Debian Codegraph @

gc/doc/README.linux

raw
1 See README.alpha for Linux on DEC AXP info.
2
3 This file applies mostly to Linux/Intel IA-32. Ports to Linux on an M68K,
4 IA-64, SPARC, MIPS, Alpha and PowerPC are integrated too. They should behave
5 similarly, except that the PowerPC port lacks incremental GC support, and
6 it is unknown to what extent the Linux threads code is functional.
7 See below for M68K specific notes.
8
9 Incremental GC is generally supported.
10
11 Dynamic libraries are supported on an ELF system.
12
13 The collector appears to work reliably with Linux threads, but beware
14 of older versions of glibc and gdb.
15
16 The garbage collector uses SIGPWR and SIGXCPU if it is used with
17 Linux threads. These should not be touched by the client program.
18
19 To use threads, you need to abide by the following requirements:
20
21 1) You need to use LinuxThreads or NPTL (which are included in libc6).
22
23 The collector relies on some implementation details of the LinuxThreads
24 package. This code may not work on other
25 pthread implementations (in particular it will *not* work with
26 MIT pthreads).
27
28 2) You must compile the collector with "-DGC_THREADS -D_REENTRANT" specified
29 in the Makefile.direct file.
30
31 3a) Every file that makes thread calls should define GC_THREADS, and then
32 include gc.h. The latter redefines some of the pthread primitives as
33 macros which also provide the collector with information it requires.
34
35 3b) A new alternative to (3a) is to build the collector and compile GC clients
36 with -DGC_USE_LD_WRAP, and to link the final program with
37
38 (for ld) --wrap dlopen --wrap pthread_create \
39 --wrap pthread_join --wrap pthread_detach \
40 --wrap pthread_sigmask --wrap pthread_exit --wrap pthread_cancel
41
42 (for gcc) -Wl,--wrap -Wl,dlopen -Wl,--wrap -Wl,pthread_create \
43 -Wl,--wrap -Wl,pthread_join -Wl,--wrap -Wl,pthread_detach \
44 -Wl,--wrap -Wl,pthread_sigmask -Wl,--wrap -Wl,pthread_exit \
45 -Wl,--wrap -Wl,pthread_cancel
46
47 In any case, _REENTRANT should be defined during compilation.
48
49 4) Dlopen() disables collection during its execution. (It can't run
50 concurrently with the collector, since the collector looks at its
51 data structures. It can't acquire the allocator lock, since arbitrary
52 user startup code may run as part of dlopen().) Under unusual
53 conditions, this may cause unexpected heap growth.
54
55 5) The combination of GC_THREADS, REDIRECT_MALLOC, and incremental
56 collection is probably not fully reliable, though it now seems to work
57 in simple cases.
58
59 6) Thread local storage may not be viewed as part of the root set by the
60 collector. This probably depends on the linuxthreads version. For the
61 time being, any collectible memory referenced by thread local storage
62 should also be referenced from elsewhere, or be allocated as uncollectible.
63 (This is really a bug that should be fixed somehow. Actually, the
64 collector probably gets things right, on Linux at least, if there are not
65 too many tls locations and if dlopen is not used.)
66
67
68 M68K LINUX:
69 (From Richard Zidlicky)
70 The bad news is that it can crash every linux-m68k kernel on a 68040,
71 so an additional test is needed somewhere on startup. I have meanwhile
72 patches to correct the problem in 68040 buserror handler but it is not
73 yet in any standard kernel.
74
75 Here is a simple test program to detect whether the kernel has the
76 problem. It could be run as a separate check in configure or tested
77 upon startup. If it fails (return !0) than mprotect can't be used
78 on that system.
79
80 /*
81 * test for bug that may crash 68040 based Linux
82 */
83
84 #include <sys/mman.h>
85 #include <signal.h>
86 #include <unistd.h>
87 #include <stdio.h>
88 #include <stdlib.h>
89
90
91 char *membase;
92 int pagesize=4096;
93 int pageshift=12;
94 int x_taken=0;
95
96 int sighandler(int sig)
97 {
98 mprotect(membase,pagesize,PROT_READ|PROT_WRITE);
99 x_taken=1;
100 }
101
102 main()
103 {
104 long l;
105
106 signal(SIGSEGV,sighandler);
107 l=(long)mmap(NULL,pagesize,PROT_READ,MAP_PRIVATE | MAP_ANON,-1,0);
108 if (l==-1)
109 {
110 perror("mmap/malloc");
111 abort();
112 }
113 membase=(char*)l;
114 *(long*)(membase+sizeof(long))=123456789;
115 if (*(long*)(membase+sizeof(long)) != 123456789 )
116 {
117 fprintf(stderr,"writeback failed !\n");
118 exit(1);
119 }
120 if (!x_taken)
121 {
122 fprintf(stderr,"exception not taken !\n");
123 exit(1);
124 }
125 fprintf(stderr,"vmtest Ok\n");
126 exit(0);
127 }