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

Show
Ignore:
Timestamp:
08/25/09 02:26:02 (4 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.