readme

linux下建立JAVA虚拟机的源码KAFFE

(e.g. GC_mark_rts.c) you simply list your version ahead of gc.a on the
ld command line, rather than replacing the one in gc.a.  (This will
generate numerous warnings under some versions of AIX, but it still
works.)

  All include files that need to be used by clients will be put in the
include subdirectory.  (Normally this is just gc.h.  "Make cords" adds
"cord.h" and "ec.h".)

  The collector currently is designed to run essentially unmodified on
machines that use a flat 32-bit or 64-bit address space.
That includes the vast majority of Workstations and X86 (X >= 3) PCs.
(The list here was deleted because it was getting too long and constantly
out of date.)
  It does NOT run under plain 16-bit DOS or Windows 3.X.  There are however
various packages (e.g. win32s, djgpp) that allow flat 32-bit address
applications to run under those systemsif the have at least an 80386 processor,
and several of those are compatible with the collector.

  In a few cases (Amiga, OS/2, Win32, MacOS) a separate makefile
or equivalent is supplied.  Many of these have separate README.system
files.

  Dynamic libraries are completely supported only under SunOS/Solaris,
(and even that support is not functional on the last Sun 3 release),
Linux, FreeBSD, NetBSD, IRIX 5&6, HP/UX, Win32 (not Win32S) and OSF/1
on DEC AXP machines plus perhaps a few others listed near the top
of dyn_load.c.  On other machines we recommend that you do one of
the following:

  1) Add dynamic library support (and send us the code).
  2) Use static versions of the libraries.
  3) Arrange for dynamic libraries to use the standard malloc.
     This is still dangerous if the library stores a pointer to a
     garbage collected object.  But nearly all standard interfaces
     prohibit this, because they deal correctly with pointers
     to stack allocated objects.  (Strtok is an exception.  Don't
     use it.)

  In all cases we assume that pointer alignment is consistent with that
enforced by the standard C compilers.  If you use a nonstandard compiler
you may have to adjust the alignment parameters defined in gc_priv.h.
Note that this may also be an issue with packed records/structs, if those
enforce less alignment for pointers.

  A port to a machine that is not byte addressed, or does not use 32 bit
or 64 bit addresses will require a major effort.  A port to plain MSDOS
or win16 is hard.

  For machines not already mentioned, or for nonstandard compilers, the
following are likely to require change:

1.  The parameters in gcconfig.h.
      The parameters that will usually require adjustment are
   STACKBOTTOM,  ALIGNMENT and DATASTART.  Setjmp_test
   prints its guesses of the first two.
      DATASTART should be an expression for computing the
   address of the beginning of the data segment.  This can often be
   &etext.  But some memory management units require that there be
   some unmapped space between the text and the data segment.  Thus
   it may be more complicated.   On UNIX systems, this is rarely
   documented.  But the adb "$m" command may be helpful.  (Note
   that DATASTART will usually be a function of &etext.  Thus a
   single experiment is usually insufficient.)
     STACKBOTTOM is used to initialize GC_stackbottom, which
   should be a sufficient approximation to the coldest stack address.
   On some machines, it is difficult to obtain such a value that is
   valid across a variety of MMUs, OS releases, etc.  A number of
   alternatives exist for using the collector in spite of this.  See the
   discussion in gcconfig.h immediately preceding the various
   definitions of STACKBOTTOM.
   
2.  mach_dep.c.
      The most important routine here is one to mark from registers.
    The distributed file includes a generic hack (based on setjmp) that
    happens to work on many machines, and may work on yours.  Try
    compiling and running setjmp_t.c to see whether it has a chance of
    working.  (This is not correct C, so don't blame your compiler if it
    doesn't work.  Based on limited experience, register window machines
    are likely to cause trouble.  If your version of setjmp claims that
    all accessible variables, including registers, have the value they
    had at the time of the longjmp, it also will not work.  Vanilla 4.2 BSD
    on Vaxen makes such a claim.  SunOS does not.)
      If your compiler does not allow in-line assembly code, or if you prefer
    not to use such a facility, mach_dep.c may be replaced by a .s file
    (as we did for the MIPS machine and the PC/RT).
      At this point enough architectures are supported by mach_dep.c
    that you will rarely need to do more than adjust for assembler
    syntax.

3.  os_dep.c (and gc_priv.h).
  	  Several kinds of operating system dependent routines reside here.
  	Many are optional.  Several are invoked only through corresponding
  	macros in gc_priv.h, which may also be redefined as appropriate.
      The routine GC_register_data_segments is crucial.  It registers static
    data areas that must be traversed by the collector. (User calls to
    GC_add_roots may sometimes be used for similar effect.)
      Routines to obtain memory from the OS also reside here.
    Alternatively this can be done entirely by the macro GET_MEM
    defined in gc_priv.h.  Routines to disable and reenable signals
    also reside here if they are need by the macros DISABLE_SIGNALS
    and ENABLE_SIGNALS defined in gc_priv.h.
      In a multithreaded environment, the macros LOCK and UNLOCK
    in gc_priv.h will need to be suitably redefined.
      The incremental collector requires page dirty information, which
    is acquired through routines defined in os_dep.c.  Unless directed
    otherwise by gcconfig.h, these are implemented as stubs that simply
    treat all pages as dirty.  (This of course makes the incremental
    collector much less useful.)

