move the "meat" into the wiki, this file just contains pointers now
[ghc.git] / includes / InfoTables.h
1 /* ----------------------------------------------------------------------------
2 *
3 * (c) The GHC Team, 1998-2002
4 *
5 * Info Tables
6 *
7 * -------------------------------------------------------------------------- */
8
9 #ifndef INFOTABLES_H
10 #define INFOTABLES_H
11
12 /* -----------------------------------------------------------------------------
13 Profiling info
14 -------------------------------------------------------------------------- */
15
16 typedef struct {
17 char *closure_type;
18 char *closure_desc;
19 } StgProfInfo;
20
21 /* -----------------------------------------------------------------------------
22 Parallelism info
23 -------------------------------------------------------------------------- */
24
25 #if 0 && (defined(PAR) || defined(GRAN))
26
27 /* CURRENTLY UNUSED
28 ToDo: use this in StgInfoTable (mutually recursive) -- HWL */
29
30 typedef struct {
31 StgInfoTable *rbh_infoptr; /* infoptr to the RBH */
32 } StgParInfo;
33
34 #endif /* 0 */
35
36 /*
37 Copied from ghc-0.29; ToDo: check this code -- HWL
38
39 In the parallel system, all updatable closures have corresponding
40 revertible black holes. When we are assembly-mangling, we guarantee
41 that the revertible black hole code precedes the normal entry code, so
42 that the RBH info table resides at a fixed offset from the normal info
43 table. Otherwise, we add the RBH info table pointer to the end of the
44 normal info table and vice versa.
45
46 Currently has to use a !RBH_MAGIC_OFFSET setting.
47 Still todo: init of par.infoptr field in all infotables!!
48 */
49
50 #if defined(PAR) || defined(GRAN)
51
52 # ifdef RBH_MAGIC_OFFSET
53
54 # error magic offset not yet implemented
55
56 # define RBH_INFO_WORDS 0
57 # define INCLUDE_RBH_INFO(infoptr)
58
59 # define RBH_INFOPTR(infoptr) (((P_)infoptr) - RBH_MAGIC_OFFSET)
60 # define REVERT_INFOPTR(infoptr) (((P_)infoptr) + RBH_MAGIC_OFFSET)
61
62 # else
63
64 # define RBH_INFO_WORDS 1
65 # define INCLUDE_RBH_INFO(info) rbh_infoptr : &(info)
66
67 # define RBH_INFOPTR(infoptr) (((StgInfoTable *)(infoptr))->rbh_infoptr)
68 # define REVERT_INFOPTR(infoptr) (((StgInfoTable *)(infoptr))->rbh_infoptr)
69
70 # endif
71
72 /* see ParallelRts.h */
73 /*
74 EXTFUN(RBH_entry);
75 StgClosure *convertToRBH(StgClosure *closure);
76 #if defined(GRAN)
77 void convertFromRBH(StgClosure *closure);
78 #elif defined(PAR)
79 void convertToFetchMe(StgPtr closure, globalAddr *ga);
80 #endif
81 */
82
83 #endif
84
85 /* -----------------------------------------------------------------------------
86 Ticky info
87
88 There is no ticky-specific stuff in an info table at this time.
89 -------------------------------------------------------------------------- */
90
91 /* -----------------------------------------------------------------------------
92 Debugging info
93 -------------------------------------------------------------------------- */
94
95 #ifdef DEBUG_CLOSURE
96
97 typedef struct {
98 ... whatever ...
99 } StgDebugInfo;
100
101 #else /* !DEBUG_CLOSURE */
102
103 /* There is no DEBUG-specific stuff in an info table at this time. */
104
105 #endif /* DEBUG_CLOSURE */
106
107 /* -----------------------------------------------------------------------------
108 Closure flags
109 -------------------------------------------------------------------------- */
110
111 /* The type flags provide quick access to certain properties of a closure. */
112
113 #define _HNF (1<<0) /* head normal form? */
114 #define _BTM (1<<1) /* bitmap-style layout? */
115 #define _NS (1<<2) /* non-sparkable */
116 #define _STA (1<<3) /* static? */
117 #define _THU (1<<4) /* thunk? */
118 #define _MUT (1<<5) /* mutable? */
119 #define _UPT (1<<6) /* unpointed? */
120 #define _SRT (1<<7) /* has an SRT? */
121 #define _IND (1<<8) /* is an indirection? */
122
123 #define isSTATIC(flags) ((flags) &_STA)
124 #define isMUTABLE(flags) ((flags) &_MUT)
125 #define isBITMAP(flags) ((flags) &_BTM)
126 #define isTHUNK(flags) ((flags) &_THU)
127 #define isUNPOINTED(flags) ((flags) &_UPT)
128 #define hasSRT(flags) ((flags) &_SRT)
129
130 extern StgWord16 closure_flags[];
131
132 #define closureFlags(c) (closure_flags[get_itbl(c)->type])
133
134 #define closure_HNF(c) ( closureFlags(c) & _HNF)
135 #define closure_BITMAP(c) ( closureFlags(c) & _BTM)
136 #define closure_NON_SPARK(c) ( (closureFlags(c) & _NS))
137 #define closure_SHOULD_SPARK(c) (!(closureFlags(c) & _NS))
138 #define closure_STATIC(c) ( closureFlags(c) & _STA)
139 #define closure_THUNK(c) ( closureFlags(c) & _THU)
140 #define closure_MUTABLE(c) ( closureFlags(c) & _MUT)
141 #define closure_UNPOINTED(c) ( closureFlags(c) & _UPT)
142 #define closure_SRT(c) ( closureFlags(c) & _SRT)
143 #define closure_IND(c) ( closureFlags(c) & _IND)
144
145 /* same as above but for info-ptr rather than closure */
146 #define ipFlags(ip) (closure_flags[ip->type])
147
148 #define ip_HNF(ip) ( ipFlags(ip) & _HNF)
149 #define ip_BITMAP(ip) ( ipFlags(ip) & _BTM)
150 #define ip_SHOULD_SPARK(ip) (!(ipFlags(ip) & _NS))
151 #define ip_STATIC(ip) ( ipFlags(ip) & _STA)
152 #define ip_THUNK(ip) ( ipFlags(ip) & _THU)
153 #define ip_MUTABLE(ip) ( ipFlags(ip) & _MUT)
154 #define ip_UNPOINTED(ip) ( ipFlags(ip) & _UPT)
155 #define ip_SRT(ip) ( ipFlags(ip) & _SRT)
156 #define ip_IND(ip) ( ipFlags(ip) & _IND)
157
158 /* -----------------------------------------------------------------------------
159 Bitmaps
160
161 These are used to describe the pointerhood of a sequence of words
162 (usually on the stack) to the garbage collector. The two primary
163 uses are for stack frames, and functions (where we need to describe
164 the layout of a PAP to the GC).
165
166 In these bitmaps: 0 == ptr, 1 == non-ptr.
167 -------------------------------------------------------------------------- */
168
169 /*
170 * Small bitmaps: for a small bitmap, we store the size and bitmap in
171 * the same word, using the following macros. If the bitmap doesn't
172 * fit in a single word, we use a pointer to an StgLargeBitmap below.
173 */
174 #define MK_SMALL_BITMAP(size,bits) (((bits)<<BITMAP_BITS_SHIFT) | (size))
175
176 #define BITMAP_SIZE(bitmap) ((bitmap) & BITMAP_SIZE_MASK)
177 #define BITMAP_BITS(bitmap) ((bitmap) >> BITMAP_BITS_SHIFT)
178
179 /*
180 * A large bitmap.
181 */
182 typedef struct {
183 StgWord size;
184 StgWord bitmap[FLEXIBLE_ARRAY];
185 } StgLargeBitmap;
186
187 /* -----------------------------------------------------------------------------
188 SRTs (Static Reference Tables)
189
190 These tables are used to keep track of the static objects referred
191 to by the code for a closure or stack frame, so that we can follow
192 static data references from code and thus accurately
193 garbage-collect CAFs.
194 -------------------------------------------------------------------------- */
195
196 /* An SRT is just an array of closure pointers: */
197 typedef StgClosure* StgSRT[];
198
199 /*
200 * Each info table refers to some subset of the closure pointers in an
201 * SRT. It does this using a pair of an StgSRT pointer and a
202 * half-word bitmap. If the half-word bitmap isn't large enough, then
203 * we fall back to a large SRT, including an unbounded bitmap. If the
204 * half-word bitmap is set to all ones (0xffff), then the StgSRT
205 * pointer instead points to an StgLargeSRT:
206 */
207 typedef struct StgLargeSRT_ {
208 StgSRT *srt;
209 StgLargeBitmap l;
210 } StgLargeSRT;
211
212 /* ----------------------------------------------------------------------------
213 Relative pointers
214
215 Several pointer fields in info tables are expressed as offsets
216 relative to the info pointer, so that we can generate
217 position-independent code.
218
219 There is a complication on the x86_64 platform, where pointeres are
220 64 bits, but the tools don't support 64-bit relative relocations.
221 However, the default memory model (small) ensures that all symbols
222 have values in the lower 2Gb of the address space, so offsets all
223 fit in 32 bits. Hence we can use 32-bit offset fields.
224 ------------------------------------------------------------------------- */
225
226 #if x86_64_TARGET_ARCH
227 #define OFFSET_FIELD(n) StgHalfInt n; StgHalfWord __pad_##n;
228 #else
229 #define OFFSET_FIELD(n) StgInt n;
230 #endif
231
232 /* ----------------------------------------------------------------------------
233 Info Tables
234 ------------------------------------------------------------------------- */
235
236 /*
237 * Stuff describing the closure layout. Well, actually, it might
238 * contain the selector index for a THUNK_SELECTOR. This union is one
239 * word long.
240 */
241 typedef union {
242 struct { /* Heap closure payload layout: */
243 StgHalfWord ptrs; /* number of pointers */
244 StgHalfWord nptrs; /* number of non-pointers */
245 } payload;
246
247 StgWord bitmap; /* word-sized bit pattern describing */
248 /* a stack frame: see below */
249
250 #ifndef TABLES_NEXT_TO_CODE
251 StgLargeBitmap* large_bitmap; /* pointer to large bitmap structure */
252 #else
253 OFFSET_FIELD( large_bitmap_offset ); /* offset from info table to large bitmap structure */
254 #endif
255
256 StgWord selector_offset; /* used in THUNK_SELECTORs */
257
258 } StgClosureInfo;
259
260
261 /*
262 * The "standard" part of an info table. Every info table has this bit.
263 */
264 typedef struct _StgInfoTable {
265
266 #ifndef TABLES_NEXT_TO_CODE
267 StgFunPtr entry; /* pointer to the entry code */
268 #endif
269
270 #if defined(PAR) || defined(GRAN)
271 struct _StgInfoTable *rbh_infoptr;
272 #endif
273 #ifdef PROFILING
274 StgProfInfo prof;
275 #endif
276 #ifdef TICKY
277 /* Ticky-specific stuff would go here. */
278 #endif
279 #ifdef DEBUG_CLOSURE
280 /* Debug-specific stuff would go here. */
281 #endif
282
283 StgClosureInfo layout; /* closure layout info (one word) */
284
285 StgHalfWord type; /* closure type */
286 StgHalfWord srt_bitmap; /* number of entries in SRT (or constructor tag) */
287
288 #ifdef TABLES_NEXT_TO_CODE
289 StgCode code[FLEXIBLE_ARRAY];
290 #endif
291 } StgInfoTable;
292
293
294 /* -----------------------------------------------------------------------------
295 Function info tables
296
297 This is the general form of function info tables. The compiler
298 will omit some of the fields in common cases:
299
300 - If fun_type is not ARG_GEN or ARG_GEN_BIG, then the slow_apply
301 and bitmap fields may be left out (they are at the end, so omitting
302 them doesn't affect the layout).
303
304 - If srt_bitmap (in the std info table part) is zero, then the srt
305 field may be omitted. This only applies if the slow_apply and
306 bitmap fields have also been omitted.
307 -------------------------------------------------------------------------- */
308
309 typedef struct _StgFunInfoExtraRev {
310 OFFSET_FIELD ( slow_apply_offset ); /* apply to args on the stack */
311 union {
312 StgWord bitmap;
313 OFFSET_FIELD ( bitmap_offset ); /* arg ptr/nonptr bitmap */
314 } b;
315 OFFSET_FIELD ( srt_offset ); /* pointer to the SRT table */
316 StgHalfWord fun_type; /* function type */
317 StgHalfWord arity; /* function arity */
318 } StgFunInfoExtraRev;
319
320 typedef struct _StgFunInfoExtraFwd {
321 StgHalfWord fun_type; /* function type */
322 StgHalfWord arity; /* function arity */
323 StgSRT *srt; /* pointer to the SRT table */
324 union { /* union for compat. with TABLES_NEXT_TO_CODE version */
325 StgWord bitmap; /* arg ptr/nonptr bitmap */
326 } b;
327 StgFun *slow_apply; /* apply to args on the stack */
328 } StgFunInfoExtraFwd;
329
330 typedef struct {
331 #if defined(TABLES_NEXT_TO_CODE)
332 StgFunInfoExtraRev f;
333 StgInfoTable i;
334 #else
335 StgInfoTable i;
336 StgFunInfoExtraFwd f;
337 #endif
338 } StgFunInfoTable;
339
340 /* -----------------------------------------------------------------------------
341 Return info tables
342 -------------------------------------------------------------------------- */
343
344 /*
345 * When info tables are laid out backwards, we can omit the SRT
346 * pointer iff srt_bitmap is zero.
347 */
348
349 typedef struct {
350 #if defined(TABLES_NEXT_TO_CODE)
351 OFFSET_FIELD( srt_offset ); /* offset to the SRT table */
352 StgInfoTable i;
353 #else
354 StgInfoTable i;
355 StgSRT *srt; /* pointer to the SRT table */
356 StgFunPtr vector[FLEXIBLE_ARRAY];
357 #endif
358 } StgRetInfoTable;
359
360 /* -----------------------------------------------------------------------------
361 Thunk info tables
362 -------------------------------------------------------------------------- */
363
364 /*
365 * When info tables are laid out backwards, we can omit the SRT
366 * pointer iff srt_bitmap is zero.
367 */
368
369 typedef struct _StgThunkInfoTable {
370 #if !defined(TABLES_NEXT_TO_CODE)
371 StgInfoTable i;
372 #endif
373 #if defined(TABLES_NEXT_TO_CODE)
374 OFFSET_FIELD( srt_offset ); /* offset to the SRT table */
375 #else
376 StgSRT *srt; /* pointer to the SRT table */
377 #endif
378 #if defined(TABLES_NEXT_TO_CODE)
379 StgInfoTable i;
380 #endif
381 } StgThunkInfoTable;
382
383
384 /* -----------------------------------------------------------------------------
385 Accessor macros for fields that might be offsets (C version)
386 -------------------------------------------------------------------------- */
387
388 /*
389 * GET_SRT(info)
390 * info must be a Stg[Ret|Thunk]InfoTable* (an info table that has a SRT)
391 */
392 #ifdef TABLES_NEXT_TO_CODE
393 #define GET_SRT(info) ((StgSRT*) (((StgWord) ((info)+1)) + (info)->srt_offset))
394 #else
395 #define GET_SRT(info) ((info)->srt)
396 #endif
397
398 /*
399 * GET_FUN_SRT(info)
400 * info must be a StgFunInfoTable*
401 */
402 #ifdef TABLES_NEXT_TO_CODE
403 #define GET_FUN_SRT(info) ((StgSRT*) (((StgWord) ((info)+1)) + (info)->f.srt_offset))
404 #else
405 #define GET_FUN_SRT(info) ((info)->f.srt)
406 #endif
407
408 #ifdef TABLES_NEXT_TO_CODE
409 #define GET_LARGE_BITMAP(info) ((StgLargeBitmap*) (((StgWord) ((info)+1)) \
410 + (info)->layout.large_bitmap_offset))
411 #else
412 #define GET_LARGE_BITMAP(info) ((info)->layout.large_bitmap)
413 #endif
414
415 #ifdef TABLES_NEXT_TO_CODE
416 #define GET_FUN_LARGE_BITMAP(info) ((StgLargeBitmap*) (((StgWord) ((info)+1)) \
417 + (info)->f.b.bitmap_offset))
418 #else
419 #define GET_FUN_LARGE_BITMAP(info) ((StgLargeBitmap*) ((info)->f.b.bitmap))
420 #endif
421
422
423 #endif /* INFOTABLES_H */