|Version 8 (modified by 8 years ago) (diff),|
GHC Source Tree Roadmap: includes/
This directory contains C header files that are included in a GHC distribution. The headers fall into several 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, as required by the FFI spec
The API for calling into the RTS. Used by the implementation
foreign exportcalls, but may also be used by external clients.
This header file defines everything that is visible
externally to the RTS. It includes
Stg.hand everything in the
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 and 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
#includes the C header files containing the structure
definitions, and emits a new C header file containing only
that give the byte offsets of important fields in those structures.
The program generates the following files:
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
generated by GHC when it compiles Haskell code to C. They are also
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.
In particular, there are no function prototypes: all calls to C
.hc files are given types at the call site.
The top of the hierarchy is
Stg.h, which includes everything required by
.hccode. Most files
Stg.hare in the
Configuration info derived by the
Sizes of various basic types (should be in the
stgsubdirectory, but left here for backwards-compatibility reasons).
- Stuff related to Windows DLLs.
- Global register assignments for this processor.
- Declarations for closures & info tables built-in to the RTS
- "registers" in the virtual machine.
- Atomic memory operations for SMP support
Tail calls in
- Declarations for ticky-ticky counters
Basic types specific to the virtual machine (eg.
The RTS external APIs
The header Rts.h
includes all the headers below the
rts subdirectory, which together
define the RTS external API. Virtually all RTS code
The rts header files are divided into a few directories:
- includes/rts: Most of the external RTS APIs, in separate header files per-subsystem
- 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.
- includes/rts/prof: Interfaces and definitions for profiling.
Included into C-- (
.cmmsource only; provides useful macros for writing low-level C-- code for GHC.