Return to README.linux CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc / doc

Annotation of OpenXM_contrib2/asir2000/gc/doc/README.linux, Revision 1.1

1.1     ! noro        1: See README.alpha for Linux on DEC AXP info.
        !             2:
        !             3: This file applies mostly to Linux/Intel IA32.  Ports to Linux on an M68K
        !             4: and PowerPC are also integrated.  They should behave similarly, except that
        !             5: the PowerPC port lacks incremental GC support, and it is unknown to what
        !             6: extent the Linux threads code is functional.  See below for M68K specific
        !             7: notes.
        !             8:
        !             9: Incremental GC is supported on Intel IA32 and M68K.
        !            10:
        !            11: Dynamic libraries are supported on an ELF system.  A static executable
        !            12: should be linked with the gcc option "-Wl,-defsym,_DYNAMIC=0".
        !            13:
        !            14: The collector appears to work with Linux threads.  We have seen
        !            15: intermittent hangs in sem_wait.  So far we have been unable to reproduce
        !            16: these unless the process was being debugged or traced.  Thus it's
        !            17: possible that the only real issue is that the debugger loses
        !            18: signals on rare occasions.
        !            19:
        !            20: The garbage collector uses SIGPWR and SIGXCPU if it is used with
        !            21: Linux threads.  These should not be touched by the client program.
        !            22:
        !            23: To use threads, you need to abide by the following requirements:
        !            24:
        !            25: 1) You need to use LinuxThreads (which are included in libc6).
        !            26:
        !            27:    The collector relies on some implementation details of the LinuxThreads
        !            28:    package.  It is unlikely that this code will work on other
        !            29:    pthread implementations (in particular it will *not* work with
        !            30:    MIT pthreads).
        !            31:
        !            32: 2) You must compile the collector with -DGC_LINUX_THREADS and -D_REENTRANT
        !            33:    specified in the Makefile.
        !            34:
        !            35: 3a) Every file that makes thread calls should define GC_LINUX_THREADS and
        !            36:    _REENTRANT and then include gc.h.  Gc.h redefines some of the
        !            37:    pthread primitives as macros which also provide the collector with
        !            38:    information it requires.
        !            39:
        !            40: 3b) A new alternative to (3a) is to build the collector and compile GC clients
        !            41:    with -DGC_USE_LD_WRAP, and to link the final program with
        !            42:
        !            43:    (for ld) --wrap read --wrap dlopen --wrap pthread_create \
        !            44:            --wrap pthread_join --wrap pthread_detach \
        !            45:            --wrap pthread_sigmask --wrap sleep
        !            46:
        !            47:    (for gcc) -Wl,--wrap -Wl,read -Wl,--wrap -Wl,dlopen -Wl,--wrap \
        !            48:             -Wl,pthread_create -Wl,--wrap -Wl,pthread_join -Wl,--wrap \
        !            49:             -Wl,pthread_detach -Wl,--wrap -Wl,pthread_sigmask \
        !            50:             -Wl,--wrap -Wl,sleep
        !            51:
        !            52:    In any case, _REENTRANT should be defined during compilation.
        !            53:
        !            54: 4) Dlopen() disables collection during its execution.  (It can't run
        !            55:    concurrently with the collector, since the collector looks at its
        !            56:    data structures.  It can't acquire the allocator lock, since arbitrary
        !            57:    user startup code may run as part of dlopen().)  Under unusual
        !            58:    conditions, this may cause unexpected heap growth.
        !            59:
        !            60: 5) The combination of GC_LINUX_THREADS, REDIRECT_MALLOC, and incremental
        !            61:    collection fails in seemingly random places.  This hasn't been tracked
        !            62:    down yet, but is perhaps not completely astonishing.  The thread package
        !            63:    uses malloc, and thus can presumably get SIGSEGVs while inside the
        !            64:    package.  There is no real guarantee that signals are handled properly
        !            65:    at that point.
        !            66:
        !            67: 6) Thread local storage may not be viewed as part of the root set by the
        !            68:    collector.  This probably depends on the linuxthreads version.  For the
        !            69:    time being, any collectable memory referenced by thread local storage should
        !            70:    also be referenced from elsewhere, or be allocated as uncollectable.
        !            71:    (This is really a bug that should be fixed somehow.)
        !            72:
        !            73:
        !            74: M68K LINUX:
        !            75: (From Richard Zidlicky)
        !            76: The bad news is that it can crash every linux-m68k kernel on a 68040,
        !            77: so an additional test is needed somewhere on startup. I have meanwhile
        !            78: patches to correct the problem in 68040 buserror handler but it is not
        !            79: yet in any standard kernel.
        !            80:
        !            81: Here is a simple test program to detect whether the kernel has the
        !            82: problem. It could be run as a separate check in configure or tested
        !            83: upon startup. If it fails (return !0) than mprotect can't be used
        !            84: on that system.
        !            85:
        !            86: /*
        !            87:  * test for bug that may crash 68040 based Linux
        !            88:  */
        !            89:
        !            90: #include <sys/mman.h>
        !            91: #include <signal.h>
        !            92: #include <unistd.h>
        !            93: #include <stdio.h>
        !            94: #include <stdlib.h>
        !            95:
        !            96:
        !            97: char *membase;
        !            98: int pagesize=4096;
        !            99: int pageshift=12;
        !           100: int x_taken=0;
        !           101:
        !           102: int sighandler(int sig)
        !           103: {
        !           104:    mprotect(membase,pagesize,PROT_READ|PROT_WRITE);
        !           105:    x_taken=1;
        !           106: }
        !           107:
        !           108: main()
        !           109: {
        !           110:   long l;
        !           111:
        !           112:    signal(SIGSEGV,sighandler);
        !           113:    l=(long)mmap(NULL,pagesize,PROT_READ,MAP_PRIVATE | MAP_ANON,-1,0);
        !           114:   if (l==-1)
        !           115:      {
        !           116:        perror("mmap/malloc");
        !           117:        abort();
        !           118:      }
        !           119:   membase=(char*)l;
        !           120:     *(long*)(membase+sizeof(long))=123456789;
        !           121:   if (*(long*)(membase+sizeof(long)) != 123456789 )
        !           122:     {
        !           123:       fprintf(stderr,"writeback failed !\n");
        !           124:       exit(1);
        !           125:     }
        !           126:   if (!x_taken)
        !           127:     {
        !           128:       fprintf(stderr,"exception not taken !\n");
        !           129:       exit(1);
        !           130:     }
        !           131:   fprintf(stderr,"vmtest Ok\n");
        !           132:   exit(0);
        !           133: }
        !           134:
        !           135: