wiki:Commentary/SourceTree/Includes

Version 5 (modified by simonmar, 5 years ago) (diff)

fix links

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.

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
RtsAPI.h
The top-level interface to the RTS (rts_evalIO(), etc.)
SchedAPI.h
External API to the RTS scheduler
RtsFlags.h
External API to the RTS runtime flags
Linker.h
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.

Stg.h
The top of the hierarchy is Stg.h, which includes everything required by .hc code. The following files are #included by Stg.h:
ghcconfig.h
Configuration info derived by the configure script.
RtsConfig.h
Settings for Rts configurables (eg. eager vs. lazy BH)
MachDeps.h
Sizes of various basic types.
StgTypes.h
Basic types specific to the virtual machine (eg. StgWord).
TailCalls.h
Tail calls in .hc code.
StgDLL.h
Stuff related to Windows DLLs.
MachRegs.h
Global register assignments for this processor.
Regs.h
"registers" in the virtual machine.
StgProf.h
Profiling gubbins.
StgMiscClosures.h
Declarations for closures & info tables built-in to the RTS
RtsExternal.h
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.

Rts.h
RtsTypes.h
Types used in the RTS
Constants.h
Build-time constants
StgLdvProf.h
StgFun.h
Closures.h
The layout of closures.
Liveness.h
macros for constructing RET_DYN liveness masks
ClosureMacros.h
ClosureTypes.h
InfoTables.h
The layout of info tables.
TSO.h
The structure of Thread State Objects.
Updates.h
Macros for performing updates.
GranSim.h
Parallel.h
SMP.h
Macros for multiprocessor support, eg. cas().
Block.h
The block allocator, block descriptors, Bdescr().
StgTicky.h
Ticky-ticky profiling.
Stable.h
Stable pointers, stable names.
Hooks.h
Hooks for changing RTS behaviour.
Signals.h
The API for using Signals from Haskell.
DNInvoke.h
.NET stuff (bitrotted).

Included into C-- code

Cmm.h
included into .cmm source only
DerivedConstants.h
generated by includes/mkDerivedConstants.c from other .h files, see Commentary/Compiler/CodeGen.
Block.h
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:

config.h
RtsConfig.h
Constants.h
DerivedConstants.h
ClosureTypes.h
StgFun.h
MachRegs.h
Liveness.h
StgLdvProf.h

Miscellaneous

Bytecodes.h
Bytecode definitions for the interpreter
ieee-flpt.h
ToDo: needed?