Commit d20d32d7 authored by Simon Marlow's avatar Simon Marlow

Tidy up file headers and copyrights; point to the wiki for docs

I've updated the wiki page about the RTS headers
  http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
to reflect the new layout and explain some of the rationale.  All the
header files now point to this page.
parent f871cf1b
......@@ -7,6 +7,10 @@
*
* NB: Keep in sync with HsFFI.h and StgTypes.h.
* NB: THIS FILE IS INCLUDED IN HASKELL SOURCE!
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef MACHDEPS_H
......
-----------------------------------------------------------------------------
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
ghcconfig.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 */
TickyCounters.h
StgMiscClosures.h /* decls for closures & info tables in the RTS */
SMP.h /* basic primitives for synchronisation */
RtsTypes.h /* types used in the RTS */
Constants.h /* build-time constants */
StgLdvProf.h
StgFun.h
StgProf.h /* profiling gubbins */
Closures.h
Liveness.h /* macros for constructing RET_DYN liveness masks */
ClosureMacros.h
ClosureTypes.h
InfoTables.h
SMPClosureOps.h /* lockClosure/unlockClosure etc. */
SpinLock.h
TSO.h
Updates.h /* macros for performing updates */
Parallel.h
Block.h
Stable.h
Hooks.h
Signals.h
Adjustor.h /* foreign import "wrapper", aka adjustors */
StgPrimFloat.h /* primitive floating-point operations */
Hpc.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 */
......@@ -5,6 +5,9 @@
* RTS external APIs. This file declares everything that the GHC RTS
* exposes externally.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_H
......
......@@ -4,6 +4,9 @@
*
* API for invoking Haskell functions via the RTS
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* --------------------------------------------------------------------------*/
#ifndef RTSAPI_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2004
* (c) The GHC Team, 1998-2009
*
* Top-level include file for everything STG-ish.
*
* This file is included *automatically* by all .hc files.
*
* NOTE: always include Stg.h *before* any other headers, because we
* define some register variables which must be done before any inline
* functions are defined (some system headers have been known to
* define the odd inline function).
* Top-level include file for everything required when compiling .hc
* code. NOTE: in .hc files, Stg.h must be included *before* any
* other headers, because we define some register variables which must
* be done before any inline functions are defined (some system
* headers have been known to define the odd inline function).
*
* We generally try to keep as little visible as possible when
* compiling .hc files. So for example the definitions of the
......@@ -18,6 +15,12 @@
* of these types to generate code which manipulates them directly
* with pointer arithmetic.
*
* In ordinary C code, do not #include this file directly: #include
* "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef STG_H
......
......@@ -4,6 +4,11 @@
*
* Adjustor API
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_ADJUSTOR_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2002
* (c) The GHC Team, 1998-2009
*
* Bytecode definitions.
*
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2004
* (c) The GHC Team, 1998-2009
*
* Rts settings.
*
* NOTE: assumes #include "ghcconfig.h"
*
* NB: THIS FILE IS INCLUDED IN NON-C CODE AND DATA! #defines only please.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_CONFIG_H
......
/* ----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2002
* (c) The GHC Team, 1998-2009
*
* Constants
*
......@@ -12,6 +12,9 @@
* the system (eg. structure sizes) are generated into the file
* DerivedConstants.h by a C program (mkDerivedConstantsHdr).
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_CONSTANTS_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 2007
* (c) The GHC Team, 2007-2009
*
* File locking support as required by Haskell 98
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_FILELOCK_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-1999
* (c) The GHC Team, 1998-2009
*
* Datatypes that holds the command-line flag settings.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_FLAGS_H
......
......@@ -7,6 +7,11 @@
* even when multiple versions of the library are loaded. e.g. see
* Data.Typeable and GHC.Conc.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_GLOBALS_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-1999
* (c) The GHC Team, 1998-2009
*
* User-overridable RTS hooks.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_HOOKS_H
......
......@@ -4,6 +4,11 @@
*
* Haskell Program Coverage
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_HPC_H
......
......@@ -4,6 +4,11 @@
*
* IO Manager functionality in the RTS
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_IOMANAGER_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 2000
* (c) The GHC Team, 2009
*
* RTS Object Linker
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_LINKER_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2004
* (c) The GHC Team, 1998-2009
*
* Message API for use inside the RTS. All messages generated by the
* RTS should go through one of the functions declared here, and we
* also provide hooks so that messages from the RTS can be redirected
* as appropriate.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_MESSAGES_H
......
/* ---------------------------------------------------------------------------
*
* (c) The GHC Team, 2001-2005
* (c) The GHC Team, 2001-2009
*
* Accessing OS threads functionality in a (mostly) OS-independent
* manner.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* --------------------------------------------------------------------------*/
#ifndef RTS_OSTHREADS_H
......
......@@ -4,6 +4,11 @@
*
* Parallelism-related functionality
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_PARALLEL_H
......
......@@ -4,6 +4,11 @@
*
* RTS signal handling
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_SIGNALS_H
......
/* ----------------------------------------------------------------------------
*
* (c) The GHC Team, 2006-2008
* (c) The GHC Team, 2006-2009
*
* Spin locks
*
......@@ -12,6 +12,11 @@
* TODO: measure whether we really need these, or whether Mutexes
* would do (and be a bit safer if a CPU becomes loaded).
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_SPINLOCK_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2004
* (c) The GHC Team, 1998-2009
*
* Stable Pointers
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_STABLE_H
......
......@@ -4,6 +4,11 @@
*
* POSIX TTY-related functionality
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef RTS_TTY_H
......
......@@ -5,6 +5,11 @@
* External API for the scheduler. For most uses, the functions in
* RtsAPI.h should be enough.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_THREADS_H
......
......@@ -4,6 +4,11 @@
*
* TICKY_TICKY types
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_TICKY_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1995-2006
* (c) The GHC Team, 1995-2009
*
* Interface to the RTS timer signal (uses OS-dependent Ticker.h underneath)
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_TIMER_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2008
* (c) The GHC Team, 1998-2009
*
* RTS-specific types.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
/* -------------------------------------------------------------------------
Generally useful typedefs
------------------------------------------------------------------------- */
#ifndef RTS_TYPES_H
#define RTS_TYPES_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 2004
* (c) The GHC Team, 2009
*
* Macros for profiling operations in STG code
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_PROF_CCS_H
......
/* -----------------------------------------------------------------------------
*
* (c) The University of Glasgow, 2004
* (c) The University of Glasgow, 2009
*
* Lag/Drag/Void profiling.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef RTS_PROF_LDV_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2009
*
* Support for Windows DLLs.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef __STGDLL_H__
#define __STGDLL_H__ 1
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-1999
* (c) The GHC Team, 1998-2009
*
* Registers used in STG code. Might or might not correspond to
* actual machine registers.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef MACHREGS_H
......
/* ----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2004
* (c) The GHC Team, 1998-2009
*
* Declarations for various symbols exported by the RTS.
*
......@@ -10,6 +10,11 @@
*
* See wiki:Commentary/Compiler/Backends/PprC#Prototypes
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* --------------------------------------------------------------------------*/
#ifndef STGMISCCLOSURES_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-2004
* (c) The GHC Team, 1998-2009
*
* Registers in the STG machine.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef REGS_H
#define REGS_H
/*
* The STG machine has a collection of "registers", each one of which
* may or may not correspond to an actual machine register when
* running code.
......@@ -17,10 +28,7 @@
* BaseReg is not in a machine register, then the register table is
* used from an absolute location (MainCapability).
*
* ---------------------------------------------------------------------------*/
#ifndef REGS_H
#define REGS_H
*/
typedef struct {
StgWord stgEagerBlackholeInfo;
......
/* ----------------------------------------------------------------------------
*
* (c) The GHC Team, 2005-2008
* (c) The GHC Team, 2005-2009
*
* Macros for multi-CPU support
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
#ifndef SMP_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 1998-1999
* (c) The GHC Team, 1998-2009
*
* Stuff for implementing proper tail jumps.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* ---------------------------------------------------------------------------*/
#ifndef TAILCALLS_H
......
/* -----------------------------------------------------------------------------
*
* (c) The GHC Team, 2007
* (c) The GHC Team, 2009
*
* Declarations for counters used by ticky-ticky profiling.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* -------------------------------------------------------------------------- */
......
......@@ -5,6 +5,23 @@
* Various C datatypes used in the run-time system. This is the
* lowest-level include file, after ghcconfig.h and RtsConfig.h.
*
* Do not #include this file directly: #include "Rts.h" instead.
*
* To understand the structure of the RTS headers, see the wiki:
* http://hackage.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
*
* NOTE: assumes #include "ghcconfig.h"
*
* Works with or without _POSIX_SOURCE.
*
* WARNING: Keep this file, MachDeps.h, and HsFFI.h in synch!
*
* ---------------------------------------------------------------------------*/
#ifndef STGTYPES_H
#define STGTYPES_H
/*
* This module should define types *only*, all beginning with "Stg".
*
* Specifically:
......@@ -22,17 +39,7 @@
StgBool, StgVoid, StgPtr, StgOffset,
StgCode, StgStablePtr, StgFunPtr,
StgUnion.
* WARNING: Keep this file, MachDeps.h, and HsFFI.h in synch!
*
* NOTE: assumes #include "ghcconfig.h"
*
* Works with or without _POSIX_SOURCE.
*
* ---------------------------------------------------------------------------*/
#ifndef STGTYPES_H
#define STGTYPES_H
*/
/*
* First, platform-dependent definitions of size-specific integers.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment