Garbage Collector (parallel iversion) for ix86 DG/UX Release R4.20MU07


     *READ* the file README.QUICK.

     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 parralleli-mark for the SMP DG/UX machines.
     To build the garbage collector do:

      ./configure --enable-parallel-mark
      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 --enable-parallel-mark --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) the option parallel
     mark (aka --enable-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]

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 v4.12 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.

    GC version:     4.12a2
    Codewarrior:    CWPro1
    date:           18 July 1997

The notes may or may not apply to earlier or later versions of the
GC/CWPro. Actually, they do apply to earlier versions of both except that
until recently a project could only build one target so each target was a
separate project. The notes will most likely apply to future versions too.
Possibly with minor tweaks.

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 'test.c'.
3) Test that the C++ interface 'gc_cpp.cc/h' works with 'test_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 commandline 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 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:
--------------------------------
    allchblk.c
    alloc.c
    blacklst.c
    checksums.c
    dbg_mlc.c
    finalize.c
    headers.c
    mach_dep.c
    MacOS.c    -- contains MacOS code
    malloc.c
    mallocx.c
    mark.c
    mark_rts.c
    misc.c
    new_hblk.c
    obj_map.c
    os_dep.c   -- contains MacOS code
    ptr_chck.c
    reclaim.c
    stubborn.c
    typd_mlc.c
    gc++.cc    -- this is 'gc_cpp.cc' with less 'inline' and
               -- throw std::bad_alloc when out of memory
               -- gc_cpp.cc works just fine too

== 2. Test that the library works with 'test.c' ==

The test app is just an ordinary ANSI-C console app. Make sure settings
match the library you're testing.

Files
-----
    test.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.cc/h' works with 'test_cpp.cc' ==

The test app is just an ordinary ANSI-C console app. Make sure settings match
the library you're testing.

Files
-----
    test_cpp.cc
    the GC library to test        -- link order before ANSI libs
    suitable Mac+ANSI libraries

prefix:
------
same as for test.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: test.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 it's 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.

== Source Changes (GC 4.12a2) ==

