[project @ 2004-08-13 13:04:50 by simonmar]

[ghc-hetmet.git] / ghc / includes / README

diff --git a/ghc/includes/README b/ghc/includes/README
new file mode 100644 (file)
index 0000000..ec10ca1
--- /dev/null
+++ b/ghc/includes/README
@@ -0,0 +1,114 @@
+-----------------------------------------------------------------------------
+The External API to the GHC Runtime System.
+-----------------------------------------------------------------------------
+
+The header files in this directory form the external API for the
+runtime.  The header files are used in the following scenarios:
+
+  1. Included into the RTS source code itself.
+       In this case we include "Rts.h", which includes everything
+       else in the appropriate order.
+
+       Pretty much everything falls into this category.
+
+  2. Included into a .hc file generated by the compiler.
+       In this case we include Stg.h, which includes a
+       subset of the headers, in the appropriate order and
+       with the appropriate settings (e.g. global register variables
+       turned on).
+
+       Includes everything below Stg.h in the hierarchy (see below).
+
+  3. Included into external C source code.
+       The following headers are designed to be included into
+        external C  code (i.e. C code compiled using a GHC installation,
+        not part of GHC itself or the RTS):
+
+               HsFFI.h
+               RtsAPI.h
+               SchedAPI.h
+               RtsFlags.h
+               Linker.h
+
+       These interfaces are intended to be relatively stable.
+
+       Also Rts.h can be included to get hold of everything else, including
+       definitions of heap objects, info tables, the storage manager interface
+       and so on.  But be warned: none of this is guaranteed to remain stable
+       from one GHC release to the next.
+
+  4. Included into non-C source code, including Haskell (GHC itself)
+     and C-- code in the RTS.
+
+       The following headers are #included into non-C source, so
+       cannot contain any C code or declarations:
+               config.h
+               RtsConfig.h
+               Constants.h
+               DerivedConstants.h
+               ClosureTypes.h
+               StgFun.h
+               MachRegs.h
+               Liveness.h
+               StgLdvProf.h
+
+Here is a rough hierarchy of the header files by dependency.
+
+Rts.h
+  Stg.h
+    config.h           // configuration info derived by the configure script.
+    RtsConfig.h                // settings for Rts things (eg. eager vs. lazy BH)
+    MachDeps.h         // sizes of various basic types
+    StgTypes.h         // basic types specific to the virtual machine
+    TailCalls.h                // tail calls in .hc code
+    StgDLL.h           // stuff related to Windows DLLs
+    MachRegs.h         // global register assignments for this arch
+    Regs.h             // "registers" in the virtual machine
+    StgProf.h          // profiling gubbins
+    StgMiscClosures.h  // decls for closures & info tables in the RTS
+    RtsExternal.h      // decls for RTS things required by .hc code
+      (RtsAPI.h)
+      (HsFFI.h)
+
+  RtsTypes.h           // types used in the RTS
+
+  Constants.h          // build-time constants
+  StgLdvProf.h
+  StgFun.h
+  Closures.h
+  Liveness.h           // macros for constructing RET_DYN liveness masks
+  ClosureMacros.h
+  ClosureTypes.h
+  InfoTables.h
+  TSO.h
+  Updates.h            // macros for performing updates
+  GranSim.h
+  Parallel.h
+  SMP.h
+  Block.h
+  StgTicky.h
+  Stable.h
+  Hooks.h
+  Signals.h
+  DNInvoke.h
+    Dotnet.h
+
+Cmm.h                  // included into .cmm source only
+  DerivedConstants.h   // generated by mkDerivedConstants.c from other
+                       // .h files.
+  (Constants.h)
+  (ClosureTypes.h)
+  (StgFun.h)
+  (MachRegs.h)
+  (Liveness.h)  
+  (Block.h)
+
+Bytecodes.h    // Bytecode definitions for the interpreter
+Linker.h       // External API to the linker
+RtsFlags.h     // External API to the RTS runtime flags
+SchedAPI.h     // External API to the RTS scheduler
+ieee-flpt.h    // ToDo: needed?
+
+RtsAPI.h       // The top-level interface to the RTS (rts_evalIO(), etc.)
+HsFFI.h                // The external FFI api
+