Rename doc folder to docs

* CMakeLists.txt [enable_docs] (CMAKE_INSTALL_DOCDIR): Rename doc
folder to docs.
* Makefile.am [ENABLE_DOCS] (docdocdir, dist_docdocs_DATA,
dist_docdocsplatforms_DATA): Likewise.
* Makefile.direct (CXXFLAGS): Likewise.
* README.md: Likewise.
* docs/simple_example.md (Other platforms): Likewise.
* Makefile.am [ENABLE_DOCS] (docdocdir): Rename to docdocsdir.
* Makefile.am [ENABLE_DOCS] (dist_docdoc_DATA): Rename to
dist_docdocs_DATA.
* Makefile.am [ENABLE_DOCS] (docdocplatformsdir): Rename to
docdocsplatformsdir.
* Makefile.am [ENABLE_DOCS] (dist_docdocplatforms_DATA): Rename to
dist_docdocsplatforms_DATA.
* doc/README.autoconf: Move to docs folder.
* doc/README.cmake: Likewise.
* doc/README.cords: Likewise.
* doc/README.environment: Likewise.
* doc/README.macros: Likewise.
* doc/debugging.md: Likewise.
* doc/faq.md: Likewise.
* doc/finalization.md: Likewise.
* doc/gcdescr.md: Likewise.
* doc/gcinterface.md: Likewise.
* doc/leak.md: Likewise.
* doc/overview.md: Likewise.
* doc/porting.md: Likewise.
* doc/scale.md: Likewise.
* doc/simple_example.md: Likewise.
* doc/tree.md: Likewise.
* doc/platforms/README.aix: Move to docs/platforms folder.
* doc/platforms/README.amiga: Likewise.
* doc/platforms/README.arm_cross: Likewise.
* doc/platforms/README.darwin: Likewise.
* doc/platforms/README.dgux386: Likewise.
* doc/platforms/README.emscripten: Likewise.
* doc/platforms/README.ews4800: Likewise.
* doc/platforms/README.hp: Likewise.
* doc/platforms/README.linux: Likewise.
* doc/platforms/README.mac: Likewise.
* doc/platforms/README.os2: Likewise.
* doc/platforms/README.sgi: Likewise.
* doc/platforms/README.solaris2: Likewise.
* doc/platforms/README.symbian: Likewise.
* doc/platforms/README.uts: Likewise.
* doc/platforms/README.win32: Likewise.
* doc/platforms/README.win64: Likewise.

17 files changed, 1464 insertions, 0 deletions

