2004-11-01 Joel Sherrill <joel@oarcorp.com>

	* score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h,
	score/include/rtems/seterr.h, score/include/rtems/system.h,
	score/include/rtems/score/address.h,
	score/include/rtems/score/apiext.h,
	score/include/rtems/score/apimutex.h,
	score/include/rtems/score/bitfield.h,
	score/include/rtems/score/chain.h,
	score/include/rtems/score/context.h,
	score/include/rtems/score/copyrt.h,
	score/include/rtems/score/coremsg.h,
	score/include/rtems/score/coremutex.h,
	score/include/rtems/score/coresem.h,
	score/include/rtems/score/heap.h, score/include/rtems/score/interr.h,
	score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h,
	score/include/rtems/score/mppkt.h,
	score/include/rtems/score/objectmp.h,
	score/include/rtems/score/priority.h,
	score/include/rtems/score/stack.h,
	score/include/rtems/score/states.h,
	score/include/rtems/score/sysstate.h,
	score/include/rtems/score/thread.h,
	score/include/rtems/score/threadmp.h,
	score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h,
	score/include/rtems/score/tqdata.h,
	score/include/rtems/score/userext.h,
	score/include/rtems/score/watchdog.h,
	score/include/rtems/score/wkspace.h,
	score/inline/rtems/score/address.inl,
	score/inline/rtems/score/chain.inl,
	score/inline/rtems/score/coremsg.inl,
	score/inline/rtems/score/coremutex.inl,
	score/inline/rtems/score/coresem.inl,
	score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl,
	score/inline/rtems/score/mppkt.inl,
	score/inline/rtems/score/objectmp.inl,
	score/inline/rtems/score/priority.inl,
	score/inline/rtems/score/stack.inl,
	score/inline/rtems/score/states.inl,
	score/inline/rtems/score/sysstate.inl,
	score/inline/rtems/score/thread.inl,
	score/inline/rtems/score/threadmp.inl,
	score/inline/rtems/score/tod.inl,
	score/inline/rtems/score/tqdata.inl,
	score/inline/rtems/score/userext.inl,
	score/inline/rtems/score/watchdog.inl,
	score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working
	modifications which are not complete and may have broken code.
	Committing so work and testing can proceed.
	* score/Doxyfile, score/mainpage.h: New files.

1 files changed, 69 insertions, 56 deletions

diff --git a/cpukit/score/include/rtems/score/context.h b/cpukit/score/include/rtems/score/context.h
index f1ea268c13..7c0b5df16d 100644
--- a/cpukit/score/include/rtems/score/context.h
+++ b/cpukit/score/include/rtems/score/context.h
@@ -1,8 +1,11 @@
-/*  context.h
+/** 
+ *  @file context.h
  *
- *  This include file contains all information about a context.
- *
- *  COPYRIGHT (c) 1989-1999.
+ *  This include file contains all information about each thread's context.
+ */
+
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -15,113 +18,121 @@
 #ifndef __RTEMS_CONTEXT_h
 #define __RTEMS_CONTEXT_h
 
+/**
+ *  @defgroup ScoreContext Context Handler
+ *
+ *  This group contains functionality which abstracts thread context
+ *  management in a portable manner.
+ */
+/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #include <rtems/score/cpu.h>
 
-/*
- *  The following constant defines the number of bytes required
+/**
+ *  @ingroup ScoreContext
+ *  This constant defines the number of bytes required
  *  to store a full floating point context.
  */
-
 #define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE
 
-/*
- *  The following variable is set to TRUE when a reschedule operation
+/**
+ *  @ingroup ScoreContext
+ *  This variable is set to TRUE when a reschedule operation
  *  has determined that the processor should be taken away from the
  *  currently executing thread and given to the heir thread.
  */
 
 SCORE_EXTERN volatile boolean _Context_Switch_necessary;
 
