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.

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

includes/README

------------------------------------------------------------------------------
-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 */

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

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

includes/Stg.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

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

includes/rts/Bytecodes.h

 /* -----------------------------------------------------------------------------
  *
- * (c) The GHC Team, 1998-2002
+ * (c) The GHC Team, 1998-2009
  *
  * Bytecode definitions.
  *

includes/rts/Config.h

 /* -----------------------------------------------------------------------------
  *
- * (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

includes/rts/Constants.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

includes/rts/FileLock.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

includes/rts/Flags.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

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

includes/rts/Hooks.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

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

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

includes/rts/Linker.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

includes/rts/Messages.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

includes/rts/OSThreads.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

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

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

includes/rts/SpinLock.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

includes/rts/Stable.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

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

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

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

includes/rts/Timer.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

includes/rts/Types.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
 

includes/rts/prof/CCS.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

includes/rts/prof/LDV.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

includes/stg/DLL.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
 

includes/stg/MachRegs.h

 /* -----------------------------------------------------------------------------
  *
- * (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

includes/stg/MiscClosures.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

includes/stg/Regs.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 {