ghc/includes/InfoTables.h

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