|Version 5 (modified by simonmar, 6 years ago) (diff)|
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.
These are header files that define an external API to the RTS that can be used by client code. These interfaces are intended to be relatively stable:
- The external FFI api
- The top-level interface to the RTS (rts_evalIO(), etc.)
- External API to the RTS scheduler
- External API to the RTS runtime flags
- External API to the linker
Used when compiling via C
These header files are #included into the .hc file generated by GHC when it compiles Haskell code to C.
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.
- The top of the hierarchy is Stg.h, which includes everything required by .hc code. The following files are #included by Stg.h:
- Configuration info derived by the configure script.
- Settings for Rts configurables (eg. eager vs. lazy BH)
- Sizes of various basic types.
- Basic types specific to the virtual machine (eg. StgWord).
- Tail calls in .hc code.
- Stuff related to Windows DLLs.
- Global register assignments for this processor.
- "registers" in the virtual machine.
- Profiling gubbins.
- Declarations for closures & info tables built-in to the RTS
- Declarations for RTS things referred to by .hc code. (NOTE: also includes RtsAPI.h and HsFFI.h.
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.
- Types used in the RTS
- Build-time constants
- The layout of closures.
- macros for constructing RET_DYN liveness masks
- The layout of info tables.
- The structure of Thread State Objects.
- Macros for performing updates.
- Macros for multiprocessor support, eg. cas().
- The block allocator, block descriptors, Bdescr().
- Ticky-ticky profiling.
- Stable pointers, stable names.
- Hooks for changing RTS behaviour.
- The API for using Signals from Haskell.
- .NET stuff (bitrotted).
Included into C-- code
- included into .cmm source only
- generated by includes/mkDerivedConstants.c from other .h files, see Commentary/Compiler/CodeGen.
- also included into .cmm code.
Included into various non-C source code
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 following headers are in this category: