Changes between Version 5 and Version 6 of Commentary/SourceTree/Includes


Ignore:
Timestamp:
Aug 25, 2009 9:26:02 AM (6 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/SourceTree/Includes

    v5 v6  
    44= GHC Source Tree Roadmap: includes/ =
    55
    6 This directory contains C header files that are included in a GHC distribution.  We classify header files into 4 categories.
     6This directory contains C header files that are included in a GHC
     7distribution.  We classify header files into 4 categories.
    78
    89== External APIs ==
     
    1314
    1415 [http://darcs.haskell.org/ghc/includes/HsFFI.h HsFFI.h]::
    15   The external FFI api
     16  The external FFI api, as required by the FFI spec
     17
    1618 [http://darcs.haskell.org/ghc/includes/RtsAPI.h RtsAPI.h]::
    17   The top-level interface to the RTS ({{{rts_evalIO()}}}, etc.)
    18  [http://darcs.haskell.org/ghc/includes/SchedAPI.h SchedAPI.h]::
    19   External API to the RTS scheduler
    20  [http://darcs.haskell.org/ghc/includes/RtsFlags.h RtsFlags.h]::
    21   External API to the RTS runtime flags
    22  [http://darcs.haskell.org/ghc/includes/Linker.h Linker.h]::
    23   External API to the linker
     19  The API for calling into the RTS.  Used by the implementation
     20  of `foreign export` calls, but may also be used by external
     21  clients.
     22
     23 [http://darcs.haskell.org/ghc/includes/Rts.h Rts.h]::
     24  This header file defines everything that is visible
     25  externally to the RTS.  It includes `Stg.h` and everything
     26  in the `rts` subdirectory.
     27
     28== Derived Constants ==
     29
     30The canonical definition of certain structures are in C header files.
     31For example, the layout of closures and info tables are defined in the
     32headers [http://darcs.haskell.org/ghc/includes/rts/storage/Closures.h
     33Closures.h] and
     34[http://darcs.haskell.org/ghc/includes/rts/storage/InfoTables.h
     35InfoTables.h] respectivesly.  How do we get the information about the
     36layout of these structures to the parts of the system that are not
     37written in C, such as the compiler itself, or the C-- code in the RTS?
     38
     39Our solution is the C program
     40[http://darcs.haskell.org/ghc/includes/mkDerivedConstants.c mkDerivedConstants.c].
     41It `#includes` the C header files containing the structure
     42definitions, and emits a new C header file containing only `#define`s
     43that give the byte offsets of important fields in those structures.
     44The program generates the following files:
     45
     46 * `DerivedConstants.h`
     47 * `GHCConstants.h`
     48
     49Take a look at those files in a build tree to see exactly what is
     50generated.
    2451
    2552== Used when compiling via C ==
    2653
    27 These header files are {{{#included}}} into the {{{.hc}}} file
    28 generated by GHC when it compiles Haskell code to C. 
     54These header files are `#included` into the `.hc` file
     55generated by GHC when it compiles Haskell code to C.  They are also
     56`#included` by `Rts.h`, so the definitions from these files are shared
     57by the RTS code.
    2958
    30 These days the amount of stuff included this way is kept to a minimum,
    31 because we don't want to pollute the C namespace with too much
    32 extraneous goop.
     59These days the amount of stuff included this way is kept to a minimum.
     60In particular, there are no function prototypes: all calls to C
     61functions from `.hc` files are given types at the call site.
    3362
    3463 [http://darcs.haskell.org/ghc/includes/Stg.h Stg.h]::
    35   The top of the hierarchy is {{{Stg.h}}}, which includes everything required by
    36   {{{.hc}}} code.  The following files are {{{#included}}} by {{{Stg.h}}}:
     64  The top of the hierarchy is `Stg.h`, which includes everything
     65  required by `.hc` code.  Most files `#included` by `Stg.h` are in the
     66  `stg` subdirectory.
    3767
    3868 [http://darcs.haskell.org/ghc/includes/ghcconfig.h ghcconfig.h]::
    39   Configuration info derived by the {{{configure}}} script.
    40  [http://darcs.haskell.org/ghc/includes/RtsConfig.h RtsConfig.h]::
    41   Settings for Rts configurables (eg. eager vs. lazy BH)
     69  Configuration info derived by the `configure` script.
    4270 [http://darcs.haskell.org/ghc/includes/MachDeps.h MachDeps.h]::
    43   Sizes of various basic types.
    44  [http://darcs.haskell.org/ghc/includes/StgTypes.h StgTypes.h]::
    45   Basic types specific to the virtual machine (eg. {{{StgWord}}}).
    46  [http://darcs.haskell.org/ghc/includes/TailCalls.h TailCalls.h]::
    47   Tail calls in {{{.hc}}} code.
    48  [http://darcs.haskell.org/ghc/includes/StgDLL.h StgDLL.h]::
     71  Sizes of various basic types (should be in the `stg` subdirectory,
     72  but left here for backwards-compatibility reasons).
     73 [http://darcs.haskell.org/ghc/includes/stg/DLL.h stg/DLL.h]::
    4974  Stuff related to Windows DLLs.
    50  [http://darcs.haskell.org/ghc/includes/MachRegs.h MachRegs.h]::
     75 [http://darcs.haskell.org/ghc/includes/stg/MachRegs.h stg/MachRegs.h]::
    5176  Global register assignments for this processor.
    52  [http://darcs.haskell.org/ghc/includes/Regs.h Regs.h]::
     77 [http://darcs.haskell.org/ghc/includes/stg/MiscClosures.h stg/MiscClosures.h]::
     78  Declarations for closures & info tables built-in to the RTS
     79 [http://darcs.haskell.org/ghc/includes/stg/Regs.h stg/Regs.h]::
    5380  "registers" in the virtual machine.
    54  [http://darcs.haskell.org/ghc/includes/StgProf.h StgProf.h]::
    55   Profiling gubbins.
    56  [http://darcs.haskell.org/ghc/includes/StgMiscClosures.h StgMiscClosures.h]::
    57   Declarations for closures & info tables built-in to the RTS
    58  [http://darcs.haskell.org/ghc/includes/RtsExternal.h RtsExternal.h]::
    59   Declarations for RTS things referred to by {{{.hc}}} code.  (NOTE:
    60   also includes {{{RtsAPI.h}}} and {{{HsFFI.h}}}.
     81 [http://darcs.haskell.org/ghc/includes/stg/SMP.h stg/SMP.h]::
     82  Atomic memory operations for SMP support
     83 [http://darcs.haskell.org/ghc/includes/stg/TailCalls.h stg/TailCalls.h]::
     84  Tail calls in `.hc` code.
     85 [http://darcs.haskell.org/ghc/includes/stg/Ticky.h stg/Ticky.h]::
     86  Declarations for ticky-ticky counters
     87 [http://darcs.haskell.org/ghc/includes/stg/Types.h stg/Types.h]::
     88  Basic types specific to the virtual machine (eg. `StgWord`).
    6189
    62 == Included into the RTS source code itself ==
     90== The RTS external APIs ==
    6391
    64 Some of the header files here define important aspects of the
    65 implementation of the runtime, such as {{{Closures.h}}} which defines
    66 structures representing the layout of closures.
     92The header [http://darcs.haskell.org/ghc/includes/Rts.h Rts.h]
     93includes all the headers below the `rts` subdirectory, which together
     94define the RTS external API.  Virtually all RTS code `#includes`
     95`Rts.h`.
    6796
    68 All such header files lie below {{{Rts.h}}} in the inclusion
    69 hierarchy, in general all RTS sources {{{#include}}} {{{Rts.h}}}.
    70 Pretty much all the header files in this directory fall into this
    71 category.
     97The rts header files are divided into a few directories:
    7298
    73  [http://darcs.haskell.org/ghc/includes/Rts.h Rts.h]::
    74  [http://darcs.haskell.org/ghc/includes/RtsTypes.h RtsTypes.h]::
    75   Types used in the RTS
    76  [http://darcs.haskell.org/ghc/includes/Constants.h Constants.h]::
    77   Build-time constants
    78  [http://darcs.haskell.org/ghc/includes/StgLdvProf.h StgLdvProf.h]::
    79  [http://darcs.haskell.org/ghc/includes/StgFun.h StgFun.h]::
    80  [http://darcs.haskell.org/ghc/includes/Closures.h Closures.h]::
    81   The layout of closures.
    82  [http://darcs.haskell.org/ghc/includes/Liveness.h Liveness.h]::
    83   macros for constructing RET_DYN liveness masks
    84  [http://darcs.haskell.org/ghc/includes/ClosureMacros.h ClosureMacros.h]::
    85  [http://darcs.haskell.org/ghc/includes/ClosureTypes.h ClosureTypes.h]::
    86  [http://darcs.haskell.org/ghc/includes/InfoTables.h InfoTables.h]::
    87   The layout of info tables.
    88  [http://darcs.haskell.org/ghc/includes/TSO.h TSO.h]::
    89   The structure of Thread State Objects.
    90  [http://darcs.haskell.org/ghc/includes/Updates.h Updates.h]::
    91   Macros for performing updates.
    92  [http://darcs.haskell.org/ghc/includes/GranSim.h GranSim.h]::
    93  [http://darcs.haskell.org/ghc/includes/Parallel.h Parallel.h]::
    94  [http://darcs.haskell.org/ghc/includes/SMP.h SMP.h]::
    95   Macros for multiprocessor support, eg. {{{cas()}}}.
    96  [http://darcs.haskell.org/ghc/includes/Block.h Block.h]::
    97   The block allocator, block descriptors, {{{Bdescr()}}}.
    98  [http://darcs.haskell.org/ghc/includes/StgTicky.h StgTicky.h]::
    99   Ticky-ticky profiling.
    100  [http://darcs.haskell.org/ghc/includes/Stable.h Stable.h]::
    101   Stable pointers, stable names.
    102  [http://darcs.haskell.org/ghc/includes/Hooks.h Hooks.h]::
    103   Hooks for changing RTS behaviour.
    104  [http://darcs.haskell.org/ghc/includes/Signals.h Signals.h]::
    105   The API for using Signals from Haskell.
    106  [http://darcs.haskell.org/ghc/includes/DNInvoke.h DNInvoke.h]::
    107   .NET stuff (bitrotted).
     99 * [http://darcs.haskell.org/ghc/includes/rts includes/rts]: Most of
     100   the external RTS APIs, in separate header files per-subsystem
    108101
    109 == Included into C-- code ==
     102 * [http://darcs.haskell.org/ghc/includes/rts/storage includes/rts/storage]: Definitions of the layout of heap and stack
     103   objects, info tables, structures that define memory areas managed
     104   by the GC, and memory management APIs.
     105
     106 * [http://darcs.haskell.org/ghc/includes/rts/prof includes/rts/prof]:
     107   Interfaces and definitions for profiling.
     108
     109== Included into C-- (`.cmm`) code ==
    110110
    111111 [http://darcs.haskell.org/ghc/includes/Cmm.h Cmm.h]::
    112   included into .cmm source only
    113  !DerivedConstants.h::
    114   generated by [[GhcFile(includes/mkDerivedConstants.c)]] from other .h files, see
    115   [wiki:Commentary/Compiler/CodeGen#Storagemanagerrepresentations].
    116  [http://darcs.haskell.org/ghc/includes/Block.h Block.h]::
    117   also included into `.cmm` code.
    118 
    119 == Included into various non-C source code ==
    120 
    121 Some of these header files are {{{#included}}} into Haskell code or
    122 C-- ({{{.cmm}}}) code, so that we can have one place for defining constants and
    123 configuration settings.  Files in this category therefore must contain
    124 {{{#defines}}} only, no C code or declarations.
    125 
    126 The following headers are in this category:
    127 
    128  [http://darcs.haskell.org/ghc/includes/config.h config.h]::
    129  [http://darcs.haskell.org/ghc/includes/RtsConfig.h RtsConfig.h]::
    130  [http://darcs.haskell.org/ghc/includes/Constants.h Constants.h]::
    131  !DerivedConstants.h::
    132  [http://darcs.haskell.org/ghc/includes/ClosureTypes.h ClosureTypes.h]::
    133  [http://darcs.haskell.org/ghc/includes/StgFun.h StgFun.h]::
    134  [http://darcs.haskell.org/ghc/includes/MachRegs.h MachRegs.h]::
    135  [http://darcs.haskell.org/ghc/includes/Liveness.h Liveness.h]::
    136  [http://darcs.haskell.org/ghc/includes/StgLdvProf.h StgLdvProf.h]::
    137 
    138 
    139 == Miscellaneous ==
    140 
    141  [http://darcs.haskell.org/ghc/includes/Bytecodes.h Bytecodes.h]::
    142   Bytecode definitions for the interpreter
    143  [http://darcs.haskell.org/ghc/includes/ieee-flpt.h ieee-flpt.h]::
    144   !ToDo: needed?
     112  included into `.cmm` source only; provides useful macros for writing
     113  low-level C-- code for GHC.