ghc/includes/InfoTables.h

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