|
|
# GHC Source Tree Roadmap: includes/
|
|
|
|
|
|
|
|
|
This directory contains C header files that are included in a GHC distribution. We classify header files into 4 categories.
|
|
|
This directory contains C header files that are included in a GHC
|
|
|
distribution. The headers fall into several categories.
|
|
|
|
|
|
## External APIs
|
|
|
|
... | ... | @@ -12,225 +13,135 @@ relatively stable: |
|
|
|
|
|
<table><tr><th>[ HsFFI.h](http://darcs.haskell.org/ghc/includes/HsFFI.h)</th>
|
|
|
<td>
|
|
|
The external FFI api
|
|
|
</td></tr>
|
|
|
<tr><th>[ RtsAPI.h](http://darcs.haskell.org/ghc/includes/RtsAPI.h)</th>
|
|
|
<td>
|
|
|
The top-level interface to the RTS (`rts_evalIO()`, etc.)
|
|
|
</td></tr>
|
|
|
<tr><th>[ SchedAPI.h](http://darcs.haskell.org/ghc/includes/SchedAPI.h)</th>
|
|
|
<td>
|
|
|
External API to the RTS scheduler
|
|
|
</td></tr>
|
|
|
<tr><th>[ RtsFlags.h](http://darcs.haskell.org/ghc/includes/RtsFlags.h)</th>
|
|
|
The external FFI api, as required by the FFI spec
|
|
|
</td></tr></table>
|
|
|
|
|
|
<table><tr><th>[ RtsAPI.h](http://darcs.haskell.org/ghc/includes/RtsAPI.h)</th>
|
|
|
<td>
|
|
|
External API to the RTS runtime flags
|
|
|
</td></tr>
|
|
|
<tr><th>[ Linker.h](http://darcs.haskell.org/ghc/includes/Linker.h)</th>
|
|
|
The API for calling into the RTS. Used by the implementation
|
|
|
of `foreign export` calls, but may also be used by external
|
|
|
clients.
|
|
|
</td></tr></table>
|
|
|
|
|
|
<table><tr><th>[ Rts.h](http://darcs.haskell.org/ghc/includes/Rts.h)</th>
|
|
|
<td>
|
|
|
External API to the linker
|
|
|
This header file defines everything that is visible
|
|
|
externally to the RTS. It includes `Stg.h` and everything
|
|
|
in the `rts` subdirectory.
|
|
|
</td></tr></table>
|
|
|
|
|
|
## Derived Constants
|
|
|
|
|
|
|
|
|
The canonical definition of certain structures are in C header files.
|
|
|
For example, the layout of closures and info tables are defined in the
|
|
|
headers [ Closures.h](http://darcs.haskell.org/ghc/includes/rts/storage/Closures.h) and
|
|
|
[ InfoTables.h](http://darcs.haskell.org/ghc/includes/rts/storage/InfoTables.h) respectivesly. How do we get the information about the
|
|
|
layout of these structures to the parts of the system that are not
|
|
|
written in C, such as the compiler itself, or the C-- code in the RTS?
|
|
|
|
|
|
|
|
|
Our solution is the C program
|
|
|
[ mkDerivedConstants.c](http://darcs.haskell.org/ghc/includes/mkDerivedConstants.c).
|
|
|
It `#includes` the C header files containing the structure
|
|
|
definitions, and emits a new C header file containing only `#define`s
|
|
|
that give the byte offsets of important fields in those structures.
|
|
|
The program generates the following files:
|
|
|
|
|
|
- `DerivedConstants.h`
|
|
|
- `GHCConstants.h`
|
|
|
|
|
|
|
|
|
Take a look at those files in a build tree to see exactly what is
|
|
|
generated. These new headers can then be `#included` into Haskell
|
|
|
code or C-- code.
|
|
|
|
|
|
## Used when compiling via C
|
|
|
|
|
|
|
|
|
These header files are `#included` into the `.hc` file
|
|
|
generated by GHC when it compiles Haskell code to C.
|
|
|
generated by GHC when it compiles Haskell code to C. They are also
|
|
|
`#included` by `Rts.h`, so the definitions from these files are shared
|
|
|
by the RTS code.
|
|
|
|
|
|
|
|
|
These days the amount of stuff included this way is kept to a minimum,
|
|
|
because we don't want to pollute the C namespace with too much
|
|
|
extraneous goop.
|
|
|
These days the amount of stuff included this way is kept to a minimum.
|
|
|
In particular, there are no function prototypes: all calls to C
|
|
|
functions from `.hc` files are given types at the call site.
|
|
|
|
|
|
<table><tr><th>[ Stg.h](http://darcs.haskell.org/ghc/includes/Stg.h)</th>
|
|
|
<td>
|
|
|
The top of the hierarchy is `Stg.h`, which includes everything required by
|
|
|
`.hc` code. The following files are `#included` by `Stg.h`:
|
|
|
The top of the hierarchy is `Stg.h`, which includes everything
|
|
|
required by `.hc` code. Most files `#included` by `Stg.h` are in the
|
|
|
`stg` subdirectory.
|
|
|
</td></tr></table>
|
|
|
|
|
|
<table><tr><th>[ ghcconfig.h](http://darcs.haskell.org/ghc/includes/ghcconfig.h)</th>
|
|
|
<td>
|
|
|
Configuration info derived by the `configure` script.
|
|
|
</td></tr>
|
|
|
<tr><th>[ RtsConfig.h](http://darcs.haskell.org/ghc/includes/RtsConfig.h)</th>
|
|
|
<td>
|
|
|
Settings for Rts configurables (eg. eager vs. lazy BH)
|
|
|
</td></tr>
|
|
|
<tr><th>[ MachDeps.h](http://darcs.haskell.org/ghc/includes/MachDeps.h)</th>
|
|
|
<td>
|
|
|
Sizes of various basic types.
|
|
|
</td></tr>
|
|
|
<tr><th>[ StgTypes.h](http://darcs.haskell.org/ghc/includes/StgTypes.h)</th>
|
|
|
<td>
|
|
|
Basic types specific to the virtual machine (eg. `StgWord`).
|
|
|
</td></tr>
|
|
|
<tr><th>[ TailCalls.h](http://darcs.haskell.org/ghc/includes/TailCalls.h)</th>
|
|
|
<td>
|
|
|
Tail calls in `.hc` code.
|
|
|
Sizes of various basic types (should be in the `stg` subdirectory,
|
|
|
but left here for backwards-compatibility reasons).
|
|
|
</td></tr>
|
|
|
<tr><th>[ StgDLL.h](http://darcs.haskell.org/ghc/includes/StgDLL.h)</th>
|
|
|
<tr><th>[ stg/DLL.h](http://darcs.haskell.org/ghc/includes/stg/DLL.h)</th>
|
|
|
<td>
|
|
|
Stuff related to Windows DLLs.
|
|
|
</td></tr>
|
|
|
<tr><th>[ MachRegs.h](http://darcs.haskell.org/ghc/includes/MachRegs.h)</th>
|
|
|
<tr><th>[ stg/MachRegs.h](http://darcs.haskell.org/ghc/includes/stg/MachRegs.h)</th>
|
|
|
<td>
|
|
|
Global register assignments for this processor.
|
|
|
</td></tr>
|
|
|
<tr><th>[ Regs.h](http://darcs.haskell.org/ghc/includes/Regs.h)</th>
|
|
|
<td>
|
|
|
"registers" in the virtual machine.
|
|
|
</td></tr>
|
|
|
<tr><th>[ StgProf.h](http://darcs.haskell.org/ghc/includes/StgProf.h)</th>
|
|
|
<td>
|
|
|
Profiling gubbins.
|
|
|
</td></tr>
|
|
|
<tr><th>[ StgMiscClosures.h](http://darcs.haskell.org/ghc/includes/StgMiscClosures.h)</th>
|
|
|
<tr><th>[ stg/MiscClosures.h](http://darcs.haskell.org/ghc/includes/stg/MiscClosures.h)</th>
|
|
|
<td>
|
|
|
Declarations for closures & info tables built-in to the RTS
|
|
|
</td></tr>
|
|
|
<tr><th>[ RtsExternal.h](http://darcs.haskell.org/ghc/includes/RtsExternal.h)</th>
|
|
|
<td>
|
|
|
Declarations for RTS things referred to by `.hc` code. (NOTE:
|
|
|
also includes `RtsAPI.h` and `HsFFI.h`.
|
|
|
</td></tr></table>
|
|
|
|
|
|
## Included into the RTS source code itself
|
|
|
|
|
|
|
|
|
Some of the header files here define important aspects of the
|
|
|
implementation of the runtime, such as `Closures.h` which defines
|
|
|
structures representing the layout of closures.
|
|
|
|
|
|
|
|
|
All such header files lie below `Rts.h` in the inclusion
|
|
|
hierarchy, in general all RTS sources `#include``Rts.h`.
|
|
|
Pretty much all the header files in this directory fall into this
|
|
|
category.
|
|
|
|
|
|
<table><tr><th>[ Rts.h](http://darcs.haskell.org/ghc/includes/Rts.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ RtsTypes.h](http://darcs.haskell.org/ghc/includes/RtsTypes.h)</th>
|
|
|
<td>
|
|
|
Types used in the RTS
|
|
|
</td></tr>
|
|
|
<tr><th>[ Constants.h](http://darcs.haskell.org/ghc/includes/Constants.h)</th>
|
|
|
<td>
|
|
|
Build-time constants
|
|
|
</td></tr>
|
|
|
<tr><th>[ StgLdvProf.h](http://darcs.haskell.org/ghc/includes/StgLdvProf.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ StgFun.h](http://darcs.haskell.org/ghc/includes/StgFun.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ Closures.h](http://darcs.haskell.org/ghc/includes/Closures.h)</th>
|
|
|
<td>
|
|
|
The layout of closures.
|
|
|
</td></tr>
|
|
|
<tr><th>[ Liveness.h](http://darcs.haskell.org/ghc/includes/Liveness.h)</th>
|
|
|
<td>
|
|
|
macros for constructing RET_DYN liveness masks
|
|
|
</td></tr>
|
|
|
<tr><th>[ ClosureMacros.h](http://darcs.haskell.org/ghc/includes/ClosureMacros.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ ClosureTypes.h](http://darcs.haskell.org/ghc/includes/ClosureTypes.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ InfoTables.h](http://darcs.haskell.org/ghc/includes/InfoTables.h)</th>
|
|
|
<td>
|
|
|
The layout of info tables.
|
|
|
</td></tr>
|
|
|
<tr><th>[ TSO.h](http://darcs.haskell.org/ghc/includes/TSO.h)</th>
|
|
|
<td>
|
|
|
The structure of Thread State Objects.
|
|
|
</td></tr>
|
|
|
<tr><th>[ Updates.h](http://darcs.haskell.org/ghc/includes/Updates.h)</th>
|
|
|
<td>
|
|
|
Macros for performing updates.
|
|
|
</td></tr>
|
|
|
<tr><th>[ GranSim.h](http://darcs.haskell.org/ghc/includes/GranSim.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ Parallel.h](http://darcs.haskell.org/ghc/includes/Parallel.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ SMP.h](http://darcs.haskell.org/ghc/includes/SMP.h)</th>
|
|
|
<td>
|
|
|
Macros for multiprocessor support, eg. `cas()`.
|
|
|
</td></tr>
|
|
|
<tr><th>[ Block.h](http://darcs.haskell.org/ghc/includes/Block.h)</th>
|
|
|
<td>
|
|
|
The block allocator, block descriptors, `Bdescr()`.
|
|
|
</td></tr>
|
|
|
<tr><th>[ StgTicky.h](http://darcs.haskell.org/ghc/includes/StgTicky.h)</th>
|
|
|
<tr><th>[ stg/Regs.h](http://darcs.haskell.org/ghc/includes/stg/Regs.h)</th>
|
|
|
<td>
|
|
|
Ticky-ticky profiling.
|
|
|
"registers" in the virtual machine.
|
|
|
</td></tr>
|
|
|
<tr><th>[ Stable.h](http://darcs.haskell.org/ghc/includes/Stable.h)</th>
|
|
|
<tr><th>[ stg/SMP.h](http://darcs.haskell.org/ghc/includes/stg/SMP.h)</th>
|
|
|
<td>
|
|
|
Stable pointers, stable names.
|
|
|
Atomic memory operations for SMP support
|
|
|
</td></tr>
|
|
|
<tr><th>[ Hooks.h](http://darcs.haskell.org/ghc/includes/Hooks.h)</th>
|
|
|
<tr><th>[ stg/TailCalls.h](http://darcs.haskell.org/ghc/includes/stg/TailCalls.h)</th>
|
|
|
<td>
|
|
|
Hooks for changing RTS behaviour.
|
|
|
Tail calls in `.hc` code.
|
|
|
</td></tr>
|
|
|
<tr><th>[ Signals.h](http://darcs.haskell.org/ghc/includes/Signals.h)</th>
|
|
|
<tr><th>[ stg/Ticky.h](http://darcs.haskell.org/ghc/includes/stg/Ticky.h)</th>
|
|
|
<td>
|
|
|
The API for using Signals from Haskell.
|
|
|
Declarations for ticky-ticky counters
|
|
|
</td></tr>
|
|
|
<tr><th>[ DNInvoke.h](http://darcs.haskell.org/ghc/includes/DNInvoke.h)</th>
|
|
|
<tr><th>[ stg/Types.h](http://darcs.haskell.org/ghc/includes/stg/Types.h)</th>
|
|
|
<td>
|
|
|
.NET stuff (bitrotted).
|
|
|
Basic types specific to the virtual machine (eg. `StgWord`).
|
|
|
</td></tr></table>
|
|
|
|
|
|
## Included into C-- code
|
|
|
## The RTS external APIs
|
|
|
|
|
|
<table><tr><th>[ Cmm.h](http://darcs.haskell.org/ghc/includes/Cmm.h)</th>
|
|
|
<td>
|
|
|
included into .cmm source only
|
|
|
</td></tr>
|
|
|
<tr><th>DerivedConstants.h</th>
|
|
|
<td>
|
|
|
generated by [includes/mkDerivedConstants.c](/trac/ghc/browser/ghc/includes/mkDerivedConstants.c) from other .h files, see
|
|
|
[Commentary/Compiler/CodeGen](commentary/compiler/code-gen#storage-manager-representations).
|
|
|
</td></tr>
|
|
|
<tr><th>[ Block.h](http://darcs.haskell.org/ghc/includes/Block.h)</th>
|
|
|
<td>
|
|
|
also included into `.cmm` code.
|
|
|
</td></tr></table>
|
|
|
|
|
|
## Included into various non-C source code
|
|
|
The header [ Rts.h](http://darcs.haskell.org/ghc/includes/Rts.h)
|
|
|
includes all the headers below the `rts` subdirectory, which together
|
|
|
define the RTS external API. Virtually all RTS code `#includes``Rts.h`.
|
|
|
|
|
|
|
|
|
Some of these header files are `#included` into Haskell code or
|
|
|
C-- (`.cmm`) code, so that we can have one place for defining constants and
|
|
|
configuration settings. Files in this category therefore must contain
|
|
|
`#defines` only, no C code or declarations.
|
|
|
The rts header files are divided into a few directories:
|
|
|
|
|
|
- [ includes/rts](http://darcs.haskell.org/ghc/includes/rts): Most of
|
|
|
the external RTS APIs, in separate header files per-subsystem
|
|
|
|
|
|
The following headers are in this category:
|
|
|
- [ includes/rts/storage](http://darcs.haskell.org/ghc/includes/rts/storage): Definitions of the layout of heap and stack
|
|
|
objects, info tables, structures that define memory areas managed
|
|
|
by the GC, and memory management APIs.
|
|
|
|
|
|
<table><tr><th>[ config.h](http://darcs.haskell.org/ghc/includes/config.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ RtsConfig.h](http://darcs.haskell.org/ghc/includes/RtsConfig.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ Constants.h](http://darcs.haskell.org/ghc/includes/Constants.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>DerivedConstants.h</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ ClosureTypes.h](http://darcs.haskell.org/ghc/includes/ClosureTypes.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ StgFun.h](http://darcs.haskell.org/ghc/includes/StgFun.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ MachRegs.h](http://darcs.haskell.org/ghc/includes/MachRegs.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ Liveness.h](http://darcs.haskell.org/ghc/includes/Liveness.h)</th>
|
|
|
<td></td></tr>
|
|
|
<tr><th>[ StgLdvProf.h](http://darcs.haskell.org/ghc/includes/StgLdvProf.h)</th>
|
|
|
<td></td></tr></table>
|
|
|
- [ includes/rts/prof](http://darcs.haskell.org/ghc/includes/rts/prof):
|
|
|
Interfaces and definitions for profiling.
|
|
|
|
|
|
## Miscellaneous
|
|
|
## Included into C-- (`.cmm`) code
|
|
|
|
|
|
<table><tr><th>[ Bytecodes.h](http://darcs.haskell.org/ghc/includes/Bytecodes.h)</th>
|
|
|
<td>
|
|
|
Bytecode definitions for the interpreter
|
|
|
</td></tr>
|
|
|
<tr><th>[ ieee-flpt.h](http://darcs.haskell.org/ghc/includes/ieee-flpt.h)</th>
|
|
|
<table><tr><th>[ Cmm.h](http://darcs.haskell.org/ghc/includes/Cmm.h)</th>
|
|
|
<td>
|
|
|
ToDo: needed?
|
|
|
included into `.cmm` source only; provides useful macros for writing
|
|
|
low-level C-- code for GHC.
|
|
|
</td></tr></table> |
|
|
\ No newline at end of file |