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