-/*
- *  _Context_Initialize
- *
- *  DESCRIPTION:
- *
- *  This routine initializes THE_CONTEXT such that the stack
+/**
+ *  @ingroup ScoreContext
+ *  This routine initializes @a _the_context such that the stack
  *  pointer, interrupt level, and entry point are correct for the
  *  thread's initial state.
+ *
+ *  @param _the_context (in) will be initialized
+ *  @param _stack (in) is the lowest physical address of the thread's 
+ *         context
+ *  @param _size (in) is the size in octets of the thread's context
+ *  @param _isr (in) is the ISR enable level for this thread
+ *  @param _entry (in) is this thread's entry point
+ *  @param _is_fp (in) is set to TRUE if this thread has floating point
+ *         enabled
  */
-
 #define \
    _Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) \
    _CPU_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp )
 
-/*
- *  _Context_Switch
- *
- *  DESCRIPTION:
+/**
+ *  @ingroup ScoreContext
+ *  This routine saves the current context into the @a _executing
+ *  context record and restores the context specified by @a _heir.
  *
- *  This routine saves the current context into the EXECUTING
- *  context record and restores the context specified by HEIR.
+ *  @param _executing (in) is the currently executing thread's context
+ *  @param _heir (in) is the context of the thread to be switched to
  */
-
 #define _Context_Switch( _executing, _heir ) \
    _CPU_Context_switch( _executing, _heir )
 
-/*
- *  _Context_Restart_self
- *
- *  DESCRIPTION:
- *
+/**
+ *  @ingroup ScoreContext
  *  This routine restarts the calling thread by restoring its initial
  *  stack pointer and returning to the thread's entry point.
+ *
+ *  @param _the_context (in) is the context of the thread to restart
  */
-
 #define _Context_Restart_self( _the_context ) \
    _CPU_Context_Restart_self( _the_context )
 
-/*
- *  _Context_Fp_start
- *
- *  DESCRIPTION:
- *
+/**
+ *  @ingroup ScoreContext
  *  This function returns the starting address of the floating
  *  point context save area.  It is assumed that the are reserved
  *  for the floating point save area is large enough.
+ *
+ *  @param _base (in) is lowest physical address of the floating point
+ *         context save area.
+ *  @param _offset (in) is XXX
+ *
+ *  @return the initial FP context pointer
  */
-
 #define _Context_Fp_start( _base, _offset ) \
    _CPU_Context_Fp_start( (_base), (_offset) )
 
-/*
- *  _Context_Initialize_fp
- *
- *  DESCRIPTION:
- *
+/**
+ *  @ingroup ScoreContext
  *  This routine initializes the floating point context save
  *  area to contain an initial known state.
+ *
+ *  @param _fp_area (in) is the base address of the floating point
+ *         context save area to initialize.
  */
-
 #define _Context_Initialize_fp( _fp_area ) \
    _CPU_Context_Initialize_fp( _fp_area )
 
-/*
- *  _Context_Restore_fp
- *
- *  DESCRIPTION:
- *
+/**
+ *  @ingroup ScoreContext
  *  This routine restores the floating point context contained
- *  in the FP_CONTEXT area.  It is assumed that the current
+ *  in the @a _fp area.  It is assumed that the current
  *  floating point context has been saved by a previous invocation
- *  of SAVE_FP.
+ *  of @a _Context_Save_fp.
+ *
+ *  @param _fp (in) points to the floating point context area to restore.
  */
-
 #define _Context_Restore_fp( _fp ) \
    _CPU_Context_restore_fp( _fp )
 
-/*
- *  _Context_Save_fp
- *
- *  DESCRIPTION:
- *
+/**
+ *  @ingroup ScoreContext
  *  This routine saves the current floating point context
- *  in the FP_CONTEXT area.
+ *  in the @a _fp area.
+ *
+ *  @param _fp (in) points to the floating point context area to restore.
  */
-
 #define _Context_Save_fp( _fp ) \
    _CPU_Context_save_fp( _fp )
 
@@ -129,5 +140,7 @@ SCORE_EXTERN volatile boolean _Context_Switch_necessary;
 }
 #endif
 
+/**@}*/
+
 #endif
 /* end of include file */