$OpenBSD$
--- doc/README.openbsd.orig	Sun Sep  3 17:54:10 2006
+++ doc/README.openbsd	Sun Sep  3 18:04:48 2006
@@ -0,0 +1,89 @@
+Boehm-gc for OpenBSD
+====================
+This port has been adapted from an earlier boehm-gc 6.5 port done for the cacao-0.95 jvm.
+It has been tested on OpenBSD-4.0-beta; it will probably work on -3.9
+
+The Boehm-gc 6.x code is "mature" but has become highly Linux centric.
+Not exclusively, mind you, but just enough to make a port much more troublesome.
+The last OpenBSD port was for boehm-gc6.2 -- which lacked pthread support and 
+object finalization, both needed for modern Java Virtual Machines.
+
+This port has only been tested on i386.  Testing on amd64 and macppc will require careful
+reassessment of configuration parameters.
+
+Parallel and Incremental collection are not enabled.
+
+There are a number of patches, especially in the pthread_stop_world.c and
+pthread_support.c modules.  These reference libpthread internals, specifically struct pthread.
+
+Boehm-gc is used in three alternative JVM implementations: Cacao, Kaffe, and GCJ
+
+PREREQUSITE
+===========
+You must have /usr/src/lib/libc and /usr/src/lib/libpthread source in order to build port.
+
+You do not need to have built the corresponding userland binaries, you only need to have the
+correct header files in the proper relative positions under /usr/src.
+
+cd /usr
+cvs -d your-favorite-repository-mirror co src/lib/libpthread src/lib/libc
+
+The port will not configure without these files.
+
+USAGE
+=====
+Use -lgc to link
+Use <gc.h> to compile; This must be used in all modules with references to pthread functions.
+
+TESTING
+=======
+You can run the test program tests/test.c using:
+
+gmake -f Makefile.openbsd
+
+which will produce the program xtest; This puts the collector through it's paces
+when built against the local (uninstalled) compile.  It tests multi-threaded operation.
+
+Other programs in the tests/ directory can be used with the installed version.
+
+You can change the debug parameters without modifing the ports Makefile as modeled 
+in Makefile.openbsd; it should not segfault or terminate early with errors mentioning failed tests
+
+Note that test.c was patched to reduce the size of lists used in the test; this is directly
+related to the size of the thread's stack.
+
+OpenBSD Extensions
+==================
+
+Boehm-GC wants to use signals to suspend the execution of independent threads.
+Instead, we use the OpenBSD pthread_suspend_all_np() and pthread_resume_all_np() routines.
+
+However, there are signal handlers still active, and some applications may want or need to
+intercept signals.  The new API
+
+void GC_callback(
+	int (*GC_suspend_handler_callback)(void*),
+	void (*GC_lock_stopworld_callback)(int),
+	void (*GC_unlock_stopworld_callback)() )
+
+takes three functions to act as callbacks.
+
+You can see where these are used in pthread_stop_world.c
+
+GC_suspend_handler is called when the main GC signal handler is called; it passes the ucontext.
+GC_lock_stopworld(int) is called when the GC is about to suspend all threads in preparation for a GC.
+GC_unlock_stopworld() is marks the end of the GC; all the threads have been restarted.
+
+(void*) 0 supplied for any will not affect the current callback.
+(void*)-1 supplied for any will reset to the default handler.
+
+int GC_Signum1()
+int GC_Signum2()
+	both return the signal numbers trapped by the GC
+
+	The signal numbered SIG_SUSPEND is supposed to be used to suspend a thread;
+	The signal numbered SIG_THR_RESTART is supposed to be used to restart a thread;
+
+	(Neither of these signals are used this way in reality.)
+
+	The symbols SIG_SUSPEND and SIG_THR_RESTART are defined in include/private/gc_priv.h
