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