wiki:Commentary/SourceTree/Includes

Version 10 (modified by simonmar, 16 months 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.

External APIs

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:

HsFFI.h
The external FFI api, as required by the FFI spec
RtsAPI.h
The API for calling into the RTS. Used by the implementation of foreign export calls, but may also be used by external clients.
Rts.h
This header file defines everything that is visible externally to the RTS. It includes Stg.h and everything in the rts subdirectory.

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 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 Haskell program in utils/deriveConstants/DeriveConstants.hs. It determines the sizes and fields offsets from the C header files by invoking the C compiler for the target platform, and then looking at the resulting object file (we can't run the code generated by the target C compiler, because this is the host platform).

The DeriveConstants program generates a few header files, notably includes/dist-derivedconstants/header/DerivedConstants.h, which contains C #defines for each of the derived constants; this file is used by C-- code in the RTS. It also generates a few files of Haskell code which are included into GHC itself, in the DynFlags module.

Used when compiling via C

These header files are #included into the .hc file 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. In particular, there are no function prototypes: all calls to C functions from .hc files are given types at the call site.

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.
ghcconfig.h
Configuration info derived by the configure script.
MachDeps.h
Sizes of various basic types (should be in the stg subdirectory, but left here for backwards-compatibility reasons).
stg/DLL.h
Stuff related to Windows DLLs.
stg/MachRegs.h
Global register assignments for this processor.
stg/MiscClosures.h
Declarations for closures & info tables built-in to the RTS
stg/Regs.h
"registers" in the virtual machine.
stg/SMP.h
Atomic memory operations for SMP support
stg/Ticky.h
Declarations for ticky-ticky counters
stg/Types.h
Basic types specific to the virtual machine (eg. StgWord).

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 #includes Rts.h.

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.

Included into C-- (.cmm) code

Cmm.h
included into .cmm source only; provides useful macros for writing low-level C-- code for GHC.