diff --git a/docs/platforms/README.aix b/docs/platforms/README.aix
new file mode 100644
index 00000000..f5630b20
--- /dev/null
+++ b/docs/platforms/README.aix
@@ -0,0 +1,9 @@
+We have so far failed to find a good way to determine the stack base.
+It is highly recommended that GC_stackbottom be set explicitly on program
+startup.  The supplied value sometimes causes failure under AIX 4.1, though
+it appears to work under 3.X.  HEURISTIC2 seems to work under 4.1, but
+involves a substantial performance penalty, and will fail if there is
+no limit on stack size.
+
+There is no thread support.  (I assume recent versions of AIX provide
+pthreads?  I no longer have access to a machine ...)
diff --git a/docs/platforms/README.amiga b/docs/platforms/README.amiga
new file mode 100644
index 00000000..fc9c72ab
--- /dev/null
+++ b/docs/platforms/README.amiga
@@ -0,0 +1,290 @@
+            Kjetil S. Matheussen's notes (28-11-2000)
+
+Compiles under SAS/C again. Should also still compile under other
+Amiga compilers without big changes. I haven't checked if it still
+works under gcc, because I don't have gcc for Amiga. But I have
+updated Makefile.direct, and hope it compiles fine.
+
+
+WHATS NEW:
+
+1.
+   Made a pretty big effort in preventing GC allocating-functions from
+   returning chip-mem.
+
+   The lower part of the new file AmigaOS.c does this in various ways, mainly by
+   wrapping GC_malloc, GC_malloc_atomic, GC_malloc_uncollectable,
+   GC_malloc_atomic_uncollectable, GC_malloc_ignore_off_page
+   and GC_malloc_atomic_ignore_off_page. GC_realloc is also wrapped, but
+   doesn't do the same effort in preventing to return chip-mem.
+   Other allocating-functions (e.g., GC_*_typed) can probably be
+   used without any problems, but beware that the warn hook will not be called.
+   In case of problems, don't define GC_AMIGA_FASTALLOC.
+
+   Programs using more time actually using the memory allocated
+   (instead of just allocate and free rapidly) have
+   the most to earn on this, but even gctest now normally runs twice
+   as fast and uses less memory, on my poor 8 MB machine.
+
+   The changes have only effect when there is no more
+   fast-mem left. But with the way GC works, it
+   could happen quite often. Beware that an atexit handler had to be added,
+   so using the abort() function will make a big memory-loss.
+   If you absolutely must call abort() instead of exit(), try calling
+   the GC_amiga_free_all_mem function before abort().
+
+   New Amiga-specific compilation flags:
+
+   GC_AMIGA_FASTALLOC - By NOT defining this option, GC will work like before,
+                        it will not try to force fast-mem out of the OS, and
+                        it will use normal calloc for allocation, and the rest
+                        of the following flags will have no effect.
+
+   GC_AMIGA_ONLYFAST - Makes GC never to return chip-mem. GC_AMIGA_RETRY have
+                       no effect if this flag is set.
+
+   GC_AMIGA_GC - If gc returns NULL, do a GC_gcollect, and try again. This
+                 usually is a success with the standard GC configuration.
+                 It is also the most important flag to set to prevent
+                 GC from returning chip-mem. Beware that it slows down a lot
+                 when a program is rapidly allocating/deallocating when
+                 there's either very little fast-memory left or very little
+                 chip-memory left. It's not a very common situation, but gctest
+                 sometimes (very rare) use many minutes because of this.
+
+   GC_AMIGA_RETRY - If gc succeed allocating memory, but it is chip-mem,
+                    try again and see if it is fast-mem. Most of the time,
+                    it will actually return fast-mem for the second try.
+                    I have set max number of retries to 9 or size/5000. You
+                    can change this if you like. (see GC_amiga_rec_alloc())
+
+   GC_AMIGA_PRINTSTATS - Gather some statistics during the execution of a
+                         program, and prints out the info when the atexit-handler
+                         is called.
+
+   My recommendation is to set all this flags, except GC_AMIGA_PRINTSTATS and
+   GC_AMIGA_ONLYFAST.
+
+   If your program demands high response-time, you should
+   not define GC_AMIGA_GC, and possible also define GC_AMIGA_ONLYFAST.
+   GC_AMIGA_RETRY does not seem to slow down much.
+
+   Also, when compiling up programs, and GC_AMIGA_FASTALLOC was not defined when
+   compiling gc, you can define GC_AMIGA_MAKINGLIB to avoid having these allocation-
+   functions wrapped. (see gc.h)
+
+   Note that GC_realloc must not be called before any of
+   the other above mentioned allocating-functions have been called. (shouldn't be
+   any programs doing so either, I hope).
+
+   Another note. The allocation-function is wrapped when defining
+   GC_AMIGA_FASTALLOC by letting the function go thru the new
+   GC_amiga_allocwrapper_do function-pointer (see gc.h). Means that
+   sending function-pointers, such as GC_malloc, GC_malloc_atomic, etc.,
+   for later to be called, e.g., like this, (*GC_malloc_function_pointer)(size),
+   will not wrap the function. This is normally not a big problem, unless
+   all allocation function is called like this, which will cause the
+   atexit un-allocating function never to be called. Then you either
+   have to manually add the atexit handler, or call the allocation-
+   functions function-pointer functions like this;
+   (*GC_amiga_allocwrapper_do)(size,GC_malloc_function_pointer).
+   There are probably better ways this problem could be handled, unfortunately,
+   I didn't find any without rewriting or replacing a lot of the GC-code, which
+   I really didn't want to. (Making new GC_malloc_* functions, and just
+   defining, e.g., GC_malloc as GC_amiga_malloc should work too).
+
+
+   New Amiga-specific function:
+
+     void GC_amiga_set_toany(void (*func)(void));
+
+   'func' is a function that will be called right before gc has to change
+   allocation-method from MEMF_FAST to MEMF_ANY. I.e., when it is likely
+   it will return chip-mem.
+
+
+2. A few small compiler-specific additions to make it compile with SAS/C again.
+
+3. To build the collector with SAS/C, create SMakefile including the following
+   specific content:
+
+IGNORE= IGNORE=85 IGNORE=154 IGNORE=161 IGNORE=100
+OPTIMIZE=optimize optimizetime optglobal optimizerdepth=100 optimizerpeephole optloop OPTSCHED optimizerinlocal optimizerrecurdepth=100
+OPT= $(OPTIMIZE) NOSTACKCHECK MAPHUNK NOVERSION NOICONS nodebug parm=reg
+
+DEFINE __USE_SYSBASE DEFINE AMIGA_SKIP_SEG DEFINE GC_ATOMIC_UNCOLLECTABLE
+DEFINE GC_AMIGA_FASTALLOC GC_AMIGA_RETRY GC_AMIGA_PRINTSTATS GC_AMIGA_GC
+
+DEFINE GC_AMIGA_MAKINGLIB
+DEFINE AMIGA IGNORE=100 IGNORE=161
+
+
+STILL MISSING:
+
+Programs can not be started from workbench, at least not for SAS/C. (Martin
+Tauchmanns note about that it now works with workbench is definitely wrong
+when concerning SAS/C).  An iconx-script solves this problem.
+
+
+BEWARE!
+
+-To run gctest, set the stack to around 200000 bytes first.
+-SAS/C-specific: cord will crash if you compile gc.lib with
+ either parm=reg or parm=both. (missing legal prototypes for
+ function-pointers someplace is the reason I guess.).
+
+
+tested with software: Radium, http://www.stud.ifi.uio.no/~ksvalast/radium/
+tested with hardware: MC68060
+
+
+                           Martin Tauchmann's notes             (1-Apr-99)
+
+Works now, also with the GNU-C compiler V2.7.2.1. <ftp://ftp.unina.it/pub/amiga/geekgadgets/amiga/m68k/snapshots/971125/amiga-bin/>
+Modify the `Makefile.direct`
+CC=cc $(ABI_FLAG)
+to
+CC=gcc $(ABI_FLAG)
+
+TECHNICAL NOTES
+
+- `GC_get_stack_base()`, `GC_register_data_segments()` works now with every
+   C compiler; also Workbench.
+
+- Removed AMIGA_SKIP_SEG, but the Code-Segment must not be scanned by GC.
+
+
+PROBLEMS
+- When the Linker, does`t merge all Code-Segments to an single one. LD of GCC
+  do it always.
+
+- With ixemul.library V47.3, when an GC program launched from another program
+  (example: `Make` or `if_mach M68K AMIGA gctest`), `GC_register_data_segments()`
+  found the Segment-List of the caller program.
+  Can be fixed, if the run-time initialization code (for C programs, usually *crt0*)
+  support `__data` and `__bss`.
+
+- PowerPC Amiga currently not supported.
+
+- Dynamic libraries (dyn_load.c) not supported.
+
+
+TESTED WITH SOFTWARE
+
+`Optimized Oberon 2 C` (oo2c) <http://cognac.informatik.uni-kl.de/download/index.html>
+
+
+TESTED WITH HARDWARE
+
+MC68030
+
+
+                           Michel Schinz's notes
+
+WHO DID WHAT
+
+The original Amiga port was made by Jesper Peterson. I (Michel Schinz)
+modified it slightly to reflect the changes made in the new official
+distributions, and to take advantage of the new SAS/C 6.x features. I also
+created a makefile to compile the "cord" package (see the cord
+subdirectory).
+
+TECHNICAL NOTES
+
+In addition to Jesper's notes, I have the following to say:
+
+- gctest checks to see if the code segment is added to the root set or not,
+  and complains if it is. The only problem is that, as far as I know, it is
+  impossible to know which segments are code segments and which are data
+  segments (there are indeed solutions to this problem, like scanning the
+  program on disk or patch the LoadSeg functions, but they are rather
+  complicated). The solution I have chosen (see os_dep.c) is to test whether
+  the program counter is in the segment we are about to add to the root set,
+  and if it is, to skip the segment. The problems are that this solution is
+  rather awkward and that it works only for one code segment. This means that
+  if your program has more than one code segment, all of them but one will be
+  added to the root set. This isn't a big problem in fact, since the
+  collector will continue to work correctly, but it may be slower.
+
+  Anyway, the code which decides whether to skip a segment or not can be
+  removed simply by not defining AMIGA_SKIP_SEG. But notice that if you do
+  so, gctest will complain (it will say that "GC_is_visible produced wrong
+  failure indication"). However, it may be useful if you happen to have
+  pointers stored in a code segment (you really shouldn't).
+
+  If anyone has a good solution to the problem of finding, when a program
+  is loaded in memory, whether a segment is a code or a data segment,
+  please let me know.
+
+
+                          Jesper Peterson's notes
+
+ADDITIONAL NOTES FOR AMIGA PORT
+
+These notes assume some familiarity with Amiga internals.
+
+WHY I PORTED TO THE AMIGA
+
+The sole reason why I made this port was as a first step in getting
+the Sather(*) language on the Amiga. A port of this language will
+be done as soon as the Sather 1.0 sources are made available to me.
+Given this motivation, the garbage collection (GC) port is rather
+minimal.
+
+(*) For information on Sather read the comp.lang.sather newsgroup.
+
+LIMITATIONS
+
+This port assumes that the startup code linked with target programs
+is that supplied with SAS/C versions 6.0 or later. This allows
+assumptions to be made about where to find the stack base pointer
+and data segments when programs are run from WorkBench, as opposed
+to running from the CLI. The compiler dependent code is all in the
+GC_get_stack_base() and GC_register_data_segments() functions, but
+may spread as I add Amiga specific features.
+
+Given that SAS/C was assumed, the port is set up to be built with
+"smake" using the "SMakefile". Compiler options in "SCoptions" can
+be set with "scopts" program. Both "smake" and "scopts" are part of
+the SAS/C commercial development system.
+
+In keeping with the porting philosophy outlined above, this port
+will not behave well with Amiga specific code. Especially not inter-
+process communications via messages, and setting up public structures like
+Intuition objects or anything else in the system lists. For the
+time being the use of this library is limited to single threaded
+ANSI/POSIX compliant or near-compliant code. (i.e., stick to stdio
+for now). Given this limitation there is currently no mechanism for
+allocating "CHIP" or "PUBLIC" memory under the garbage collector.
+I'll add this after giving it considerable thought. The major
+problem is the entire physical address space may have to me scanned,
+since there is no telling who we may have passed memory to.
+
+If you allocate your own stack in client code, you will have to
+assign the pointer plus stack size to GC_stackbottom.
+
+The initial stack size of the target program can be compiled in by
+setting the __stack symbol (see SAS documentation). It can be over-
+ridden from the CLI by running the AmigaDOS "stack" program, or from
+the WorkBench by setting the stack size in the tool types window.
+
+SAS/C COMPILER OPTIONS (SCoptions)
+
+You may wish to check the "CPU" code option is appropriate for your
+intended target system.
+
+Under no circumstances set the "StackExtend" code option in either
+compiling the library or *ANY* client code.
+
+All benign compiler warnings have been suppressed. These mainly
+involve lack of prototypes in the code, and dead assignments
+detected by the optimizer.
+
+THE GOOD NEWS
+
+The library as it stands is compatible with the GigaMem commercial
+virtual memory software, and probably similar PD software.
+
+The performance of "gctest" on an Amiga 2630 (68030 @ 25 MHz)
+compares favorably with an HP9000 with similar architecture (a 325
+with a 68030 I think).
diff --git a/docs/platforms/README.arm_cross b/docs/platforms/README.arm_cross
new file mode 100644
index 00000000..9e60dda7
--- /dev/null
+++ b/docs/platforms/README.arm_cross
@@ -0,0 +1,62 @@
+From: Margaret Fleck
+
+Here's the key details of what worked for me, in case anyone else needs them.
+There may well be better ways to do some of this, but ....
+   -- Margaret
+
+
+The badge4 has a StrongArm-1110 processor and a StrongArm-1111 coprocessor.
+
+Assume that the garbage collector distribution is unpacked into /home/arm/gc,
+which is visible to both the ARM machine and a linux desktop (e.g. via NFS mounting).
+
+Assume that you have a file /home/arm/config.site with contents something like the
+example attached below.  Notice that our local ARM toolchain lives in
+/skiff/local.
+
+Go to /home/arm/gc directory.  Do
+  CONFIG_SITE=/home/arm/config.site ./configure --target=arm-linux
+--prefix=/home/arm/gc
+
+On your desktop, do:
+   make
+   make install
+The main garbage collector library should now be in ../gc/lib/libgc.so.
+
+To test the garbage collector, first do the following on your desktop
+   make gctest
+   ./gctest
+Then do the following on the ARM machine
+   cd .libs
+   ./lt-gctest
+
+Do not try to do "make check" (the usual way of running the test
+program).  This does not work and seems to erase some of the important
+files.
+
+The gctest program claims to have succeeded.  Haven't run any further tests
+with it, though I'll be doing so in the near future.
+
+-------------------------------
+# config.site for configure
+
+HOSTCC=gcc
+
+# Names of the cross-compilers
+CC=/skiff/local/bin/arm-linux-gcc
+CXX=/skiff/local/bin/arm-linux-gcc
+
+# The cross compiler specific options
+CFLAGS="-O2 -fno-exceptions"
+CXXFLAGS="-O2 -fno-exceptions"
+CPPFLAGS="-O2 -fno-exceptions"
+LDFLAGS=""
+
+# Some other programs
+AR=/skiff/local/bin/arm-linux-ar
+RANLIB=/skiff/local/bin/arm-linux-ranlib
+NM=/skiff/local/bin/arm-linux-nm
+ac_cv_path_NM=/skiff/local/bin/arm-linux-nm
+ac_cv_func_setpgrp_void=yes
+x_includes=/skiff/local/arm-linux/include/X11
+x_libraries=/skiff/local/arm-linux/lib/X11
diff --git a/docs/platforms/README.darwin b/docs/platforms/README.darwin
new file mode 100644
index 00000000..32a5fb17
--- /dev/null
+++ b/docs/platforms/README.darwin
@@ -0,0 +1,81 @@
+Darwin/MacOSX Support - December 16, 2003
+
+== Build Notes ==
+
+Building can be done with autoconf as normal. If you want to build
+a Universal library using autoconf, you need to disable dependency
+tracking and specify your desired architectures in CFLAGS:
+
+CFLAGS="-arch ppc -arch i386 -arch x86_64" ./configure --disable-dependency-tracking
+
+
+== Important Usage Notes ==
+
+GC_INIT() MUST be called before calling any other GC functions. This
+is necessary to properly register segments in dynamic libraries. This
+call is required even if you code does not use dynamic libraries as the
+dyld code handles registering all data segments.
+
+When your use of the garbage collector is confined to dylibs and you
+cannot call GC_INIT() before your libraries' static initializers have
+run and perhaps called GC_malloc(), create an initialization routine
+for each library to call GC_INIT(), e.g.:
+
+#include "gc.h"
+extern "C" void my_library_init() { GC_INIT(); }
+
+Compile this code into a my_library_init.o, and link it into your
+dylib. When you link the dylib, pass the -init argument with
+_my_library_init (e.g. gcc -dynamiclib -o my_library.dylib a.o b.o c.o
+my_library_init.o -init _my_library_init). This causes
+my_library_init() to be called before any static initializers, and
+will initialize the garbage collector properly.
+
+Note: It doesn't hurt to call GC_INIT() more than once, so it's best,
+if you have an application or set of libraries that all use the
+garbage collector, to create an initialization routine for each of
+them that calls GC_INIT(). Better safe than sorry.
+
+Thread-local GC allocation will not work with threads that are not
+created using the GC-provided override of pthread_create(). Threads
+created without the GC-provided pthread_create() do not have the
+necessary data structures in the GC to store this data.
+
+
+== Implementation Information ==
+
+Darwin/MacOSX support is nearly complete. Thread support is reliable on
+Darwin 6.x (MacOSX 10.2) and there have been reports of success on older
+Darwin versions (MacOSX 10.1). Shared library support had also been
+added and the gc can be run from a shared library.
+
+Thread support is implemented in terms of mach thread_suspend and
+thread_resume calls. These provide a very clean interface to thread
+suspension. This implementation doesn't rely on pthread_kill so the
+code works on Darwin < 6.0 (MacOSX 10.1). All the code to stop and
+start the world is located in darwin_stop_world.c.
+
+Since not all uses of the GC enable clients to override pthread_create()
+before threads have been created, the code for stopping the world has
+been rewritten to look for threads using Mach kernel calls. Each
+thread identified in this way is suspended and resumed as above. In
+addition, since Mach kernel threads do not contain pointers to their
+stacks, a stack-walking function has been written to find the stack
+limits. Given an initial stack pointer (for the current thread, a
+pointer to a stack-allocated local variable will do; for a non-active
+thread, we grab the value of register 1 (on PowerPC)), it
+will walk the PPC Mach-O-ABI compliant stack chain until it reaches the
+top of the stack. This appears to work correctly for GCC-compiled C,
+C++, Objective-C, and Objective-C++ code, as well as for Java
+programs that use JNI. If you run code that does not follow the stack
+layout or stack pointer conventions laid out in the PPC Mach-O ABI,
+then this will likely crash the garbage collector.
+
+Mach has a very clean interface to exception handing. So, the current
+implementation of the incremental collection uses Mach's exception handling.
+
+Much thanks goes to Andrew Stone, Dietmar Planitzer, Andrew Begel,
+Jeff Sturm, and Jesse Rosenstock for all their work on the
+Darwin/OS X port.
+
+-Brian Alliet
diff --git a/docs/platforms/README.dgux386 b/docs/platforms/README.dgux386
new file mode 100644
index 00000000..0c5b077c
--- /dev/null
+++ b/docs/platforms/README.dgux386
@@ -0,0 +1,39 @@
+    Garbage Collector (parallel version) for x86 DG/UX Release R4.20MU07
+
+
+     *READ* the file README.md first.
+
+     You need the GCC-3.0.3 rev (DG/UX) compiler to build this tree.
+     This compiler has the new "dgux386" threads package implemented.
+     It also supports the switch "-pthread" needed to link correctly
+     the DG/UX's -lrte -lthread with -lgcc and the system's -lc.
+     Finally, we support parallel mark for the SMP DG/UX machines.
+     To build the garbage collector do:
+
+      ./configure
+      make
+      make gctest
+
+     Before you run "gctest" you need to set your LD_LIBRARY_PATH
+     correctly so that "gctest" can find the shared library libgc.
+     Alternatively you can do a configuration
+
+      ./configure --disable-shared
+
+     to build only the static version of libgc.
+
+     To enable debugging messages please do:
+     1) Add the "--enable-gc-debug" flag during configuration.
+     2) Pass "CFLAGS=-DDEBUG_THREADS" to "make".
+
+     In a machine with 4 CPUs (my own machine), parallel mark makes
+     a BIG difference.
+
+     Takis Psarogiannakopoulos
+
+Note (HB):
+     The integration of this patch is currently not complete.
+     The following patches against 6.1alpha3 where hard to move
+     to alpha4, and are not integrated.  There may also be minor
+     problems with stylistic corrections made by me.
+[The diff for ltconfig and ltmain.sh was removed from this file on 2011-08-22]
diff --git a/docs/platforms/README.emscripten b/docs/platforms/README.emscripten
new file mode 100644
index 00000000..c869f19a
--- /dev/null
+++ b/docs/platforms/README.emscripten
@@ -0,0 +1,15 @@
+
+The build system (at least autotools-based) should detect and configure
+emscripten correctly.
+
+As of now, gctest almost passes, except for the tests that involve a_get().
+
+No thread support for now. No idea how to stop other threads (perhaps we need
+support from JS side).
+
+How to build:
+
+    # source EMSDK first
+    emconfigure ./configure
+    emmake make gctest.html
+    # point your browser at .libs/gctest.html
diff --git a/docs/platforms/README.ews4800 b/docs/platforms/README.ews4800
new file mode 100644
index 00000000..83e8b1e0
--- /dev/null
+++ b/docs/platforms/README.ews4800
@@ -0,0 +1,81 @@
+GC on EWS4800
+-------------
+
+1. About EWS4800
+
+ EWS4800 is a 32/64-bit workstation.
+
+     Vendor: NEC Corporation
+     OS: UX/4800 R9.* - R13.* (SystemV R4.2)
+     CPU: R4000, R4400, R10000 (MIPS)
+
+2. Compiler
+
+ 32-bit:
+   Use ANSI C compiler.
+     CC = /usr/abiccs/bin/cc
+
+ 64-bit:
+   Use the 64-bit ANSI C compiler.
+     CC = /usr/ccs64/bin/cc
+     AR = /usr/ccs64/bin/ar
+
+3. ELF file format
+   *** Caution: The following information is empirical. ***
+
+ 32-bit:
+   ELF file has a unique format. (See a.out(4) and end(3C).)
+
+     &_start
+        :      text segment
+     &etext
+     DATASTART
+        :      data segment (initialized)
+     &edata
+     DATASTART2
+        :      data segment (uninitialized)
+     &end
+
+   Here, DATASTART and DATASTART2 are macros of GC, and are defined as
+   the following equations. (See include/private/gcconfig.h.)
+   The algorithm for DATASTART is similar with the function
+   GC_SysVGetDataStart() in os_dep.c.
+
+     DATASTART  = ((&etext + 0x3ffff) & ~0x3ffff) + (&etext & 0xffff)
+
+    Dynamically linked:
+     DATASTART2 = (&_gp + 0x8000 + 0x3ffff) & ~0x3ffff
+
+    Statically linked:
+     DATASTART2 = &edata
+
+   GC has to check addresses both between DATASTART and &edata, and
+   between DATASTART2 and &end. If a program accesses between &etext
+   and DATASTART, or between &edata and DATASTART2, the segmentation
+   error occurs and the program stops.
+
+   If a program is statically linked, there is not a gap between
+   &edata and DATASTART2. The global symbol &_DYNAMIC_LINKING is used
+   for the detection.
+
+ 64-bit:
+   ELF file has a simple format. (See end(3C).)
+
+     _ftext
+        :      text segment
+     _etext
+     _fdata = DATASTART
+        :      data segment (initialized)
+     _edata
+     _fbss
+        :      data segment (uninitialized)
+     _end = DATAEND
+
+--
+Hironori SAKAMOTO
+
+
+When using the new "configure; make" build process, please
+run configure with the --disable-shared option.  "Make check" does not
+yet pass with dynamic libraries.  The reasons for that are not yet
+understood.  (HB, paraphrasing message from Hironori SAKAMOTO.)
diff --git a/docs/platforms/README.hp b/docs/platforms/README.hp
new file mode 100644
index 00000000..cc31b18d
--- /dev/null
+++ b/docs/platforms/README.hp
@@ -0,0 +1,18 @@
+Dynamic loading support requires that executables be linked with -ldld.
+The alternative is to build the collector without defining DYNAMIC_LOADING
+in gcconfig.h and ensuring that all garbage collectible objects are
+accessible without considering statically allocated variables in dynamic
+libraries.
+
+The collector should compile with either plain cc or cc -Ae.  Cc -Aa
+fails to define _HPUX_SOURCE and thus will not configure the collector
+correctly.
+
+Incremental collection support was added recently, and should now work.
+
+In spite of past claims, pthread support under HP/UX 11 should now work.
+Define GC_THREADS macro for the build.  Incremental collection still does not
+work in combination with it.
+
+The stack finding code can be confused by putenv calls before collector
+initialization.  Call GC_malloc() or GC_INIT() before any putenv() calls.
diff --git a/docs/platforms/README.linux b/docs/platforms/README.linux
new file mode 100644
index 00000000..c9ced481
--- /dev/null
+++ b/docs/platforms/README.linux
@@ -0,0 +1,127 @@
+See README.alpha for Linux on DEC AXP info.
+
+This file applies mostly to Linux/Intel IA-32.  Ports to Linux on an M68K,
+IA-64, SPARC, MIPS, Alpha and PowerPC are integrated too.  They should behave
+similarly, except that the PowerPC port lacks incremental GC support, and
+it is unknown to what extent the Linux threads code is functional.
+See below for M68K specific notes.
+
+Incremental GC is generally supported.
+
+Dynamic libraries are supported on an ELF system.
+
+The collector appears to work reliably with Linux threads, but beware
+of older versions of glibc and gdb.
+
+The garbage collector uses SIGPWR and SIGXCPU if it is used with
+Linux threads.  These should not be touched by the client program.
+
+To use threads, you need to abide by the following requirements:
+
+1) You need to use LinuxThreads or NPTL (which are included in libc6).
+
+   The collector relies on some implementation details of the LinuxThreads
+   package.  This code may not work on other
+   pthread implementations (in particular it will *not* work with
+   MIT pthreads).
+
+2) You must compile the collector with "-DGC_THREADS -D_REENTRANT" specified
+   in the Makefile.direct file.
+
+3a) Every file that makes thread calls should define GC_THREADS, and then
+   include gc.h.  The latter redefines some of the pthread primitives as
+   macros which also provide the collector with information it requires.
+
+3b) A new alternative to (3a) is to build the collector and compile GC clients
+   with -DGC_USE_LD_WRAP, and to link the final program with
+
+   (for ld) --wrap dlopen --wrap pthread_create \
+            --wrap pthread_join --wrap pthread_detach \
+            --wrap pthread_sigmask --wrap pthread_exit --wrap pthread_cancel
+
+   (for gcc) -Wl,--wrap -Wl,dlopen -Wl,--wrap -Wl,pthread_create \
+             -Wl,--wrap -Wl,pthread_join -Wl,--wrap -Wl,pthread_detach \
+             -Wl,--wrap -Wl,pthread_sigmask -Wl,--wrap -Wl,pthread_exit \
+             -Wl,--wrap -Wl,pthread_cancel
+
+   In any case, _REENTRANT should be defined during compilation.
+
+4) Dlopen() disables collection during its execution.  (It can't run
+   concurrently with the collector, since the collector looks at its
+   data structures.  It can't acquire the allocator lock, since arbitrary
+   user startup code may run as part of dlopen().)  Under unusual
+   conditions, this may cause unexpected heap growth.
+
+5) The combination of GC_THREADS, REDIRECT_MALLOC, and incremental
+   collection is probably not fully reliable, though it now seems to work
+   in simple cases.
+
+6) Thread local storage may not be viewed as part of the root set by the
+   collector.  This probably depends on the linuxthreads version.  For the
+   time being, any collectible memory referenced by thread local storage
+   should also be referenced from elsewhere, or be allocated as uncollectible.
+   (This is really a bug that should be fixed somehow.  Actually, the
+   collector probably gets things right, on Linux at least, if there are not
+   too many tls locations and if dlopen is not used.)
+
+
+M68K LINUX:
+(From Richard Zidlicky)
+The bad news is that it can crash every linux-m68k kernel on a 68040,
+so an additional test is needed somewhere on startup. I have meanwhile
+patches to correct the problem in 68040 buserror handler but it is not
+yet in any standard kernel.
+
+Here is a simple test program to detect whether the kernel has the
+problem. It could be run as a separate check in configure or tested
+upon startup. If it fails (return !0) than mprotect can't be used
+on that system.
+
+/*
+ * test for bug that may crash 68040 based Linux
+ */
+
+#include <sys/mman.h>
+#include <signal.h>
+#include <unistd.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+
+char *membase;
+int pagesize=4096;
+int pageshift=12;
+int x_taken=0;
+
+int sighandler(int sig)
+{
+   mprotect(membase,pagesize,PROT_READ|PROT_WRITE);
+   x_taken=1;
+}
+
+main()
+{
+  long l;
+
+   signal(SIGSEGV,sighandler);
+   l=(long)mmap(NULL,pagesize,PROT_READ,MAP_PRIVATE | MAP_ANON,-1,0);
+  if (l==-1)
+     {
+       perror("mmap/malloc");
+       abort();
+     }
+  membase=(char*)l;
+    *(long*)(membase+sizeof(long))=123456789;
+  if (*(long*)(membase+sizeof(long)) != 123456789 )
+    {
+      fprintf(stderr,"writeback failed !\n");
+      exit(1);
+    }
+  if (!x_taken)
+    {
+      fprintf(stderr,"exception not taken !\n");
+      exit(1);
+    }
+  fprintf(stderr,"vmtest Ok\n");
+  exit(0);
+}
diff --git a/docs/platforms/README.mac b/docs/platforms/README.mac
new file mode 100644
index 00000000..100746b1
--- /dev/null
+++ b/docs/platforms/README.mac
@@ -0,0 +1,313 @@
+The contents of this file are old and pertain to pre-MacOSX versions.
+You probably really wanted README.darwin.
+
+---------------------------------------------
+
+Patrick Beard's Notes for building GC with CodeWarrior Pro 2:
+----------------------------------------------------------------------------
+The current build environment for the collector is CodeWarrior Pro 2.
+Projects for CodeWarrior Pro 2 (and for quite a few older versions)
+are distributed in the file Mac_projects.sit.hqx. The project file
+:Mac_projects:gc.prj builds static library versions of the collector.
+:Mac_projects:gctest.prj builds the GC test suite.
+
+Configuring the collector is still done by editing the file
+:extra:Mac_files:MacOS_config.h.
+
+Lars Farm's suggestions on building the collector:
+----------------------------------------------------------------------------
+Garbage Collection on MacOS - a manual 'MakeFile'
+-------------------------------------------------
+
+Project files and IDE's are great on the Macintosh, but they do have
+problems when used as distribution media. This note tries to provide
+porting instructions in pure TEXT form to avoid those problems. A manual
+'makefile' if you like.
+
+    Codewarrior:    CWPro1
+    date:           18 July 1997
+
+The notes may or may not apply to earlier or later versions of the CWPro.
+
+This is just to record my experiences. These notes do not mean I now
+provide a supported port of the GC to MacOS. It works for me. If it works
+for you, great. If it doesn't, sorry, try again...;-) Still, if you find
+errors, please let me know.
+
+
+Porting to MacOS is a bit more complex than it first seems. Which MacOS?
+68K/PowerPC? Which compiler? Each supports both 68K and PowerPC and offer a
+large number of (unique to each environment) compiler settings. Each
+combination of compiler/68K/PPC/settings require a unique combination of
+standard libraries. And the IDE's does not select them for you. They don't
+even check that the library is built with compatible setting and this is
+the major source of problems when porting the GC (and otherwise too).
+
+You will have to make choices when you configure the GC. I've made some
+choices here, but there are other combinations of settings and #defines
+that work too.
+
+As for target settings the major obstacles may be:
+- 68K Processor: check "4-byte Ints".
+- PPC Processor: uncheck "Store Static Data in TOC".
+
+What you need to do:
+1) Build the GC as a library
+2) Test that the library works with 'gctest.c'.
+3) Test that the C++ interface 'gc_cpp.h' works with 'tests/cpp.cc'.
+
+== 1. The Libraries ==
+
+I made one project with four targets (68K/PPC tempmem or appheap). One target
+will suffice if you're able to decide which one you want. I wasn't...
+
+Codewarrior allows a large number of compiler/linker settings. I used these:
+
+Settings shared by all targets:
+------------------------------
+o Access Paths:
+  - User Paths:   the GC folder
+  - System Paths: {Compiler}:Metrowerks Standard Library:
+                  {Compiler}:MacOS Support:Headers:
+                  {Compiler}:MacOS Support:MacHeaders:
+o C/C++ language:
+  - inlining: normal
+  - direct to SOM: off
+  - enable/check: exceptions, RTTI, bool (and if you like pool strings)
+
+PowerPC target settings
+-----------------------
+o Target Settings:
+  - name of target
+  - MacOS PPC Linker
+o PPC Target
+  - name of library
+o C/C++ language
+  - prefix file as described below
+o PPC Processor
+  - Struct Alignment: PowerPC
+  - uncheck "Store Static Data in TOC" -- important!
+    I don't think the others matter, I use full optimization and it is OK
+o PPC Linker
+  - Factory Settings (SYM file with full paths, faster linking, dead-strip
+    static init, Main: __start)
+
+
+68K target settings
+-------------------
+o Target Settings:
+  - name of target
+  - MacOS 68K Linker
+o 68K Target
+  - name of library
+  - A5 relative data
+o C/C++ language
+  - prefix file as described below
+o 68K Processor
+  - Code model: smart
+  - Struct alignment: 68K
+  - FP: SANE
+  - enable 4-Byte Ints -- important!
+    I don't think the others matter. I selected...
+  - enable: 68020
+  - enable: global register allocation
+o IR Optimizer
+  - enable: Optimize Space, Optimize Speed
+    I suppose the others would work too, but haven't tried...
+o 68K Linker
+  - Factory Settings (New Style MacsBug, SYM file with full paths,
+    A6 Frames, fast link, Merge compiler glue into segment 1,
+    dead-strip static init)
+
+Prefix Files to configure the GC sources
+----------------------------------------
+The Codewarrior equivalent of command-line compilers -DNAME=X is to use
+prefix-files. A TEXT file that is automatically #included before the first byte
+of every source file. I used these:
+
+---- ( cut here ) ----  gc_prefix_tempmem.h     -- 68K and PPC -----
+    #include "gc_prefix_common.h"
+    #undef USE_TEMPORARY_MEMORY
+    #define USE_TEMPORARY_MEMORY
+---- ( cut here ) ----  gc_prefix_appmem.h      -- 68K and PPC -----
+    #include "gc_prefix_common.h"
+    #undef USE_TEMPORARY_MEMORY
+//  #define USE_TEMPORARY_MEMORY
+
+---- ( cut here ) ----  gc_prefix_common.h      --------------------
+// gc_prefix_common.h
+// ------------------
+// Codewarrior prefix file to configure the GC libraries
+//
+//   prefix files are the Codewarrior equivalent of the
+//   command line option -Dname=x frequently seen in makefiles
+
+#if !__MWERKS__
+  #error only tried this with Codewarrior
+#endif
+
+#if macintosh
+  #define MSL_USE_PRECOMPILED_HEADERS 0
+  #include <ansi_prefix.mac.h>
+
+  //  See list of #defines to configure the library in: 'MakeFile'
+  //  see also README
+
+  #define ALL_INTERIOR_POINTERS // follows interior pointers.
+//#define DONT_ADD_BYTE_AT_END  // disables the padding if defined.
+//#define SMALL_CONFIG          // whether to use a smaller heap.
+  #define GC_ATOMIC_UNCOLLECTABLE // GC_malloc_atomic_uncollectable()
+
+  // define either or none as per personal preference
+  //   used in malloc.c
+  #define REDIRECT_MALLOC GC_malloc
+//#define REDIRECT_MALLOC GC_malloc_uncollectable
+  // if REDIRECT_MALLOC is #defined make sure that the GC library
+  // is listed before the ANSI/ISO libs in the Codewarrior
+  // 'Link order' panel
+//#define IGNORE_FREE
+
+  // mac specific configs
+//#define USE_TEMPORARY_MEMORY    // use Macintosh temporary memory.
+//#define SHARED_LIBRARY_BUILD    // build for use in a shared library.
+
+#else
+  // could build Win32 here too, or in the future
+  // Rhapsody PPC-mach, Rhapsody PPC-MacOS,
+  // Rhapsody Intel-mach, Rhapsody Intel-Win32,...
+  // ... ugh this will get messy ...
+#endif
+
+// make sure ints are at least 32-bit
+// ( could be set to 16-bit by compiler settings (68K) )
+
+struct gc_private_assert_intsize_{ char x[ sizeof(int)>=4 ? 1 : 0 ]; };
+
+#if __powerc
+  #if __option(toc_data)
+    #error turn off "store static data in TOC" when using GC
+    //     ... or find a way to add TOC to the root set...(?)
+  #endif
+#endif
+---- ( cut here ) ----  end of gc_prefix_common.h  -----------------
+
+Files to build the GC libraries:
+--------------------------------
+    extra/gc.c
+    extra/MacOS.c -- contains MacOS code
+    gc_badalc.cc
+    gc_cpp.cc
+
+== 2. Test that the library works with 'gctest.c' ==
+
+The test app is just an ordinary ANSI-C console app. Make sure settings
+match the library you're testing.
+
+Files
+-----
+    gctest.c
+    the GC library to test        -- link order before ANSI libs
+    suitable Mac+ANSI libraries
+
+prefix:
+------
+---- ( cut here ) ----  gc_prefix_testlib.h     -- all libs -----
+#define MSL_USE_PRECOMPILED_HEADERS 0
+#include <ansi_prefix.mac.h>
+#undef NDEBUG
+
+#define ALL_INTERIOR_POINTERS   /* for GC_priv.h */
+---- ( cut here ) ----
+
+== 3. Test that the C++ interface 'gc_cpp.h' works with 'tests/cpp.cc' ==
+
+The test app is just an ordinary ANSI-C console app. Make sure settings match
+the library you're testing.
+
+Files
+-----
+    tests/cpp.cc
+    the GC library to test        -- link order before ANSI libs
+    suitable Mac+ANSI libraries
+
+prefix:
+------
+same as for gctest.c
+
+For convenience I used one test-project with several targets so that all
+test apps are build at once. Two for each library to test: gctest.c and
+gc_app.cc. When I was satisfied that the libraries were OK. I put the
+libraries + gc.h + the c++ interface-file in a folder that I then put into
+the MSL hierarchy so that I don't have to alter access-paths in projects
+that use the GC.
+
+After that, just add the proper GC library to your project and the GC is in
+action! malloc will call GC_malloc and free GC_free, new/delete too. You
+don't have to call free or delete. You may have to be a bit cautious about
+delete if you're freeing other resources than RAM. See gc_cpp.h. You can
+also keep coding as always with delete/free. That works too. If you want,
+include "gc.h" and tweak its use a bit.
+
+== Symantec SPM ==
+
+It has been a while since I tried the GC in SPM, but I think that the above
+instructions should be sufficient to guide you through in SPM too. SPM
+needs to know where the global data is. Use the files 'datastart.c' and
+'dataend.c'. Put 'datastart.c' at the top of your project and 'dataend.c'
+at the bottom  of your project so that all data is surrounded. This is not
+needed in Codewarrior because it provides intrinsic variables
+__datastart__, __data_end__ that wraps all globals.
+
+
+   It worked for me, hope it works for you.
+
+   Lars Farm
+----------------------------------------------------------------------------
+
+
+Patrick Beard's instructions (may be dated):
+
+The collector should run under Symantec C++/THINK C v7.0.4, and
+Metrowerks C/C++ v4.5 both 68K and PowerPC. Project files are provided
+to build and test the collector under both development systems.
+
+Configuration
+-------------
+
+To configure the collector, under both development systems, a prefix file
+is used to set preprocessor directives. This file is called "MacOS_config.h".
+
+Testing
+-------
+
+To test the collector (always a good idea), build one of the gctest projects,
+gctest. (Symantec C++/THINK C), mw/gctest.68K, or mw/gctest.PPC.  The
+test will ask you how many times to run; 1 should be sufficient.
+
+Building
+--------
+
+For your convenience project files for the major Macintosh development
+systems are provided.
+
+For Symantec C++/THINK C, you must build the two projects gclib-1 and
+gclib-2. It has to be split up because the collector has more than 32 KB
+of static data and no library can have more than this in the Symantec
+environment. (Future versions will probably fix this.)
+
+For Metrowerks C/C++ 4.5 you build gc.68K/PPC and the result will
+be a library called gc.68K.lib/gc.PPC.lib.
+
+Using
+-----
+
+Under Symantec C++/THINK C, you can just add the gclib-1 and gclib-2
+projects to your own project. Under Metrowerks, you add gc.68K.lib or
+gc.PPC.lib and two additional files. You add the files called datastart.c
+and dataend.c to your project, bracketing all files that use the collector.
+See mw/gctest for an example.
+
+Include the projects/libraries you built above into your own project,
+#include "gc.h", and call GC_malloc. You don't have to call GC_free.
+
+Patrick C. Beard
diff --git a/docs/platforms/README.os2 b/docs/platforms/README.os2
new file mode 100644
index 00000000..fbd9c811
--- /dev/null
+++ b/docs/platforms/README.os2
@@ -0,0 +1,13 @@
+The code assumes static linking, and a single thread.  The editor de has
+not been ported; the cord test program has.  The supplied WCC_MAKEFILE should
+work for OS/2 but was not tested on.
+
+Since we haven't figured out how to do partial linking or to build static
+libraries, clients currently need to link against a long list of executables.
+
+Notes:
+* adding dynamic linking support seems easy, but was not done;
+* adding thread support may be nontrivial, since we have not yet figured out
+  how to look at another thread's registers;
+* setjmp_test may yield overly optimistic results when compiled without
+  optimization.
diff --git a/docs/platforms/README.sgi b/docs/platforms/README.sgi
new file mode 100644
index 00000000..4258dce4
--- /dev/null
+++ b/docs/platforms/README.sgi
@@ -0,0 +1,39 @@
+Performance of the incremental collector can be greatly enhanced with
+-DNO_EXECUTE_PERMISSION.
+
+The collector should run with all of the -32, -n32 and -64 ABIs.  Remember to
+define the AS macro in the Makefile.direct to be "as -64", or "as -n32".
+
+If you use -DREDIRECT_MALLOC=GC_malloc with C++ code, your code should make
+at least one explicit call to malloc instead of new to ensure that the proper
+version of malloc is linked in.
+
+Sproc threads are not supported.
+
+Pthreads support is provided.  This requires that:
+
+1) You compile the collector with -DGC_THREADS specified in Makefile.direct.
+
+2) You have the latest pthreads patches installed.
+
+(Though the collector makes only documented pthread calls,
+it relies on signal/threads interactions working just right in ways
+that are not required by the standard.  It is unlikely that this code
+will run on other pthreads platforms.  But please tell me if it does.)
+
+3) Every file that makes thread calls should define GC_THREADS and then
+include gc.h.  Gc.h redefines some of the pthread primitives as macros which
+also provide the collector with information it requires.
+
+4) pthread_cond_wait and pthread_cond_timedwait should be prepared for
+premature wakeups.  (I believe the pthreads and related standards require this
+anyway.  Irix pthreads often terminate a wait if a signal arrives.
+The garbage collector uses signals to stop threads.)
+
+5) It is expensive to stop a thread waiting in IO at the time the request is
+initiated.  Applications with many such threads may not exhibit acceptable
+performance with the collector.  (Increasing the heap size may help.)
+
+6) The collector should not be compiled with -DREDIRECT_MALLOC.  This
+confuses some library calls made by the pthreads implementation, which
+expect the standard malloc.
diff --git a/docs/platforms/README.solaris2 b/docs/platforms/README.solaris2
new file mode 100644
index 00000000..8eb4b9c2
--- /dev/null
+++ b/docs/platforms/README.solaris2
@@ -0,0 +1,68 @@
+The collector supports both incremental collection and threads under
+Solaris 2.  The incremental collector normally retrieves page dirty information
+through the appropriate /proc calls.  But it can also be configured
+(by defining MPROTECT_VDB instead of PROC_VDB in gcconfig.h) to use mprotect
+and signals.  This may result in shorter pause times, but it is no longer
+safe to issue arbitrary system calls that write to the heap.
+
+Under other UNIX versions,
+the collector normally obtains memory through sbrk.  There is some reason
+to expect that this is not safe if the client program also calls the system
+malloc, or especially realloc.  The sbrk man page strongly suggests this is
+not safe: "Many library routines use malloc() internally, so use brk()
+and sbrk() only when you know that malloc() definitely will not be used by
+any library routine."  This doesn't make a lot of sense to me, since there
+seems to be no documentation as to which routines can transitively call malloc.
+Nonetheless, under Solaris2, the collector now allocates
+memory using mmap by default.  (It defines USE_MMAP in gcconfig.h.)
+You may want to reverse this decisions if you use -DREDIRECT_MALLOC=...
+
+Note:
+Before you run "make check", you need to set your LD_LIBRARY_PATH correctly
+(e.g., to "/usr/local/lib") so that tests can find the shared library
+libgcc_s.so.1.  Alternatively, you can configure with --disable-shared.
+
+SOLARIS THREADS:
+
+Unless --disable-threads option is given, threads support is on by default in
+configure.  This causes the collector to be compiled with -D GC_THREADS
+ensuring thread safety.  This assumes use of the pthread_ interface; old-style
+Solaris threads are no longer supported.  Thread-local allocation is on by
+default.  Parallel marking is on by default (it could be disabled manually
+by configure --disable-parallel-mark option).
+
+It is also essential that gc.h be included in files that call pthread_create,
+pthread_join, pthread_detach, or dlopen.  gc.h macro defines these to also do
+GC bookkeeping, etc.  gc.h must be included with GC_THREADS macro defined
+first, otherwise these replacements are not visible.  A collector built in
+this way may only be used by programs that are linked with the threads library.
+
+Unless USE_PROC_FOR_LIBRARIES is defined, dlopen disables collection
+temporarily.  In some unlikely cases, this can result in unpleasant heap
+growth.  But it seems better than the race/deadlock issues we had before.
+
+If threads are used on an x86 processor with malloc redirected to
+GC_malloc, it is necessary to call GC_INIT explicitly before forking the
+first thread.  (This avoids a deadlock arising from calling GC_thr_init
+with the allocation lock held.)
+
+There could be an issue when using gc_cpp.h in conjunction with Solaris
+threads and Sun's C++ runtime.  Apparently the overloaded new operator
+may be invoked by some iostream initialization code before threads are
+correctly initialized.  This may cause a SIGSEGV during initialization
+of the garbage collector.  Currently the only known workaround is to not
+invoke the garbage collector from a user defined global operator new, or to
+have it invoke the garbage-collector's allocators only after main has started.
+(Note that the latter requires a moderately expensive test in operator
+delete.)
+
+I encountered "symbol <unknown>: offset .... is non-aligned" errors.  These
+appear to be traceable to the use of the GNU assembler with the Sun linker.
+The former appears to generate a relocation not understood by the latter.
+The fix appears to be to use a consistent toolchain.  (As a non-Solaris-expert
+my solution involved hacking the libtool script, but I'm sure you can
+do something less ugly.)
+
+Hans-J. Boehm
+(The above contains my personal opinions, which are probably not shared
+by anyone else.)
diff --git a/docs/platforms/README.symbian b/docs/platforms/README.symbian
new file mode 100644
index 00000000..c3e0c833
--- /dev/null
+++ b/docs/platforms/README.symbian
@@ -0,0 +1,65 @@
+Instructions for Symbian:
+1. Build: use libgc.mmp (the sample for s60v3 is provided below)
+2. Limitations
+2.1. No multi-threaded support yet
+2.2. Be careful with limitation that emulator introduces: Static roots are not
+dynamically accessible (there are Symbian APIs for this purpose but are just
+stubs, returning irrelevant values).
+Consequently, on emulator, you can only use dlls or exe, and retrieve static
+roots by calling global_init_static_root per dll (or exe).
+On target, only libs are supported, because static roots are retrieved by
+linker flags, by calling global_init_static_root in main exe.
+
+
+bld.inf sample contents:
+
+PRJ_PLATFORMS
+default armv5
+
+PRJ_MMPFILES
+libgc.mmp
+
+
+libgc.mmp sample contents:
+
+TARGET libgc.dll
+
+TARGETTYPE dll
+UID 0x1000008d 0x200107C2 // check uid
+
+EXPORTUNFROZEN
+EPOCALLOWDLLDATA
+
+CAPABILITY PowerMgmt ReadDeviceData ReadUserData WriteDeviceData WriteUserData SwEvent LocalServices NetworkServices UserEnvironment
+
+MACRO ALL_INTERIOR_POINTERS
+MACRO NO_EXECUTE_PERMISSION
+MACRO USE_MMAP
+MACRO GC_ATOMIC_UNCOLLECTABLE
+MACRO GC_DONT_REGISTER_MAIN_STATIC_DATA
+MACRO GC_DLL
+MACRO JAVA_FINALIZATION
+MACRO SYMBIAN
+MACRO ENABLE_DISCLAIM
+
+USERINCLUDE .\include
+USERINCLUDE .\include\private
+
+SYSTEMINCLUDE \epoc32\include
+SYSTEMINCLUDE \epoc32\include\stdapis
+
+SOURCEPATH .
+
+SOURCE extra/gc.c
+SOURCE extra/symbian.cpp
+
+SOURCE extra/symbian/global_end.cpp
+SOURCE extra/symbian/global_start.cpp
+SOURCE extra/symbian/init_global_static_roots.cpp
+
+STATICLIBRARY libcrt0.lib
+LIBRARY libc.lib
+LIBRARY euser.lib
+LIBRARY efsrv.lib
+LIBRARY avkon.lib
+LIBRARY eikcore.lib
diff --git a/docs/platforms/README.uts b/docs/platforms/README.uts
new file mode 100644
index 00000000..6be49667
--- /dev/null
+++ b/docs/platforms/README.uts
@@ -0,0 +1,2 @@
+Alistair Crooks supplied the port.  He used Lexa C version 2.1.3 with
+-Xa to compile.
diff --git a/docs/platforms/README.win32 b/docs/platforms/README.win32
new file mode 100644
index 00000000..21d14181
--- /dev/null
+++ b/docs/platforms/README.win32
@@ -0,0 +1,215 @@
+The collector has at various times been compiled under Windows 95 and later,
+NT, and XP, with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6,
+with the GNU Win32 tools, with Borland C++ Builder, with Watcom C, with EMX,
+and with the Digital Mars compiler (DMC).
+
+For historical reasons,
+the collector test program "gctest" is linked as a GUI application,
+but does not open any windows.  Its output normally appears in the file
+"gctest.gc.log".  It may be started from the file manager.  The hour glass
+cursor may appear as long as it's running.  If it is started from the
+command line, it will usually run in the background.  Wait a few
+minutes (a few seconds on a modern machine) before you check the output.
+You should see either a failure indication or a "Collector appears to work"
+message.
+
+A toy editor (de.exe) based on cords (heavyweight
+strings represented as trees) has been ported and is included.
+It runs fine under either Win32 or win32s.  It serves as an example
+of a true Windows application, except that it was written by a
+nonexpert Windows programmer.  (There are some peculiarities
+in the way files are displayed.  The <cr> is displayed explicitly
+for standard DOS text files.  As in the UNIX version, control
+characters are displayed explicitly, but in this case as red text.
+This may be suboptimal for some tastes and/or sets of default
+window colors.)
+
+In general -DREDIRECT_MALLOC is unlikely to work unless the
+application is completely statically linked.
+
+The collector normally allocates memory from the OS with VirtualAlloc.
+This appears to cause problems under Windows NT and Windows 2000 (but
+not Windows 95/98) if the memory is later passed to CreateDIBitmap.
+To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC.
+This is currently incompatible with -DUSE_MUNMAP.  (Thanks to Jonathan
+Clark for tracking this down.  There's some chance this may be fixed
+since we now separate heap sections with an unused page.)
+
+[Threads and incremental collection are discussed near the end, below.]
+
+Microsoft Tools
+---------------
+
+For Microsoft development tools, type
+"nmake -f NT_MAKEFILE cpu=i386 disable_threads=1 enable_static=1 nodebug=1"
+to build the release variant of the collector as a static library without
+threads support.
+
+In order to use the gc_cpp.h C++ interface, all client code should include
+gc_cpp.h.
+
+[See above for gctest.]
+
+If you would prefer a VC++ .NET project file, ask Hans Boehm.  One has
+been contributed, but it seems to contain some absolute paths etc., so
+it can presumably only be a starting point, and is not in the standard
+distribution.  It is unclear (to me, Hans Boehm) whether it is feasible to
+change that.
+
+Clients may need to define GC_NOT_DLL before including gc.h, if the
+collector was built as a static library.
+
+GNU Tools
+---------
+
+The collector should be buildable under Cygwin with the
+"./configure; make check" machinery.
+
+MinGW builds (including for x64) are available both directly (on a Windows
+host) and via cross-compilation, e.g.
+"./configure --host=i686-pc-mingw32; make check"
+
+By default, configure instructs make to build the collector as a DLL (shared
+library), adding -D GC_DLL to CFLAGS.
+
+Parallel marker is enabled by default; it could be disabled by
+"--disable-parallel-mark" option.
+
+Memory unmapping could be turned off by "--disable-munmap" option.
+
+Borland Tools
+-------------
+
+For Borland tools, use `cmake -G "Borland Makefiles"`.  Note that
+Borland's compiler defaults to 1 byte alignment in structures (-a1),
+whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
+The garbage collector in its default configuration EXPECTS AT
+LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
+BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
+I expect that -a1 introduces major performance penalties on a
+486 or Pentium.)  Note that this changes structure layouts.  (As a last
+resort, gcconfig.h can be changed to allow 1 byte alignment.  But
+this has significant negative performance implications.)
+
+Digital Mars compiler
+---------------------
+
+Same as MS Visual C++ but might require
+-DAO_OLD_STYLE_INTERLOCKED_COMPARE_EXCHANGE option to compile with the
+parallel marker enabled.
+
+Watcom compiler
+---------------
+
+Ivan V. Demakov's README for the Watcom port:
+
+The collector has been tested with Watcom C 10.6, 11.0 and OpenWatcom 2.0.
+It runs under Win32 and win32s, and even under DOS with dos4gw
+dos-extender. It should also run under OS/2, though this isn't
+tested. Under Win32 the collector can be built either as dll
+or as static library.
+
+Note that all compilations were done under Windows 95 or NT.
+For unknown reason compiling under Windows 3.11 for NT (one
+attempt has been made) leads to broken executables.
+
+Incremental collection is supported (except for MSDOS and OS/2).
+
+Before compiling you may need to edit WCC_MAKEFILE to set target
+platform, library type (dynamic or static), calling conventions, and
+optimization options.
+
+To compile the collector use the command:
+    wmake -f WCC_MAKEFILE
+
+All programs using gc should be compiled with 4-byte alignment.
+For further explanations on this see comments about Borland.
+
+If the gc is compiled as dll, the macro "GC_DLL" should be defined before
+including "gc.h" (for example, with -DGC_DLL compiler option). It's
+important, otherwise resulting programs will not run.
+
+The alternate way to compile the collector is to use cmake build system:
+    cmake -G "Watcom WMake" .
+    cmake --build .
+
+Special note for OpenWatcom users: the C (unlike the C++) compiler (of the
+latest stable release, not sure for older ones) doesn't force pointer global
+variables (i.e. not struct fields, not sure for locals) to be aligned unless
+optimizing for speed (e.g., "-ot" option is set); the "-zp" option (or align
+pragma) only controls alignment for structs; I don't know whether it's a bug or
+a feature (see an old report of same kind -
+http://bugzilla.openwatcom.org/show_bug.cgi?id=664), so You are warned.
+
+Incremental Collection
+----------------------
+
+There is some support for incremental collection.  By default, the
+collector chooses between explicit page protection, and GetWriteWatch-based
+write tracking automatically, depending on the platform.
+
+The former is slow and interacts poorly with a debugger.
+Pages are protected.  Protection faults are caught by a handler
+installed at the bottom of the handler
+stack.  Whenever possible, I recommend adding a call to
+GC_enable_incremental at the last possible moment, after most
+debugging is complete.  No system
+calls are wrapped by the collector itself.  It may be necessary
+to wrap ReadFile calls that use a buffer in the heap, so that the
+call does not encounter a protection fault while it's running.
+(As usual, none of this is an issue unless GC_enable_incremental
+is called.)
+
+Note that incremental collection is disabled with -DSMALL_CONFIG.
+
+Threads
+-------
+
+The collector by default handles threads similarly to other platforms.
+James Clark's code which tracks threads attached to the collector DLL still
+exists, but requires that both
+- the collector is built in a DLL with GC_DLL defined, and
+- GC_use_threads_discovery() is called before GC initialization, which
+  in turn must happen before creating additional threads.
+We generally recommend avoiding this if possible, since it seems to
+be less than 100% reliable.
+
+To build the collector as a dynamic library which handles threads similarly
+to other platforms, type "nmake -f NT_MAKEFILE".  If automatic tracking of
+threads attached to the collector DLL (i.e. support of both kinds of thread
+tracking) is needed then delete "-DTHREAD_LOCAL_ALLOC" from NT_MAKEFILE
+manually before the build.
+
+The incremental collection is supported only if it is enabled before any
+additional threads are created.
+
+Threads are also supported in static library builds with Microsoft tools
+(e.g., NT_MAKEFILE), as well as with the CMake and GNU tools.  The collector
+must be built with GC_THREADS defined (this is the default in NT_MAKEFILE,
+CMakeLists.txt and configure).
+
+For the normal, non-dll-based thread tracking to work properly,
+threads should be created with GC_CreateThread or GC_beginthreadex,
+and exit normally, or call GC_endthreadex or GC_ExitThread.  (For Cygwin, the
+standard pthread_create/exit calls could be used instead.)  As in the pthread
+case, including gc.h will redefine CreateThread, _beginthreadex,
+_endthreadex, and ExitThread to call the GC_ versions instead.
+
+Note that, as usual, GC_CreateThread tends to introduce resource leaks (in the
+C runtime) that are avoided by GC_beginthreadex.  There is currently no
+equivalent of _beginthread, and it should not be used.
+
+GC_INIT should be called from the main thread before other GC calls.
+
+We strongly advise against using the TerminateThread() Windows API call,
+especially with the garbage collector.  Any use is likely to provoke a
+crash in the GC, since it makes it impossible for the collector to
+correctly track threads.
+
+To build the collector for MinGW pthreads-win32 (or other non-Cygwin pthreads
+implementation for Windows), use Makefile.direct and explicitly set
+GC_WIN32_PTHREADS (or pass --enable-threads=pthreads to configure).
+Use -DPTW32_STATIC_LIB for the static threads library.
+
+The alternate (better) way to build the library is to use CMake script;
+please see README.cmake for the details.
diff --git a/docs/platforms/README.win64 b/docs/platforms/README.win64
new file mode 100644
index 00000000..ed30665e
--- /dev/null
+++ b/docs/platforms/README.win64
@@ -0,0 +1,27 @@
+64-bit Windows on AMD64/Intel EM64T (x64) is supported.  A collector can be
+built with Microsoft Visual C++ 2005 or with mingw-w64 gcc.
+
+NT_MAKEFILE has been used in this environment.  Type
+"nmake -f NT_MAKEFILE cpu=AMD64 nodebug=1" in a Visual C++ command line
+window to build the release variant of the dynamic library with threads
+support.
+To verify that the collector is at least somewhat functional,
+type "nmake -f NT_MAKEFILE cpu=AMD64 check" to build and run the usual test
+programs.  This should create gctest.gc.log after a few seconds.
+
+cpptest.exe might not run correctly in case of dynamic GC linking.  (It seems
+that we're getting wrong instances of operator new/delete in some cases.)
+
+This process is completely analogous to NT_MAKEFILE usage
+for the 32-bit library version.
+
+A similar procedure using NT_MAKEFILE is applicable to build the static
+library - just pass "enable_static=1" as an extra argument to nmake.
+If needed, it is also possible to build the library without threads
+support - this could be done by passing "disable_threads=1" argument to nmake.
+
+Note that some warnings have been explicitly turned off in the makefile.
+
+VC++ note: to suppress warnings -D_CRT_SECURE_NO_DEPRECATE is used.
+
+gcc note: -fno-strict-aliasing should be used if optimizing.