Porting NSPR to Unix Platforms

From MDC

Last modified 16 July 1998

<<< Under construction >>>

Unix platforms are probably the easiest platforms to port NetScape Portable Runtime (NSPR) to. However, if you are not familiar with the structure of the NSPR source tree and its build system, it may take you extra time. Therefore I write this article to document the more mechanical part of the Unix porting task. For certain more "standard" Unix platforms, this may be all you have to do. On other platforms, you may need to do extra work to deal with their idiosyncrasies.

[edit] Porting Instructions

You can use different threading packages to implement NSPR threads. NSPR has a user-level threading library where thread context switches are done by setjmp/longjmp or sigsetjmp/siglongjmp. This is called the local threads only version of classic NSPR. You should attempt to do a local threads only port first. The classic NSPR source files are in mozilla/nsprpub/pr/src/threads and mozilla/nsprpub/pr/src/io.

If the platform has pthreads, you can also use pthreads as an implementation strategy. This is referred to as pthreads NSPR. Pthreads NSPR has relatively orthogonal source code in the thread management, thread synchronization, and I/O area. The pthreads source files are in mozilla/nsprpub/pr/src/pthreads.

I use the NetBSD port I recently received as an example to illustrate the mechanical part of the porting process.

There are a few new files you need to add:

mozilla/nsprpub/config/NetBSD.mk 

The name of this file is the return value of uname -s on the platform, plus the file suffix .mk. If the return value of uname -s is too long or ambiguous, you can modify it in mozilla/nsprpub/config/arch.mk (the makefile variable OS_ARCH).

mozilla/nsprpub/pr/include/md/_netbsd.cfg 

We have a program mozilla/nsprpub/pr/include/gencfg.c to help you generate partof this file. You can build the gencfg tool as follows:

cd mozilla/nsprpub/pr/include
gmake gencfg
gencfg > foo.bar

Then you use the macro values in foo.bar as a basis for the _xxxos.cfg file.

• mozilla/nsprpub/pr/include/md/_netbsd.h: For local threads only version, the main challenge is to figure out how to define the three thread context switch macros. In particular, you need to figure out which element in the jmp_buf is the stack pointer. Usually jmp_buf is an array of integers, and some platforms have a JB_SP macro that tells you which array element is the stack pointer. If you can't find a JB_SP macro, you must resort to brute-force experiments. I usually print out every element in the jmp_buf and see which one is the closest to the address of a local variable (local variables are allocated on the stack). On some platforms, jmp_buf is a struct, then you should look for a struct member named sp or something similar.

• mozilla/nsprpub/pr/src/md/unix/netbsd.c

You need to modify the following existing files:

• mozilla/nsprpub/pr/include/md/Makefile
• mozilla/nsprpub/pr/include/md/_unixos.h: Just fix the compiling errors, usually pointed out by the #error preprocessor directives we inserted.
• mozilla/nsprpub/pr/include/md/prosdep.h
• mozilla/nsprpub/pr/src/md/prosdep.c
• mozilla/nsprpub/pr/src/md/unix/Makefile
• mozilla/nsprpub/pr/src/md/unix/objs.mk
• mozilla/nsprpub/pr/src/md/unix/unix.c: Just fix the compiling errors, usually pointed out by the #error preprocessor directives we inserted

For a pthreads port, you need to modify the following files:

• mozilla/nsprpub/pr/include/md/_pth.h
• Files in mozilla/nsprpub/pr/src/pthreads, most likely ptthread.c and ptio.c

[edit] Testing Your Port

We have some unit tests in mozilla/nsprpub/pr/tests. First a warning: some of the tests are broken. Further, we don't have documentation of our unit tests, so you often need to resort to read the source code to understand what they do. Some of them respond to the -h command line option and print a usage message. Henry Sobotka of the OS/2 Mozilla porting project has a web page at http://www.axess.com/users/sobotka/nsprtest/warpztjs.html with good documentation of the NSPR unit tests.

Here are my favorite tests.

For thread management and synchronization:

• cvar -d
• cvar2
• ./join -d
• perf
• ./switch -d
• intrupt -d

For I/O:

• cltsrv -d, cltsrv -Gd
• socket
• testfile -d
• tmocon -d
• 'tmoacc -d' in conjunction with 'writev -d'

Miscellaneous:

• dlltest -d
• forktest

[edit] Original Document Information