initial import of NetBSD tree

1 files changed, 85 insertions, 0 deletions

diff --git a/lib/libpthread/README b/lib/libpthread/README
new file mode 100644
index 00000000000..f546325d948
--- /dev/null
+++ b/lib/libpthread/README
@@ -0,0 +1,85 @@
+This pthread package is/will be based on the POSIX1003.4a Draft 7 pthread
+standard, and Frank Mullers paper on signal handelling presented
+at the Winter 93 USENIX conference.
+
+It is currently being designed and written by me, Chris Provenzano.
+All bug, comments, and questions can be sent me at either
+proven@athena.mit.edu or proven@sun-lamp.cs.berkeley.edu
+PLEASE, don't send questions, bugs or patches to any of the *BSD* mailing lists.
+
+Thanks goes to John Carr jfc@mit.edu for porting this to the IBM/RT,
+and for his bug reports and fixes, Greg Hudson and Mark Eichin for the
+testing they've done, and all the others.
+
+PORTING
+One of the goals of this user space implementation of pthreads is that it
+be portable. I have minimized the ammount of assembler code necessary,
+but some is.
+
+If you want to port it to another platform here are a few basic hints.
+
+There are currently three files you'll have to creat for your
+architecture, machdep.h, machdep.c and syscall.S.
+The first two are necessary to get the context switch section of
+the pthread package running, the third is for all the syscalls.
+
+To do an initial port, create an appropriate machdep.h, and machdep.c
+and define PTHREAD_INITIAL_PORT in the Makefile
+
+Comment out references to the stdio package.
+
+INCLUDE FILES AND PORTING
+To continue to make this package portable, some basic rules on includes
+files must be followed.
+
+pthread.h should be included first (if it is to be included).
+machdep.h should define size_t if the system doesn't define it already
+
+posix.h should be included last. This file is used to correct non
+POSIX features, after everything else has been defined.
+
+INTERNAL LOCKING
+To prevent deadlocks the following rules were used for locks.
+
+1.	Local locks for mutex queues and other like things are only locked
+	by running threads, at NO time will a local lock be held by
+	a thread in a non running state.
+2.  Only threads that are in a run state can attempt to lock another thread,
+	this way, we can assume that the lock will be released shortly, and don't
+	have to unlock the local lock.
+3.	The only time a thread will have a pthread->lock and is not in a run
+	state is when it is in the reschedule routine.
+4.	The reschedule routine assumes all local locks have been released,
+	there is a lock on the currently running thread (pthread_run),
+	and that this thread is being rescheduled to a non running state.
+	It is safe to unlock the currently running threads lock after it
+	has been rescheduled.
+5.	The reschedule routine locks the kernel, sets the state of the currently
+	running thread, unlocks the currently running thread, calls the
+	context switch routines.
+6	the kernel lock is used only ...
+
+
+7.	The order of locking is ...
+
+1 local locks
+2 pthread->lock			/* Assumes it will get it soon */
+3 pthread_run->lock		/* Assumes it will get it soon, but must release 2 */
+4 kernel lock			/* Currently assumes it will ALWAYS get it. */
+
+8.	The kernel lock will be changed to a spin lock for systems that
+already support kernel threads, this way we can mutiplex threads onto
+kernel threads.
+9.	There are points where the kernel is locked and it needs to get
+either a local lock or a pthread lock, if at these points the code
+fails to get the lock the kernel gives up and sets a flag which will
+be checked at a later point.
+10.	Interrupts are dissabled while the kernel is locked, the interrupt
+mask must be checked afterwards or cleared in some way, after interrputs
+have been reenabled, this allows back to back interrupts, but should always
+avoid missing one.
+
+Copyright (c) 1993 Chris Provenzano. All rights reserved.
+
+This product includes software developed by the Univeristy of California,
+Berkeley and its contributors.