4.  dyn_load.c
	This provides a routine that allows the collector to scan data
	segments associated with dynamic libraries.  Often it is not
	necessary to provide this routine unless user-written dynamic
	libraries are used.

  For a different version of UN*X or different machines using the
Motorola 68000, Vax, SPARC, 80386, NS 32000, PC/RT, or MIPS architecture,
it should frequently suffice to change definitions in gcconfig.h.


THE C INTERFACE TO THE ALLOCATOR

  The following routines are intended to be directly called by the user.
Note that usually only GC_malloc is necessary.  GC_clear_roots and GC_add_roots
calls may be required if the collector has to trace from nonstandard places
(e.g. from dynamic library data areas on a machine on which the 
collector doesn't already understand them.)  On some machines, it may
be desirable to set GC_stacktop to a good approximation of the stack base. 
(This enhances code portability on HP PA machines, since there is no
good way for the collector to compute this value.)  Client code may include
"gc.h", which defines all of the following, plus many others.

1)  GC_malloc(nbytes)
    - allocate an object of size nbytes.  Unlike malloc, the object is
      cleared before being returned to the user.  Gc_malloc will
      invoke the garbage collector when it determines this to be appropriate.
      GC_malloc may return 0 if it is unable to acquire sufficient
      space from the operating system.  This is the most probable
      consequence of running out of space.  Other possible consequences
      are that a function call will fail due to lack of stack space,
      or that the collector will fail in other ways because it cannot
      maintain its internal data structures, or that a crucial system
      process will fail and take down the machine.  Most of these
      possibilities are independent of the malloc implementation.

2)  GC_malloc_atomic(nbytes)
    - allocate an object of size nbytes that is guaranteed not to contain any
      pointers.  The returned object is not guaranteed to be cleared.
      (Can always be replaced by GC_malloc, but results in faster collection
      times.  The collector will probably run faster if large character
      arrays, etc. are allocated with GC_malloc_atomic than if they are
      statically allocated.)

3)  GC_realloc(object, new_size)
    - change the size of object to be new_size.  Returns a pointer to the
      new object, which may, or may not, be the same as the pointer to
      the old object.  The new object is taken to be atomic iff the old one
      was.  If the new object is composite and larger than the original object,
      then the newly added bytes are cleared (we hope).  This is very likely
      to allocate a new object, unless MERGE_SIZES is defined in gc_priv.h.
      Even then, it is likely to recycle the old object only if the object
      is grown in small additive increments (which, we claim, is generally bad
      coding practice.)

4)  GC_free(object)
    - explicitly deallocate an object returned by GC_malloc or
      GC_malloc_atomic.  Not necessary, but can be used to minimize
      collections if performance is critical.  Probably a performance
      loss for very small objects (<= 8 bytes).

5)  GC_expand_hp(bytes)
    - Explicitly increase the heap size.  (This is normally done automatically
      if a garbage collection failed to GC_reclaim enough memory.  Explicit
      calls to GC_expand_hp may prevent unnecessarily frequent collections at
      program startup.)

6)  GC_malloc_ignore_off_page(bytes)
	- identical to GC_malloc, but the client promises to keep a pointer to
	  the somewhere within the first 256 bytes of the object while it is
	  live.  (This pointer should nortmally be declared volatile to prevent
	  interference from compiler optimizations.)  This is the recommended
	  way to allocate anything that is likely to be larger than 100Kbytes
	  or so.  (GC_malloc may result in failure to reclaim such objects.)

7)  GC_set_warn_proc(proc)
	- Can be used to redirect warnings from the collector.  Such warnings
	  should be rare, and should not be ignored during code development.
      
8) GC_enable_incremental()
    - Enables generational and incremental collection.  Useful for large
      heaps on machines that provide access to page dirty information.
      Some dirty bit implementations may interfere with debugging
      (by catching address faults) and place restrictions on heap arguments
      to system calls (since write faults inside a system call may not be
      handled well).

9) Several routines to allow for registration of finalization code.
   User supplied finalization code may be invoked when an object becomes
   unreachable.  To call (*f)(obj, x) when obj becomes inaccessible, use
	GC_register_finalizer(obj, f, x, 0, 0);
   For more sophisticated uses, and for finalization ordering issues,
   see gc.h.

  The global variable GC_free_space_divisor may be adjusted up from its
default value of 4 to use less space and more collection time, or down for
the opposite effect.  Setting it to 1 or 0 will effectively disable collections
and cause all allocations to simply grow the heap.