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.

37 files changed, 223 insertions, 161 deletions

diff --git a/includes/MachDeps.h b/includes/MachDeps.h
index 8e6db3ec0e..f97d3e87d4 100644
--- a/includes/MachDeps.h
+++ b/includes/MachDeps.h
@@ -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
diff --git a/includes/README b/includes/README
deleted file mode 100644
index dbde6579f4..0000000000
--- a/includes/README
+++ /dev/null
@@ -1,112 +0,0 @@
------------------------------------------------------------------------------
-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 */
diff --git a/includes/Rts.h b/includes/Rts.h
index 3b5c5bd0e9..74d45f21e6 100644
--- a/includes/Rts.h
+++ b/includes/Rts.h
@@ -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
diff --git a/includes/RtsAPI.h b/includes/RtsAPI.h
index 2d2c35ca97..ff2bc1120a 100644
--- a/includes/RtsAPI.h
+++ b/includes/RtsAPI.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
diff --git a/includes/Stg.h b/includes/Stg.h
index 0344b70fd2..b2051cbdd4 100644
--- a/includes/Stg.h
+++ b/includes/Stg.h
@@ -1,15 +1,12 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Adjustor.h b/includes/rts/Adjustor.h
index 71e15246c1..b65212d1c8 100644
--- a/includes/rts/Adjustor.h
+++ b/includes/rts/Adjustor.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
diff --git a/includes/rts/Bytecodes.h b/includes/rts/Bytecodes.h
index 4aff907cfd..8764b180df 100644
--- a/includes/rts/Bytecodes.h
+++ b/includes/rts/Bytecodes.h
@@ -1,6 +1,6 @@
 /* -----------------------------------------------------------------------------
  *
- * (c) The GHC Team, 1998-2002
+ * (c) The GHC Team, 1998-2009
  *
  * Bytecode definitions.
  *
diff --git a/includes/rts/Config.h b/includes/rts/Config.h
index ce332fa2a2..9e4d683857 100644
--- a/includes/rts/Config.h
+++ b/includes/rts/Config.h
@@ -1,12 +1,16 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Constants.h b/includes/rts/Constants.h
index b283befde2..071d094782 100644
--- a/includes/rts/Constants.h
+++ b/includes/rts/Constants.h
@@ -1,6 +1,6 @@
 /* ----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/FileLock.h b/includes/rts/FileLock.h
index ab59173cef..17087db094 100644
--- a/includes/rts/FileLock.h
+++ b/includes/rts/FileLock.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Flags.h b/includes/rts/Flags.h
index 3f3a0a952f..dca727a1cd 100644
--- a/includes/rts/Flags.h
+++ b/includes/rts/Flags.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Globals.h b/includes/rts/Globals.h
index 71846e75a1..85d0acd4bd 100644
--- a/includes/rts/Globals.h
+++ b/includes/rts/Globals.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
diff --git a/includes/rts/Hooks.h b/includes/rts/Hooks.h
index 4fe50b4b9f..f878dc6e10 100644
--- a/includes/rts/Hooks.h
+++ b/includes/rts/Hooks.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Hpc.h b/includes/rts/Hpc.h
index c966e32cd9..26da35d4cd 100644
--- a/includes/rts/Hpc.h
+++ b/includes/rts/Hpc.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
diff --git a/includes/rts/IOManager.h b/includes/rts/IOManager.h
index 1c269ada6d..ef89f27a30 100644
--- a/includes/rts/IOManager.h
+++ b/includes/rts/IOManager.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
diff --git a/includes/rts/Linker.h b/includes/rts/Linker.h
index df74e7eeb8..73d18cadbe 100644
--- a/includes/rts/Linker.h
+++ b/includes/rts/Linker.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Messages.h b/includes/rts/Messages.h
index e01eff47cf..6f59d1dc3e 100644
--- a/includes/rts/Messages.h
+++ b/includes/rts/Messages.h
@@ -1,12 +1,17 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/OSThreads.h b/includes/rts/OSThreads.h
index 2d32136379..106e1e7e9f 100644
--- a/includes/rts/OSThreads.h
+++ b/includes/rts/OSThreads.h
@@ -1,10 +1,15 @@
 /* ---------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Parallel.h b/includes/rts/Parallel.h
index b6759819b1..f2b56469e7 100644
--- a/includes/rts/Parallel.h
+++ b/includes/rts/Parallel.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
diff --git a/includes/rts/Signals.h b/includes/rts/Signals.h
index 8d9e0fd4b7..4bdd68c06f 100644
--- a/includes/rts/Signals.h
+++ b/includes/rts/Signals.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
diff --git a/includes/rts/SpinLock.h b/includes/rts/SpinLock.h
index ea992a3457..9bfb35bbac 100644
--- a/includes/rts/SpinLock.h
+++ b/includes/rts/SpinLock.h
@@ -1,6 +1,6 @@
 /* ----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Stable.h b/includes/rts/Stable.h
index 95a3f96156..ec867e486c 100644
--- a/includes/rts/Stable.h
+++ b/includes/rts/Stable.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/TTY.h b/includes/rts/TTY.h
index f1ef62eef6..647d88b118 100644
--- a/includes/rts/TTY.h
+++ b/includes/rts/TTY.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
diff --git a/includes/rts/Threads.h b/includes/rts/Threads.h
index 4f343b804c..ca3e8b2da0 100644
--- a/includes/rts/Threads.h
+++ b/includes/rts/Threads.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
diff --git a/includes/rts/Ticky.h b/includes/rts/Ticky.h
index d7e09fcd22..f46e802577 100644
--- a/includes/rts/Ticky.h
+++ b/includes/rts/Ticky.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
diff --git a/includes/rts/Timer.h b/includes/rts/Timer.h
index e3a5c2dc69..39edeb2937 100644
--- a/includes/rts/Timer.h
+++ b/includes/rts/Timer.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/Types.h b/includes/rts/Types.h
index 6f399e083d..ff78402584 100644
--- a/includes/rts/Types.h
+++ b/includes/rts/Types.h
@@ -1,15 +1,16 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
 
diff --git a/includes/rts/prof/CCS.h b/includes/rts/prof/CCS.h
index d56caf0be4..90224d72a0 100644
--- a/includes/rts/prof/CCS.h
+++ b/includes/rts/prof/CCS.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/rts/prof/LDV.h b/includes/rts/prof/LDV.h
index f54724652d..77d873cceb 100644
--- a/includes/rts/prof/LDV.h
+++ b/includes/rts/prof/LDV.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/stg/DLL.h b/includes/stg/DLL.h
index 5e824271bf..b7e7c5aaac 100644
--- a/includes/stg/DLL.h
+++ b/includes/stg/DLL.h
@@ -1,3 +1,16 @@
+/* -----------------------------------------------------------------------------
+ *
+ * (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
 
diff --git a/includes/stg/MachRegs.h b/includes/stg/MachRegs.h
index d6075326db..cd9866671c 100644
--- a/includes/stg/MachRegs.h
+++ b/includes/stg/MachRegs.h
@@ -1,10 +1,15 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/stg/MiscClosures.h b/includes/stg/MiscClosures.h
index 34bd95a550..031c74b45f 100644
--- a/includes/stg/MiscClosures.h
+++ b/includes/stg/MiscClosures.h
@@ -1,6 +1,6 @@
 /* ----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/stg/Regs.h b/includes/stg/Regs.h
index fb26254d5a..d620bf1466 100644
--- a/includes/stg/Regs.h
+++ b/includes/stg/Regs.h
@@ -1,9 +1,20 @@
 /* -----------------------------------------------------------------------------
  *
- * (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;
diff --git a/includes/stg/SMP.h b/includes/stg/SMP.h
index 5d9d80169b..8297f5711c 100644
--- a/includes/stg/SMP.h
+++ b/includes/stg/SMP.h
@@ -1,9 +1,14 @@
 /* ----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/stg/TailCalls.h b/includes/stg/TailCalls.h
index 854c7b4b18..bffd39c674 100644
--- a/includes/stg/TailCalls.h
+++ b/includes/stg/TailCalls.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
diff --git a/includes/stg/Ticky.h b/includes/stg/Ticky.h
index fd7edf85c5..001ab973f7 100644
--- a/includes/stg/Ticky.h
+++ b/includes/stg/Ticky.h
@@ -1,9 +1,14 @@
 /* -----------------------------------------------------------------------------
  *
- * (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
+ *
  * -------------------------------------------------------------------------- */
 
 
diff --git a/includes/stg/Types.h b/includes/stg/Types.h
index 227356c9ea..e05690ac6e 100644
--- a/includes/stg/Types.h
+++ b/includes/stg/Types.h
@@ -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.