Very few. Just one tiny in the GC, not strictly needed.
- test_cpp.cc
  made the first lines of main() look like this:
  ------------
  int main( int argc, char* argv[] ) {
  #endif
  #if macintosh                             // MacOS
    char* argv_[] = {"test_cpp","10"};      //   doesn't
    argv=argv_;                             //     have a
    argc = sizeof(argv_)/sizeof(argv_[0]);  //       commandline
  #endif                                    //

  int i, iters, n;
  # ifndef __GNUC__
   alloc dummy_to_fool_the_compiler_into_doing_things_it_currently_cant_handle;
  ------------

- config.h [now gcconfig.h]
  __MWERKS__ does not have to mean MACOS. You can use Codewarrior to
  build a Win32 or BeOS library and soon a Rhapsody library. You may
  have to change that #if...



   It worked for me, hope it works for you.

   Lars Farm
----------------------------------------------------------------------------


Patrick Beard's instructions (may be dated):

v4.3 of the collector now runs 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 32k
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

The code assumes static linking, and a single thread.  The editor de has
not been ported.  The cord test program has.  The supplied OS2_MAKEFILE
assumes the IBM C Set/2 environment, but the code shouldn't.

Since we haven't figured out hoe to do perform partial links or to build static
libraries, clients currently need to link against a long list of executables.

            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', and hope it compiles fine.


WHATS NEW:

1.
   Made a pretty big effort in preventing GCs 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_stubborn, 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 (f.ex. 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 8MB 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
                 theres either very little fast-memory left or verly little
                 chip-memory left. Its 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 reccomendation 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
   compilling 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 like f.ex 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
   define f.ex 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. Ie. 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. Updated and rewritten the smakefile, so that it works again and that
   the "unnecessary" 'SCOPTIONS' files could be removed. Also included
   the cord-smakefile stuff in the main smakefile, so that the cord smakefile
   could be removed too. By writing smake -f Smakefile.smk, both gc.lib and
   cord.lib will be made.



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). I guess it works if you use the old "#if 0'ed"-code,
but I haven't tested it. I think the reason for MT to replace the
"#if 0'ed"-code was only because it was a bit to SAS/C-specific. But I
don't know. An iconx-script solves this problem anyway.


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`
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:

- Starting with version 4.3, gctest checks to see if the code segment is
  added to the root set or not, and complains if it is. Previous versions
  of this Amiga port added the code segment to the root set, so I tried to
  fix that. 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 comms 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-complient code. (ie. 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 documentaion). 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 @ 25Mhz)
compares favourably with an HP9000 with similar architecture (a 325
with a 68030 I think).

-----------------------------------------------------------------------

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/gc6.0,
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/gc6.0 directory.  Do
  CONFIG_SITE=/home/arm/config.site ./configure --target=arm-linux
--prefix=/home/arm/gc6.0

On your desktop, do:
   make
   make install
The main garbage collector library should now be in ../gc6.0/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 test" (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

Starting from GC v6.0, we support GNU-style builds based on automake,
autoconf and libtool.  This is based almost entirely on Tom Tromey's work
with gcj.

To build and install libraries use

configure; make; make install

The advantages of this process are:

1) It should eventually do a better job of automatically determining the
right compiler to use, etc.  It probably already does in some cases.

2) It tries to automatically set a good set of default GC parameters for
the platform (e.g. thread support).  It provides an easier way to configure
some of the others.

3) It integrates better with other projects using a GNU-style build process.

4) It builds both dynamic and static libraries.

The known disadvantages are:

1) The build scripts are much more complex and harder to debug (though largely
standard).  I don't understand them all, and there's probably lots of redundant
stuff.

2) It probably doesn't work on all Un*x-like platforms yet.  It probably will
never work on the rest.

3) The scripts are not yet complete.  Some of the standard GNU targets don't
yet work.  (Corrections/additions are very welcome.)

The distribution should contain all files needed to run "configure" and "make",
as well as the sources needed to regenerate the derived files.  (If I missed
some, please let me know.)

Note that the distribution comes without "Makefile" which is generated by
"configure".  The distribution also contains "Makefile.direct" which is not
always equivalent to the generated one.

Important options to configure:

  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [same as prefix]
  --enable-threads=TYPE   choose threading package
  --enable-parallel-mark  parallelize marking and free list construction
  --enable-gc-debug (--enable-full-debug before about 7.0)
                          include full support for pointer back-tracing etc.


Unless --prefix is set (or --exec-prefix or one of the more obscure options),
make install will install libgc.a and libgc.so in /usr/local/bin, which
would typically require the "make install" to be run as root.

Most commonly --enable-threads=posix or will be needed.  --enable-parallel-mark
is recommended for multiprocessors if it is supported on the platform.

CMAKE
-----

Win32 binaries (both 32- and 64-bit) can be built using CMake.  CMake is an
open-source tool like automake - it generates makefiles.

Some preliminary work has been done to make this work on other platforms, but
the support is not yet complete.

CMake will generate:

  Borland Makefiles
  MSYS Makefiles
  MinGW Makefiles
  NMake Makefiles
  Unix Makefiles
  . Visual Studio project files
    Visual Studio 6
    Visual Studio 7
    Visual Studio 7 .NET 2003
    Visual Studio 8 2005
    Visual Studio 8 2005 Win64
    Visual Studio 9 2008
    Visual Studio 9 2008 Win64
  Watcom WMake


BUILD PROCESS
-------------

 . install cmake (cmake.org)
 . add directory containing cmake.exe to %PATH%
 . run cmake from the gc root directory, passing the target with -G:
   e.g.,
      > cmake -G "Visual Studio 8 2005"
   use the gc.sln file generated by cmake to build gc
 . you can also run cmake from a build directory to build outside of
   the source tree. Just specify the path to the source tree:
   e.g.,
      > mkdir build
      > cd build
      > cmake .. -G "Visual Studio 8 2005"


INPUT
-----

The main input to cmake are the CMakeLists.txt files in each directory.  For
help, goto cmake.org.

Copyright (c) 1993-1994 by Xerox Corporation.  All rights reserved.

THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.

Permission is hereby granted to use or copy this program
for any purpose,  provided the above notices are retained on all copies.
Permission to modify the code and to distribute modified code is granted,
provided the above notices are retained, and a notice that the code was
modified is included with the above copyright notice.

Please send bug reports to Hans-J. Boehm.

This is a string packages that uses a tree-based representation.
See cord.h for a description of the functions provided.  Ec.h describes
"extensible cords", which are essentially output streams that write
to a cord.  These allow for efficient construction of cords without
requiring a bound on the size of a cord.

More details on the data structure can be found in

Boehm, Atkinson, and Plass, "Ropes: An Alternative to Strings",
Software Practice and Experience 25, 12, December 1995, pp. 1315-1330.

A fundamentally similar "rope" data structure is also part of SGI's standard
template library implementation, and its descendants, which include the
GNU C++ library.  That uses reference counting by default.
There is a short description of that data structure at
http://www.sgi.com/tech/stl/ropeimpl.html .

All of these are descendants of the "ropes" in Xerox Cedar.

cord/tests/de.c is a very dumb text editor that illustrates the use of cords.
It maintains a list of file versions.  Each version is simply a
cord representing the file contents.  Nonetheless, standard
editing operations are efficient, even on very large files.
(Its 3 line "user manual" can be obtained by invoking it without
arguments.  Note that ^R^N and ^R^P move the cursor by
almost a screen.  It does not understand tabs, which will show
up as highlighted "I"s.  Use the UNIX "expand" program first.)
To build the editor, type "make cord/de" in the gc directory.

This package assumes an ANSI C compiler such as gcc.  It will
not compile with an old-style K&R compiler.

Note that CORD_printf iand friends use C functions with variable numbers
of arguments in non-standard-conforming ways.  This code is known to
break on some platforms, notably PowerPC.  It should be possible to
build the remainder of the library (everything but cordprnt.c) on
any platform that supports the collector.

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():

#include <gc/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.

The incremental collector is still a bit flaky on darwin. It seems to
work reliably with workarounds for a few possible bugs in place however
these workaround may not work correctly in all cases. There may also
be additional problems that I have not found.

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.

The original incremental collector support unfortunately no longer works
on recent Darwin versions. It also relied on some undocumented kernel
structures. Mach, however, does have a very clean interface to exception
handing. The current implementation 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

== gc_cpp.h usage ==

Replacement of operator new and delete is apparently not supported with
dynamic libraries.  This means that applications using gc_cpp.h
(including the built-in test) will probably not work correctly with
the collector in a dynamic library, unless special care is taken.

See
http://article.gmane.org/gmane.comp.programming.garbage-collection.boehmgc/1421
for some details.

- Hans Boehm (based on information from Andrew Begel)


== Older Information (Most of this no longer applies to the current code) ==

While the GC should work on MacOS X Server, MacOS X and Darwin, I only tested
it on MacOS X Server.
I've added a PPC assembly version of GC_push_regs(), thus the setjmp() hack is
no longer necessary. Incremental collection is supported via mprotect/signal.
The current solution isn't really optimal because the signal handler must decode
the faulting PPC machine instruction in order to find the correct heap address.
Further, it must poke around in the register state which the kernel saved away
in some obscure register state structure before it calls the signal handler -
needless to say the layout of this structure is no where documented.
Threads and dynamic libraries are not yet supported (adding dynamic library
support via the low-level dyld API shouldn't be that hard).

The original MacOS X port was brought to you by Andrew Stone.


June, 1 2000

Dietmar Planitzer

Note from Andrew Begel:

One more fix to enable gc.a to link successfully into a shared library for
MacOS X. You have to add -fno-common to the CFLAGS in the Makefile. MacOSX
disallows common symbols in anything that eventually finds its way into a
shared library. (I don't completely understand why, but -fno-common seems to
work and doesn't mess up the garbage collector's functionality).

Feb 26, 2003

Jeff Sturm and Jesse Rosenstock provided a patch that adds thread support.
GC_MACOSX_THREADS should be defined in the build and in clients.  Real
dynamic library support is still missing, i.e. dynamic library data segments
are still not scanned.  Code that stores pointers to the garbage collected
heap in statically allocated variables should not reside in a dynamic
library.  This still doesn't appear to be 100% reliable.

Mar 10, 2003
Brian Alliet contributed dynamic library support for MacOSX.  It could also
use more testing.

Look first at Makefile.dj, and possibly change the definitions of
RM and MV if you don't have rm and mv installed.
Then use Makefile.dj to compile the garbage collector.
For example, you can do:

        make -f Makefile.dj test

All the tests should work fine.

The garbage collector looks at a number of environment variables which are,
then, used to affect its operation.

GC_INITIAL_HEAP_SIZE=<bytes> -  Initial heap size in bytes.  May speed up
                                process start-up.  Optionally, may be
                                specified with a multiplier ('k', 'M' or 'G')
                                suffix.

GC_MAXIMUM_HEAP_SIZE=<bytes> - Maximum collected heap size.  Allows
                               a multiplier suffix.

GC_LOOP_ON_ABORT - Causes the collector abort routine to enter a tight loop.
                   This may make it easier to debug, such a process, especially
                   for multi-threaded platforms that don't produce usable core
                   files, or if a core file would be too large.  On some
                   platforms, this also causes SIGSEGV to be caught and
                   result in an infinite loop in a handler, allowing
                   similar debugging techniques.

GC_PRINT_STATS - Turn on GC logging.  Not functional with SMALL_CONFIG.

GC_LOG_FILE - The name of the log file.  Stderr by default.  Not functional
              with SMALL_CONFIG.

GC_ONLY_LOG_TO_FILE - Turns off redirection of GC stdout and stderr to the log
                      file specified by GC_LOG_FILE.  Has no effect unless
                      GC_LOG_FILE is set.  Not functional with SMALL_CONFIG.

GC_PRINT_VERBOSE_STATS - Turn on even more logging.  Not functional with
                         SMALL_CONFIG.

GC_DUMP_REGULARLY - Generate a GC debugging dump GC_dump() on startup
                    and during every collection.  Very verbose.  Useful
                    if you have a bug to report, but please include only the
                    last complete dump.

GC_COLLECT_AT_MALLOC=<n> - Override the default value specified by
                           GC_COLLECT_AT_MALLOC macro.  Has no effect unless
                           GC is built with GC_COLLECT_AT_MALLOC defined.

GC_BACKTRACES=<n> - Generate n random back-traces (for heap profiling) after
                    each GC.  Collector must have been built with
                    KEEP_BACK_PTRS.  This won't generate useful output unless
                    most objects in the heap were allocated through debug
                    allocators.  This is intended to be only a statistical
                    sample;  individual traces may be erroneous due to
                    concurrent heap mutation.

GC_PRINT_ADDRESS_MAP - Linux only.  Dump /proc/self/maps, i.e. various address
                       maps for the process, to stderr on every GC.  Useful for
                       mapping root addresses to source for deciphering leak
                       reports.

GC_NPROCS=<n> - Linux w/threads only.  Explicitly sets the number of processors
                that the GC should expect to use.  Note that setting this to 1
                when multiple processors are available will preserve
                correctness, but may lead to really horrible performance,
                since the lock implementation will immediately yield without
                first spinning.

GC_MARKERS=<n> - Only if compiled with PARALLEL_MARK.  Set the number
                of marker threads.  This is normally set to the number of
                processors.  It is safer to adjust GC_MARKERS than GC_NPROCS,
                since GC_MARKERS has no impact on the lock implementation.

GC_NO_BLACKLIST_WARNING - Prevents the collector from issuing
                warnings about allocations of very large blocks.
                Deprecated.  Use GC_LARGE_ALLOC_WARN_INTERVAL instead.

GC_LARGE_ALLOC_WARN_INTERVAL=<n> - Print every nth warning about very large
                block allocations, starting with the nth one.  Small values
                of n are generally benign, in that a bounded number of
                such warnings generally indicate at most a bounded leak.
                For best results it should be set at 1 during testing.
                Default is 5.  Very large numbers effectively disable the
                warning.

GC_IGNORE_GCJ_INFO - Ignore the type descriptors implicitly supplied by
                     GC_gcj_malloc and friends.  This is useful for debugging
                     descriptor generation problems, and possibly for
                     temporarily working around such problems.  It forces a
                     fully conservative scan of all heap objects except
                     those known to be pointer-free, and may thus have other
                     adverse effects.

GC_PRINT_BACK_HEIGHT - Print max length of chain through unreachable objects
                     ending in a reachable one.  If this number remains
                     bounded, then the program is "GC robust".  This ensures
                     that a fixed number of misidentified pointers can only
                     result in a bounded space leak.  This currently only
                     works if debugging allocation is used throughout.
                     It increases GC space and time requirements appreciably.
                     This feature is still somewhat experimental, and requires
                     that the collector have been built with MAKE_BACK_GRAPH
                     defined.  For details, see Boehm, "Bounding Space Usage
                     of Conservative Garbage Collectors", POPL 2001
                     (http://www.hpl.hp.com/techreports/2001/HPL-2001-251.html).

GC_RETRY_SIGNALS, GC_NO_RETRY_SIGNALS - Try to compensate for lost
                     thread suspend signals (Pthreads only).  On by
                     default for GC_OSF1_THREADS, off otherwise.  Note
                     that this does not work around a possible loss of
                     thread restart signals.  This seems to be necessary for
                     some versions of Tru64.  Since we've previously seen
                     similar issues on some other operating systems, it
                     was turned into a runtime flag to enable last-minute
                     work-arounds.

GC_USE_GETWRITEWATCH=<n> - Only if MPROTECT_VDB and GWW_VDB are both defined
                     (Win32 only).  Explicitly specify which strategy of
                     keeping track of dirtied pages should be used.
                     If n=0 then GetWriteWatch() is not used (falling back to
                     protecting pages and catching memory faults strategy)
                     else the collector tries to use GetWriteWatch-based
                     strategy (GWW_VDB) first if available.

GC_DISABLE_INCREMENTAL - Ignore runtime requests to enable incremental GC.
                     Useful for debugging.

The following turn on runtime flags that are also program settable.  Checked
only during initialization.  We expect that they will usually be set through
other means, but this may help with debugging and testing:

GC_ENABLE_INCREMENTAL - Turn on incremental collection at startup.  Note that,
                     depending on platform and collector configuration, this
                     may involve write protecting pieces of the heap to
                     track modifications.  These pieces may include
                     pointer-free objects or not.  Although this is intended
                     to be transparent, it may cause unintended system call
                     failures.  Use with caution.

GC_PAUSE_TIME_TARGET - Set the desired garbage collector pause time in msecs.
                     This only has an effect if incremental collection is
                     enabled.  If a collection requires appreciably more time
                     than this, the client will be restarted, and the collector
                     will need to do additional work to compensate.  The
                     special value "999999" indicates that pause time is
                     unlimited, and the incremental collector will behave
                     completely like a simple generational collector.  If
                     the collector is configured for parallel marking, and
                     run on a multiprocessor, incremental collection should
                     only be used with unlimited pause time.

GC_FULL_FREQUENCY - Set the desired number of partial collections between full
                    collections.  Matters only if GC_incremental is set.
                    Not functional with SMALL_CONFIG.

GC_FREE_SPACE_DIVISOR - Set GC_free_space_divisor to the indicated value.
                      Setting it to larger values decreases space consumption
                      and increases GC frequency.

GC_UNMAP_THRESHOLD - Set the desired memory blocks unmapping threshold (the
                   number of sequential garbage collections for which
                   a candidate block for unmapping should remain free).  The
                   special value "0" completely disables unmapping.

GC_FORCE_UNMAP_ON_GCOLLECT - Turn "unmap as much as possible on explicit GC"
                mode on (overrides the default value).  Has no effect on
                implicitly-initiated garbage collections.  Has no effect if
                memory unmapping is disabled (or not compiled in) or if the
                unmapping threshold is 1.

GC_FIND_LEAK - Turns on GC_find_leak and thus leak detection.  Forces a
               collection at program termination to detect leaks that would
               otherwise occur after the last GC.

GC_FINDLEAK_DELAY_FREE - Turns on deferred freeing of objects in the
                       leak-finding mode (see the corresponding macro
                       description for more information).

GC_ABORT_ON_LEAK - Causes the application to be terminated once leaked or
                   smashed objects are found.

GC_ALL_INTERIOR_POINTERS - Turns on GC_all_interior_pointers and thus interior
                           pointer recognition.

GC_DONT_GC - Turns off garbage collection.  Use cautiously.

GC_USE_ENTIRE_HEAP - Set desired GC_use_entire_heap value at start-up.  See
                     the similar macro description in README.macros.

GC_TRACE=addr - Intended for collector debugging.  Requires that the collector
                have been built with ENABLE_TRACE defined.  Causes the debugger
                to log information about the tracing of address ranges
                containing addr.  Typically addr is the address that contains
                a pointer to an object that mysteriously failed to get marked.
                Addr must be specified as a hexadecimal integer.

GC on EWS4800
-------------

1. About EWS4800
   EWS4800 is 32bit/64bit workstation.

     Vendor: NEC Corporation
     OS: UX/4800 R9.* - R13.* (SystemV R4.2)
     CPU: R4000, R4400, R10000 (MIPS)

2. Compiler

 32bit:
   Use ANSI C compiler.
     CC = /usr/abiccs/bin/cc

 64bit:
   Use 64bit ANSI C compiler.
     CC = /usr/ccs64/bin/cc
     AR = /usr/ccs64/bin/ar

3. ELF file format
   *** Caution: The following information is empirical. ***

 32bit:
   ELF file has an 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.

 64bit:
   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.)

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 reccently added, and should now work.

In spite of past claims, pthread support under HP/UX 11 should now work.
Define GC_HPUX_THREADS 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.

See README.alpha for Linux on DEC AXP info.

This file applies mostly to Linux/Intel IA32.  Ports to Linux on an M68K,
IA64, 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.  A static executable
should be linked with the gcc option "-Wl,-defsym,_DYNAMIC=0".

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_LINUX_THREADS (or
   just -DGC_THREADS) and -D_REENTRANT specified in the Makefile.

3a) Every file that makes thread calls should define GC_LINUX_THREADS and
   _REENTRANT and then include gc.h.  Gc.h 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_LINUX_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.  The current GC
   version probably gets things right 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);
}

The collector uses a large amount of conditional compilation in order to
deal with platform dependencies.  This violates a number of known coding
standards.  On the other hand, it seems to be the only practical way to
support this many platforms without excessive code duplication.

A few guidelines have mostly been followed in order to keep this manageable:

1) #if and #ifdef directives are properly indented whenever easily possible.
All known C compilers allow whitespace between the "#" and the "if" to make
this possible.  ANSI C also allows white space before the "#", though we
avoid that.  It has the known disadvantages that it differs from the normal
GNU conventions, and that it makes patches larger than otherwise necessary.
In my opinion, it's still well worth it, for the same reason that we indent
ordinary "if" statements.

2) Whenever possible, tests are performed on the macros defined in gcconfig.h
instead of directly testing platform-specific predefined macros.  This makes
it relatively easy to adapt to new compilers with a different set of
predefined macros.  Currently these macros generally identify platforms
instead of features.  In many cases, this is a mistake.

Many of the tested configuration macros are at least somewhat defined in
either include/private/gcconfig.h or in Makefile.direct.  Here is an attempt
at documenting these macros:  (Thanks to Walter Bright for suggesting
this.  This is a work in progress)

MACRO           EXPLANATION
-----           -----------

GC_DEBUG        Tested by gc.h.  Causes all-upper-case macros to
                expand to calls to debug versions of collector routines.

GC_NAMESPACE    Tested by gc_cpp.h. Causes gc_cpp symbols to be defined
                in "boehmgc" namespace.

GC_DEBUG_REPLACEMENT    Tested by gc.h. Causes GC_MALLOC/REALLOC() to be
                defined as GC_debug_malloc/realloc_replacement().

GC_NO_THREAD_REDIRECTS  Tested by gc.h.  Prevents redirection of thread
                creation routines etc. to GC_ versions.  Requires the
                programmer to explicitly handle thread registration.

GC_NO_THREAD_DECLS      Tested by gc.h.  MS Windows only.  Do not declare
                Windows thread creation routines and do not include windows.h.

GC_UNDERSCORE_STDCALL   Tested by gc.h.  Explicitly prefix exported/imported
                WINAPI (__stdcall) symbols with '_' (underscore).  Could be
                used with MinGW (for x86) compiler (in conjunction with
                GC_DLL) to follow MS conventions for __stdcall symbols naming.

_ENABLE_ARRAYNEW
                #define'd by the Digital Mars C++ compiler when
                operator new[] and delete[] are separately
                overloadable. Used in gc_cpp.h.

_DLL            Tested by gc_config_macros.h. Defined by Visual C++ if runtime
                dynamic libraries are in use.  Used (only if none of GC_DLL,
                GC_NOT_DLL, __GNUC__ are defined) to test whether
                __declspec(dllimport) needs to be added to declarations
                to support the case in which the collector is in a DLL.

GC_DLL          Defined by user if dynamic libraries are being built
                or used.  Also set by gc.h if _DLL is defined (except for
                mingw) while GC_NOT_DLL and __GNUC__ are both undefined.
                This is the macro that is tested internally to determine
                whether the GC is in its own dynamic library.  May need
                to be set by clients before including gc.h.  Note that
                inside the GC implementation it indicates that the
                collector is in its own dynamic library, should export
                its symbols, etc.  But in clients it indicates that the
                GC resides in a different DLL, its entry points should
                be referenced accordingly, and precautions may need to
                be taken to properly deal with statically allocated
                variables in the main program.  Used for MS Windows.
                Also used by GCC v4+ (only when the dynamic shared library
                is being built) to hide internally used symbols.

GC_NOT_DLL      User-settable macro that overrides _DLL, e.g. if runtime
                dynamic libraries are used, but the collector is in a static
                library.  Tested by gc_config_macros.h.

GC_REQUIRE_WCSDUP       Force GC to export GC_wcsdup() (the Unicode version
                of GC_strdup); could be useful in the leak-finding mode.


These define arguments influence the collector configuration:

FIND_LEAK       Causes GC_find_leak to be initially set.  This causes the
  collector to assume that all inaccessible objects should have been
  explicitly deallocated, and reports exceptions.  Finalization and the test
  program are not usable in this mode.

GC_FINDLEAK_DELAY_FREE  Turns on deferred freeing of objects in the
  leak-finding mode letting the collector to detect alter-object-after-free
  errors as well as detect leaked objects sooner (instead of only when program
  terminates).  Has no effect if SHORT_DBG_HDRS.

GC_ABORT_ON_LEAK        Causes the application to be terminated once leaked or
  smashed (corrupted on use-after-free) objects are found (after printing the
  information about that objects).

SUNOS5SIGS      Solaris-like signal handling.  This is probably misnamed,
  since it really doesn't guarantee much more than POSIX.  Currently set only
  for Solaris2.X, HPUX, and DRSNX.  Should probably be set for some other
  platforms.

PCR     Set if the collector is being built as part of the Xerox Portable
  Common Runtime.

IMPORTANT: Any of the _THREADS options must normally also be defined in
  the client before including gc.h.  This redefines thread primitives to
  invoke the GC_ versions instead.  Alternatively, linker-based symbol
  interception can be used on a few platforms.

GC_THREADS      Should set the appropriate one of the below macros,
  except GC_WIN32_PTHREADS, which must be set explicitly.  Tested by gc.h.

GC_SOLARIS_THREADS      Enables support for Solaris pthreads.
  Must also define _REENTRANT.

GC_IRIX_THREADS         Enables support for Irix pthreads.  See README.sgi.

GC_HPUX_THREADS         Enables support for HP/UX 11 pthreads.
  Also requires _REENTRANT or _POSIX_C_SOURCE=199506L. See README.hp.

GC_LINUX_THREADS        Enables support for Xavier Leroy's Linux threads
  or NPTL threads. See README.linux.  _REENTRANT may also be required.

GC_OSF1_THREADS         Enables support for Tru64 pthreads.

GC_FREEBSD_THREADS      Enables support for FreeBSD pthreads.
  Appeared to run into some underlying thread problems.

GC_NETBSD_THREADS       Enables support for NetBSD pthreads.

GC_OPENBSD_THREADS      Enables support for OpenBSD pthreads.

GC_DARWIN_THREADS       Enables support for Mac OS X pthreads.

GC_AIX_THREADS  Enables support for IBM AIX threads.

GC_DGUX386_THREADS      Enables support for DB/UX on I386 threads.
  See README.DGUX386.  (Probably has not been tested recently.)

GC_WIN32_THREADS        Enables support for Win32 threads.  That makes sense
  for this Makefile only under Cygwin.

GC_WIN32_PTHREADS       Enables support for pthreads-win32.  This cannot be
  enabled automatically by GC_THREADS, which would assume Win32 native
  threads.

PTW32_STATIC_LIB        Causes the static version of the Mingw pthreads
  library to be used.  Requires GC_WIN32_PTHREADS.

GC_PTHREADS_PARAMARK    Causes pthread-based parallel mark implementation
  to be used even if GC_WIN32_PTHREADS is undefined.  (Useful for WinCE.)

ALL_INTERIOR_POINTERS   Allows all pointers to the interior of objects to be
  recognized.  (See gc_priv.h for consequences.)  Alternatively,
  GC_all_interior_pointers can be set at process initialization time.

SMALL_CONFIG    Tries to tune the collector for small heap sizes,
  usually causing it to use less space in such situations.  Incremental
  collection no longer works in this case.  Also, removes some
  statistic-printing code.  Turns off some optimization algorithms (like data
  prefetching in the mark routine).

GC_DISABLE_INCREMENTAL  Turn off the incremental collection support.

NO_INCREMENTAL  Causes the gctest program to not invoke the incremental
  collector.  This has no impact on the generated library, only on the test
  program.  (This is often useful for debugging failures unrelated to
  incremental GC.)

LARGE_CONFIG    Tunes the collector for unusually large heaps.
  Necessary for heaps larger than about 4 GiB on most (64-bit) machines.
  Recommended for heaps larger than about 500 MiB.  Not recommended for
  embedded systems.  Could be used in conjunction with SMALL_CONFIG to
  generate smaller code (by disabling incremental collection support,
  statistic printing and some optimization algorithms).

DONT_ADD_BYTE_AT_END    Meaningful only with ALL_INTERIOR_POINTERS or
  GC_all_interior_pointers = 1.  Normally ALL_INTERIOR_POINTERS
  causes all objects to be padded so that pointers just past the end of
  an object can be recognized.  This can be expensive.  (The padding
  is normally more than one byte due to alignment constraints.)
  DONT_ADD_BYTE_AT_END disables the padding.

NO_EXECUTE_PERMISSION   May cause some or all of the heap to not
  have execute permission, i.e. it may be impossible to execute
  code from the heap.  Currently this only affects the incremental
  collector on UNIX machines.  It may greatly improve its performance,
  since this may avoid some expensive cache synchronization.  Alternatively,
  GC_set_pages_executable can be called at the process initialization time.

GC_NO_OPERATOR_NEW_ARRAY        Declares that the C++ compiler does not
  support the  new syntax "operator new[]" for allocating and deleting arrays.
  See gc_cpp.h for details.  No effect on the C part of the collector.
  This is defined implicitly in a few environments.  Must also be defined
  by clients that use gc_cpp.h.

REDIRECT_MALLOC=<X>     Causes malloc to be defined as alias for X.
  Unless the following macros are defined, realloc is also redirected
  to GC_realloc, and free is redirected to GC_free.
  Calloc and str[n]dup are redefined in terms of the new malloc.  X should
  be either GC_malloc or GC_malloc_uncollectable, or
  GC_debug_malloc_replacement.  (The latter invokes GC_debug_malloc
  with dummy source location information, but still results in
  properly remembered call stacks on Linux/X86 and Solaris/SPARC.
  It requires that the following two macros also be used.)
  The former is occasionally useful for working around leaks in code
  you don't want to (or can't) look at.  It may not work for
  existing code, but it often does.  Neither works on all platforms,
  since some ports use malloc or calloc to obtain system memory.
  (Probably works for UNIX, and Win32.)  If you build with DBG_HDRS_ALL,
  you should only use GC_debug_malloc_replacement as a malloc
  replacement.

REDIRECT_REALLOC=<X>    Causes GC_realloc to be redirected to X.
  The canonical use is REDIRECT_REALLOC=GC_debug_realloc_replacement,
  together with REDIRECT_MALLOC=GC_debug_malloc_replacement to
  generate leak reports with call stacks for both malloc and realloc.
  This also requires REDIRECT_FREE.

REDIRECT_FREE=<X>       Causes free to be redirected to X.  The canonical use
  is REDIRECT_FREE=GC_debug_free.

IGNORE_FREE     Turns calls to free into a no-op.  Only useful with
  REDIRECT_MALLOC.

NO_DEBUGGING    Removes GC_dump and the debugging routines it calls.
  Reduces code size slightly at the expense of debuggability.

DEBUG_THREADS   Turn on printing additional thread-support debugging
  information.

GC_COLLECT_AT_MALLOC=<n>        Force garbage collection at every
  GC_malloc_* call with the size greater than the specified value.
  (Might be useful for application debugging or in find-leak mode.)

JAVA_FINALIZATION       Makes it somewhat safer to finalize objects out of
  order by specifying a nonstandard finalization mark procedure  (see
  finalize.c).  Objects reachable from finalizable objects will be marked
  in a separate post-pass, and hence their memory won't be reclaimed.
  Not recommended unless you are implementing a language that specifies
  these semantics.  Since 5.0, determines only the initial value
  of GC_java_finalization variable.

FINALIZE_ON_DEMAND      Causes finalizers to be run only in response
  to explicit GC_invoke_finalizers() calls.
  In 5.0 this became runtime adjustable, and this only determines the
  initial value of GC_finalize_on_demand.

GC_NO_FINALIZATION      Exclude finalization support (for smaller code size)

ATOMIC_UNCOLLECTABLE    Includes code for GC_malloc_atomic_uncollectable.
  This is useful if either the vendor malloc implementation is poor,
  or if REDIRECT_MALLOC is used.

MARK_BIT_PER_GRANULE    Requests that a mark bit (or often byte)
  be allocated for each allocation granule, as opposed to each object.
  This often improves speed, possibly at some cost in space and/or
  cache footprint.  Normally it is best to let this decision be
  made automatically depending on platform.

MARK_BIT_PER_OBJ        Requests that a mark bit be allocated for each
  object instead of allocation granule.  The opposite of
  MARK_BIT_PER_GRANULE.

HBLKSIZE=<ddd>  Explicitly sets the heap block size (where ddd is a power of
  2 between 512 and 16384).  Each heap block is devoted to a single size and
  kind of object.  For the incremental collector it makes sense to match
  the most likely page size.  Otherwise large values result in more
  fragmentation, but generally better performance for large heaps.

USE_MMAP        Use MMAP instead of sbrk to get new memory.
  Works for Linux, FreeBSD, Cygwin, Solaris and Irix.

USE_MUNMAP      Causes memory to be returned to the OS under the right
  circumstances.  This currently disables VM-based incremental collection
  (except for Win32 with GetWriteWatch() available).
  Works under some Unix, Linux and Windows versions.
  Requires USE_MMAP except for Windows.

USE_WINALLOC (Cygwin only)   Use Win32 VirtualAlloc (instead of sbrk or mmap)
  to get new memory.  Useful if memory unmapping (USE_MUNMAP) is enabled.

MUNMAP_THRESHOLD=<value>        Set the desired memory blocks unmapping
  threshold (the number of sequential garbage collections for which
  a candidate block for unmapping should remain free).

GC_FORCE_UNMAP_ON_GCOLLECT      Set "unmap as much as possible on explicit GC"
  mode on by default.  The mode could be changed at run-time.  Has no effect
  unless unmapping is turned on.  Has no effect on implicitly-initiated
  garbage collections.

PRINT_BLACK_LIST        Whenever a black list entry is added, i.e. whenever
  the garbage collector detects a value that looks almost, but not quite,
  like a pointer, print both the address containing the value, and the
  value of the near-bogus-pointer.  Can be used to identify regions of
  memory that are likely to contribute misidentified pointers.

KEEP_BACK_PTRS  Add code to save back pointers in debugging headers
  for objects allocated with the debugging allocator.  If all objects
  through GC_MALLOC with GC_DEBUG defined, this allows the client
  to determine how particular or randomly chosen objects are reachable
  for debugging/profiling purposes.  The gc_backptr.h interface is
  implemented only if this is defined.

GC_ASSERTIONS   Enable some internal GC assertion checking.  Currently
  this facility is only used in a few places.  It is intended primarily
  for debugging of the garbage collector itself, but could also...

DBG_HDRS_ALL    Make sure that all objects have debug headers.  Increases
  the reliability (from 99.9999% to 100% mod. bugs) of some of the debugging
  code (especially KEEP_BACK_PTRS).  Makes SHORT_DBG_HDRS possible.
  Assumes that all client allocation is done through debugging allocators.

SHORT_DBG_HDRS  Assume that all objects have debug headers.  Shorten
  the headers to minimize object size, at the expense of checking for
  writes past the end of an object.  This is intended for environments
  in which most client code is written in a "safe" language, such as
  Scheme or Java.  Assumes that all client allocation is done using
  the GC_debug_ functions, or through the macros that expand to these,
  or by redirecting malloc to GC_debug_malloc_replacement.
  (Also eliminates the field for the requested object size.)
  Occasionally could be useful for debugging of client code.  Slows down the
  collector somewhat, but not drastically.

SAVE_CALL_COUNT=<n>     Set the number of call frames saved with objects
  allocated through the debugging interface.  Affects the amount of
  information generated in leak reports.  Only matters on platforms
  on which we can quickly generate call stacks, currently Linux/(X86 & SPARC)
  and Solaris/SPARC and platforms that provide execinfo.h.
  Default is zero.  On X86, client
  code should NOT be compiled with -fomit-frame-pointer.

SAVE_CALL_NARGS=<n>     Set the number of functions arguments to be saved
  with each call frame.  Default is zero.  Ignored if we don't know how to
  retrieve arguments on the platform.

CHECKSUMS       Reports on erroneously clear dirty bits, and unexpectedly
  altered stubborn objects, at substantial performance cost.  Use only for
  debugging of the incremental collector.  Not compatible with USE_MUNMAP
  or threads.

GC_GCJ_SUPPORT  Includes support for gcj (and possibly other systems
  that include a pointer to a type descriptor in each allocated object).
  Building this way requires an ANSI C compiler.

USE_I686_PREFETCH       Causes the collector to issue Pentium III style
  prefetch instructions.  No effect except on X86 Linux platforms.
  Assumes a very recent gcc-compatible compiler and assembler.
  (Gas prefetcht0 support was added around May 1999.)
  Empirically the code appears to still run correctly on Pentium II
  processors, though with no performance benefit.  May not run on other
  X86 processors?  In some cases this improves performance by
  15% or so.

USE_3DNOW_PREFETCH      Causes the collector to issue AMD 3DNow style
  prefetch instructions.  Same restrictions as USE_I686_PREFETCH.
  Minimally tested.  Didn't appear to be an obvious win on a K6-2/500.

USE_PPC_PREFETCH        Causes the collector to issue PowerPC style
  prefetch instructions.  No effect except on PowerPC OS X platforms.
  Performance impact untested.

GC_USE_LD_WRAP  In combination with the old flags listed in README.linux
  causes the collector some system and pthread calls in a more transparent
  fashion than the usual macro-based approach.  Requires GNU ld, and
  currently probably works only with Linux.

GC_USE_DLOPEN_WRAP      Causes the collector to redefine malloc and
  intercepted pthread routines with their real names, and causes it to use
  dlopen and dlsym to refer to the original versions.  This makes it possible
  to build an LD_PRELOADable malloc replacement library.

THREAD_LOCAL_ALLOC      Defines GC_malloc(), GC_malloc_atomic() and
  GC_gcj_malloc() to use a per-thread set of free-lists. These then allocate
  in a way that usually does not involve acquisition of a global lock.
  Recommended for multiprocessors.  Requires explicit GC_INIT() call, unless
  REDIRECT_MALLOC is defined and GC_malloc is used first.

USE_COMPILER_TLS        Causes thread local allocation to use
  the compiler-supported "__thread" thread-local variables.  This is the
  default in HP/UX.  It may help performance on recent Linux installations.
  (It failed for me on RedHat 8, but appears to work on RedHat 9.)

PARALLEL_MARK   Allows the marker to run in multiple threads.  Recommended
  for multiprocessors.

GC_WINMAIN_REDIRECT (Win32 only)        Redirect (rename) an application
  WinMain to GC_WinMain; implement the "real" WinMain which starts a new
  thread to call GC_WinMain after initializing the GC.  Useful for WinCE.
  Incompatible with GC_DLL.

GC_REGISTER_MEM_PRIVATE (Win32 only)    Force to register MEM_PRIVATE R/W
  sections as data roots.  Might be needed for some WinCE 6.0+ custom builds.
  (May result in numerous "Data Abort" messages logged to WinCE debugging
  console.)  Incompatible with GCC toolchains for WinCE.

NO_GETENV       Prevents the collector from looking at environment variables.
  These may otherwise alter its configuration, or turn off GC altogether.
  I don't know of a reason to disable this, except possibly if the resulting
  process runs as a privileged user.  (This is on by default for WinCE.)

EMPTY_GETENV_RESULTS    Define to workaround a reputed Wine bug in getenv
  (getenv() may return an empty string instead of NULL for a missing entry).

GC_READ_ENV_FILE (Win32 only)   Read environment variables from the GC "env"
  file (named as the program name plus ".gc.env" extension).  Useful for WinCE
  targets (which have no getenv()).  In the file, every variable is specified
  in a separate line and the format is as "<name>=<value>" (without spaces).
  A comment line may start with any character except for the Latin letters,
  the digits and the underscore ('_').  The file encoding is Latin-1.

USE_GLOBAL_ALLOC (Win32 only)   Use GlobalAlloc() instead of VirtualAlloc()
  to allocate the heap.  May be needed to work around a Windows NT/2000 issue.
  Incompatible with USE_MUNMAP.  See README.win32 for details.

MAKE_BACK_GRAPH         Enable GC_PRINT_BACK_HEIGHT environment variable.
  See README.environment for details.  Experimental.  Limited platform
  support.  Implies DBG_HDRS_ALL.  All allocation should be done using
  the debug interface.

GC_PRINT_BACK_HEIGHT    Permanently turn on back-height printing mode
  (useful when NO_GETENV).  See the similar environment variable description
  in README.environment.  Requires MAKE_BACK_GRAPH defined.

STUBBORN_ALLOC  Allows allocation of "hard to change" objects, and thus
  makes incremental collection easier.  Was enabled by default until 6.0.
  Rarely used, to my knowledge.

HANDLE_FORK (Unix and Cygwin only)      Attempt by default to make GC_malloc()
  work in a child process fork()'ed from a multi-threaded parent.  Not fully
  POSIX-compliant and could be disabled at runtime (before GC_INIT).

TEST_WITH_SYSTEM_MALLOC         Causes gctest to allocate (and leak) large
  chunks of memory with the standard system malloc.  This will cause the root
  set and collected heap to grow significantly if malloc'ed memory is somehow
  getting traced by the collector.  This has no impact on the generated
  library; it only affects the test.

POINTER_MASK=<0x...>    Causes candidate pointers to be AND'ed with the given
  mask before being considered.  If either this or the following macro is
  defined, it will be assumed that all pointers stored in the heap need to be
  processed this way.  Stack and register pointers will be considered both
  with and without processing.  These macros are normally needed only to
  support systems that use high-order pointer tags.  EXPERIMENTAL.

POINTER_SHIFT=<n>       Causes the collector to left shift candidate pointers
  by the indicated amount before trying to interpret them.  Applied after
  POINTER_MASK. EXPERIMENTAL.  See also the preceding macro.

ENABLE_TRACE    Enables the GC_TRACE=addr environment setting to do its job.
  By default this is not supported in order to keep the marker as fast as
  possible.

DARWIN_DONT_PARSE_STACK         Causes the Darwin port to discover thread
  stack bounds in the same way as other pthread ports, without trying to
  walk the frames on the stack.  This is recommended only as a fall-back for
  applications that don't support proper stack unwinding.

GC_NO_THREADS_DISCOVERY (Darwin and Win32+DLL only)     Exclude DllMain-based
  (on Windows) and task-threads-based (on Darwin) thread registration support.

GC_INSIDE_DLL (Win32 only)      Enable DllMain-based approach of threads
  registering even in case GC_DLL is not defined.

GC_DISCOVER_TASK_THREADS (Darwin and Win32+DLL only)    Compile the collector
  with the implicitly turned on task-threads-based (on Darwin) or
  DllMain-based (on Windows) approach of threads registering.  Only for
  compatibility and for the case when it is not possible to call
  GC_use_threads_discovery() early (before other GC calls).

USE_PROC_FOR_LIBRARIES  Causes the Linux collector to treat writable
  memory mappings (as reported by /proc) as roots, if it doesn't have
  other information about them.  It no longer traverses dynamic loader
  data structures to find dynamic library static data.  This may be
  required for applications that store pointers in mmapped segments without
  informing the collector.  But it typically performs poorly, especially
  since it will scan inactive but cached NPTL thread stacks completely.

IGNORE_DYNAMIC_LOADING  Don't define DYNAMIC_LOADING even if supported by the
  platform (that is, build the collector with disabled tracing of dynamic
  library data roots).

NO_PROC_STAT    Causes the collector to avoid relying on Linux
  "/proc/self/stat".

NO_GETCONTEXT   Causes the collector to not assume the existence of the
  getcontext() function on linux-like platforms.  This currently happens
  implicitly on Darwin, Hurd, or ARM or MIPS hardware.  It is explicitly
  needed for some old versions of FreeBSD.

STATIC=static   Causes various GC_ symbols that could logically be declared
  static to be declared (this is the default if NO_DEBUGGING is specified).
  Reduces the number of visible symbols (letting the optimizer do its work
  better), which is probably cleaner, but may make some kinds of debugging
  and profiling harder.

GC_DLL  Build dynamic-link library (or dynamic shared object).  For Unix this
  causes the exported symbols to have 'default' visibility (ignored unless
  GCC v4+) and the internal ones to have 'hidden' visibility.

DONT_USE_USER32_DLL (Win32 only)        Don't use "user32" DLL import library
  (containing MessageBox() entry); useful for a static GC library.

GC_PREFER_MPROTECT_VDB  Choose MPROTECT_VDB manually in case of multiple
  virtual dirty bit strategies are implemented (at present useful on Win32 and
  Solaris to force MPROTECT_VDB strategy instead of the default GWW_VDB or
  PROC_VDB ones).

GC_IGNORE_GCJ_INFO      Disable GCJ-style type information (useful for
  debugging on WinCE).

GC_PRINT_VERBOSE_STATS  Permanently turn on verbose logging (useful for
  debugging and profiling on WinCE).

GC_ONLY_LOG_TO_FILE     Don't redirect GC stdout and stderr to the log file
  specified by GC_LOG_FILE environment variable.  Has effect only when the
  variable is set (to anything other than "0").

GC_ANDROID_LOG (Android only)   Output error/debug information to Android log.

GC_DONT_EXPAND  Don't expand the heap unless explicitly requested or forced to.

GC_USE_ENTIRE_HEAP      Causes the non-incremental collector to use the
  entire heap before collecting.  This sometimes results in more large block
  fragmentation, since very large blocks will tend to get broken up during
  each GC cycle.  It is likely to result in a larger working set, but lower
  collection frequencies, and hence fewer instructions executed in the
  collector.  This macro controls only the default GC_use_entire_heap value.

GC_INITIAL_HEAP_SIZE=<value>    Set the desired default initial heap size
  in bytes.

GC_FREE_SPACE_DIVISOR=<value>   Set alternate default GC_free_space_divisor
  value.

GC_TIME_LIMIT=<milliseconds>    Set alternate default GC_time_limit value
  (setting this to GC_TIME_UNLIMITED will essentially disable incremental
  collection while leaving generational collection enabled).

GC_FULL_FREQ=<value>    Set alternate default number of partial collections
  between full collections (matters only if incremental collection is on).

NO_CANCEL_SAFE (Posix platforms with threads only)      Don't bother trying
  to make the collector safe for thread cancellation; cancellation is not
  used.  (Note that if cancellation is used anyway, threads may end up
  getting cancelled in unexpected places.)  Even without this option,
  PTHREAD_CANCEL_ASYNCHRONOUS is never safe with the collector.  (We could
  argue about its safety without the collector.)

UNICODE (Win32 only)    Use the Unicode variant ('W') of the Win32 API instead
  of ANSI/ASCII one ('A').  Useful for WinCE.

PLATFORM_ANDROID (or __ANDROID__)       Compile for Android NDK platform.

SN_TARGET_PS3           Compile for Sony PS/3.

USE_GET_STACKBASE_FOR_MAIN (Linux only)  Use pthread_attr_getstack() instead
  of __libc_stack_end (or instead of any hard-coded value) for getting the
  primordial thread stack base (useful if the client modifies the program's
  address space).

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 ...)

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 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 in this version, though there may exist other
ports.

Pthreads support is provided.  This requires that:

1) You compile the collector with -DGC_IRIX_THREADS specified in the Makefile.

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 IRIX_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_timed_wait should be prepared for
premature wakeups.  (I believe the pthreads and realted 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.

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:

Threads support is enabled by configure "--enable-threads=posix" option.
(In case of GCC compiler, multi-threading support is on by default.)
This causes the collector to be compiled with -D GC_THREADS (or
-D GC_SOLARIS_THREADS) ensuring thread safety.
This assumes use of the pthread_ interface.  Old style Solaris threads
are no longer supported.
Thread-local allocation is now on by default.  Parallel marking is on by
default starting from GC v7.3 but it could be enabled or disabled manually
by the corresponding "--enable/disable-parallel-mark" options.

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 one or both of these macros
defined, otherwise these replacements are not visible.  A collector built in
this way way only be used by programs that are linked with the threads library.

Since 5.0 alpha5, dlopen disables collection temporarily,
unless USE_PROC_FOR_LIBRARIES is defined.  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.)

It appears that there is a problem in using gc_cpp.h in conjunction with
Solaris threads and Sun's C++ runtime.  Apparently the overloaded new operator
is invoked by some iostream initialization code before threads are correctly
initialized.  As a result, call to thr_self() in garbage collector
initialization  SEGV faults.  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>: offet .... 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 tool chain.  (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.)

Instructions for Symbian:
1. base version: libgc 7.1
2. Build: use libgc.mmp
3. Limitations
3.1.No multi-threaded support

3.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.

Alistair Crooks supplied the port.  He used Lexa C version 2.1.3 with
-Xa to compile.

The collector has at various times been compiled under Windows 95 & 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 4.5,  with Watcom C, and recently
with the Digital Mars compiler.  It is likely that some of these have been
broken in the meantime.  Patches are appreciated.

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.

The cord test program has not been ported (but should port
easily).  A toy editor (cord/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
in 6.1alpha4, 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, rename NT_MAKEFILE as
MAKEFILE.  (Make sure that the CPU environment variable is defined
to be i386.)  In order to use the gc_cpp.h C++ interface, all
client code should include gc_cpp.h.

For historical reasons,
the collector test program "gctest" is linked as a GUI application,
but does not open any windows.  Its output 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.

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 (as it normally is in the
absence of thread support).

GNU Tools
---------
The collector should be buildable under Cygwin with the
"./configure; make check" machinery.

MinGW builds (including for x86_64) are available via cross-compilation, e.g.
"./configure --host=i686-pc-mingw32; make check"

To build the collector as a DLL, pass "--enable-shared --disable-static" to
configure (this will instruct make compile with -D GC_DLL).

Parallel marker could be enabled via "--enable-parallel-mark".
Memory unmapping could be enabled via "--enable-munmap".

Borland Tools
-------------
[Rarely tested.]
For Borland tools, use BCC_MAKEFILE.  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.)
The Makefile is set up to assume Borland 4.5.  If you have another
version, change the line near the top.  By default, it does not
require the assembler.  If you do have the assembler, I recommend
removing the -DUSE_GENERIC.

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 compiled with Watcom C 10.6 and 11.0.
It runs under win32, win32s, and even under msdos 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 not supported.

cord is not ported.

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 and testing programs 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.


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
-------

This version of 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.

Use gc.mak (a.k.a NT_THREADS_MAKEFILE) instead of NT_MAKEFILE
to build a version that supports both kinds of thread tracking.
To build the garbage collector
test with VC++ from the command line, use

nmake /F ".\gc.mak" CFG="gctest - Win32 Release"

This requires that the subdirectory gctest\Release exist.
The test program and DLL will reside in the Release directory.

This version currently supports incremental collection only if it is
enabled before any additional threads are created.

Since 6.3alpha2, threads are also better supported in static library builds
with Microsoft tools (use NT_STATIC_THREADS_MAKEFILE) and with the GNU
tools.  The collector must be built with GC_THREADS defined.
(NT_STATIC_THREADS_MAKEFILE does this implicitly.  Under Cygwin,
./configure --enable-threads=posix should be used.)

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, use standard pthread calls 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
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 executable before other GC calls.

We strongly advise against using the TerminateThread() win32 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,
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.

64-bit Windows on AMD64/Intel EM64T is somewhat supported in the 7.0
and later release.  A collector can be built with Microsoft Visual C++ 2005
or with mingw-w64 gcc.
More testing would clearly be helpful.

NT_X64_STATIC_THREADS_MAKEFILE has been used in
this environment.  Copy this file to MAKEFILE, and then type "nmake"
in a Visual C++ command line window to build the static library
and the usual test programs.  To verify that the collector is
at least somewhat functional, run gctest.exe.  This should create
gctest.gc.log after a few seconds.

This process is completely analogous to NT_STATIC_THREADS_MAKEFILE
for the 32-bit version.

A similar procedure using NT_X64_THREADS_MAKEFILE should be usable to
build the dynamic library.  Test_cpp.exe did not seem to run correctly this
way.  It seems that we're getting the wrong instances of operator new/delete
in some cases.  The C tests seemed OK.

Note that currently a few warnings are still generated by default,
and a number of others have been explicitly turned off in the makefile.

VC++ note: to suppress warnings use -D_CRT_SECURE_NO_DEPRECATE.

gcc note: -fno-strict-aliasing should be used if optimizing.