Changeset baff4da – RTEMS Project

cpukit/ChangeLog

-                      r7ce11b2
+                      rbaff4da
+-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.
 -11-01      Joel Sherrill <joel@oarcorp.com>

cpukit/score/cpu/no_cpu/rtems/score/cpu.h

-                      r7ce11b2
+                      rbaff4da
 /*  cpu.h
+/** @file  cpu.h
+ *
  *  This include file contains information pertaining to the XXX
  *  processor.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ *  @note This file is part of a porting template that is intended
+ *  to be used as the starting point when porting RTEMS to a new
+ *  CPU family.  The following needs to be done when using this as
+ *  the starting point for a new port:
+ *
+ *  + Anywhere there is an XXX, it should be replaced
+ *    with information about the CPU family being ported to.
+ *
+ *  + At the end of each comment section, there is a heading which
+ *    says "Port Specific Information:".  When porting to RTEMS,
+ *    add CPU family specific information in this section
+ */
+/*  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 /* conditional compilation parameters */
 /*
  *  Should the calls to _Thread_Enable_dispatch be inlined?
+/**
+ *  Should the calls to @ref _Thread_Enable_dispatch be inlined?
+ *
  *  If TRUE, then they are inlined.
  *  If FALSE, then a subroutine call is made.
+ *
  *  Basically this is an example of the classic trade-off of size
+ *  This conditional is an example of the classic trade-off of size
  *  versus speed.  Inlining the call (TRUE) typically increases the
  *  size of RTEMS while speeding up the enabling of dispatching.
+ *  [NOTE: In general, the _Thread_Dispatch_disable_level will
+ *
+ *  @note In general, the @ref _Thread_Dispatch_disable_level will
  *  only be 0 or 1 unless you are in an interrupt handler and that
  *  interrupt handler invokes the executive.]  When not inlined
+ *  something calls _Thread_Enable_dispatch which in turns calls
+ *  _Thread_Dispatch.  If the enable dispatch is inlined, then
+ *  one subroutine call is avoided entirely.]
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  something calls @ref _Thread_Enable_dispatch which in turns calls
+ *  @ref _Thread_Dispatch.  If the enable dispatch is inlined, then
+ *  one subroutine call is avoided entirely.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_INLINE_ENABLE_DISPATCH       FALSE
 /*
+/**
  *  Should the body of the search loops in _Thread_queue_Enqueue_priority
  *  be unrolled one time?  In unrolled each iteration of the loop examines
 …
  *  necessary to strike a balance when setting this parameter.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_UNROLL_ENQUEUE_PRIORITY      TRUE
 /*
+/**
  *  Does RTEMS manage a dedicated interrupt stack in software?
+ *
  *  If TRUE, then a stack is allocated in _ISR_Handler_initialization.
+ *  If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
  *  If FALSE, nothing is done.
+ *
 …
  *  interrupt stack.
+ *
  *  If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
+ *
  *  Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
  *  CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
+ *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
+ *
+ *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
+ *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
  *  possible that both are FALSE for a particular CPU.  Although it
  *  is unclear what that would imply about the interrupt processing
  *  procedure on that CPU.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_HAS_SOFTWARE_INTERRUPT_STACK FALSE
 /*
+/**
  *  Does this CPU have hardware support for a dedicated interrupt stack?
+ *
 …
  *  If FALSE, then no installation is performed.
+ *
  *  If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
+ *
  *  Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
  *  CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
+ *  If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
+ *
+ *  Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
+ *  @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is
  *  possible that both are FALSE for a particular CPU.  Although it
  *  is unclear what that would imply about the interrupt processing
  *  procedure on that CPU.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_HAS_HARDWARE_INTERRUPT_STACK TRUE
 /*
+/**
  *  Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
+ *
 …
  *  If FALSE, then the memory is allocated during initialization.
+ *
+ *  This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE
+ *  or CPU_INSTALL_HARDWARE_INTERRUPT_STACK is TRUE.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  This should be TRUE is @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE
+ *  or @ref CPU_INSTALL_HARDWARE_INTERRUPT_STACK is TRUE.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_ALLOCATE_INTERRUPT_STACK TRUE
 /*
+/**
  *  Does the RTEMS invoke the user's ISR with the vector number and
  *  a pointer to the saved interrupt frame (1) or just the vector
  *  number (0)?
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_ISR_PASSES_FRAME_POINTER 0
+/*
+/**
+ *  @def CPU_HARDWARE_FP
+ *
  *  Does the CPU have hardware floating point?
+ *
  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
+ *  If TRUE, then the @ref RTEMS_FLOATING_POINT task attribute is supported.
+ *  If FALSE, then the @ref RTEMS_FLOATING_POINT task attribute is ignored.
+ *
  *  If there is a FP coprocessor such as the i387 or mc68881, then
 …
  *  which set this to false to indicate that you have an i386 without
  *  an i387 and wish to leave floating point support out of RTEMS.
+ *
+ *  The CPU_SOFTWARE_FP is used to indicate whether or not there
+ */
+/**
+ *  @def CPU_SOFTWARE_FP
+ *
+ *  Does the CPU have no hardware floating point and GCC provides a
+ *  software floating point implementation which must be context
+ *  switched?
+ *
+ *  This feature conditional is used to indicate whether or not there
  *  is software implemented floating point that must be context
  *  switched.  The determination of whether or not this applies
 …
  *  compiler specific.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #if ( NO_CPU_HAS_FPU == 1 )
 #define CPU_HARDWARE_FP     TRUE
 …
 #define CPU_SOFTWARE_FP     FALSE
 /*
+/**
  *  Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
+ *
  *  If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
  *  If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
+ *  If TRUE, then the @ref RTEMS_FLOATING_POINT task attribute is assumed.
+ *  If FALSE, then the @ref RTEMS_FLOATING_POINT task attribute is followed.
+ *
  *  So far, the only CPUs in which this option has been used are the
 …
  *  In this case, this option should be TRUE.
+ *
+ *  If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_ALL_TASKS_ARE_FP     TRUE
 /*
+/**
  *  Should the IDLE task have a floating point context?
+ *
  *  If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
+ *  If TRUE, then the IDLE task is created as a @ref RTEMS_FLOATING_POINT task
  *  and it has a floating point context which is switched in and out.
  *  If FALSE, then the IDLE task does not have a floating point context.
 …
  *  must be saved as part of the preemption.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_IDLE_TASK_IS_FP      FALSE
 /*
+/**
  *  Should the saving of the floating point registers be deferred
  *  until a context switch is made to another different floating point
 …
  *  be saved or restored.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_USE_DEFERRED_FP_SWITCH       TRUE
 /*
+/**
  *  Does this port provide a CPU dependent IDLE task implementation?
+ *
  *  If TRUE, then the routine _CPU_Thread_Idle_body
+ *  If TRUE, then the routine @ref _CPU_Thread_Idle_body
  *  must be provided and is the default IDLE thread body instead of
  *  _CPU_Thread_Idle_body.
+ *  @ref _CPU_Thread_Idle_body.
+ *
  *  If FALSE, then use the generic IDLE thread body if the BSP does
 …
  *  The order of precedence for selecting the IDLE thread body is:
+ *
+ *    1.  BSP provided
+ *    2.  CPU dependent (if provided)
+ *    3.  generic (if no BSP and no CPU dependent)
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *    -#  BSP provided
+ *    -#  CPU dependent (if provided)
+ *    -#  generic (if no BSP and no CPU dependent)
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_PROVIDES_IDLE_THREAD_BODY    TRUE
 /*
+/**
  *  Does the stack grow up (toward higher addresses) or down
  *  (toward lower addresses)?
 …
  *  If FALSE, then the grows toward smaller addresses.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_STACK_GROWS_UP               TRUE
 /*
+/**
  *  The following is the variable attribute used to force alignment
  *  of critical RTEMS structures.  On some processors it may make
 …
  *      __attribute__ ((aligned (32)))
+ *
+ *  NOTE:  Currently only the Priority Bit Map table uses this feature.
+ *         To benefit from using this, the data must be heavily
+ *         used so it will stay in the cache and used frequently enough
+ *         in the executive to justify turning this on.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @note Currently only the Priority Bit Map table uses this feature.
+ *        To benefit from using this, the data must be heavily
+ *        used so it will stay in the cache and used frequently enough
+ *        in the executive to justify turning this on.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_STRUCTURE_ALIGNMENT
+/*
+/**
+ *  @defgroup CPUEndian Processor Dependent Endianness Support
+ *
+ *  This group assists in issues related to processor endianness.
+ */
+/**
+ *  @ingroup CPUEndian
  *  Define what is required to specify how the network to host conversion
  *  routines are handled.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+#define CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES     FALSE
+ *  @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
+ *  same values.
+ *
+ *  @see CPU_LITTLE_ENDIAN
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_BIG_ENDIAN                           TRUE
+/**
+ *  @ingroup CPUEndian
+ *  Define what is required to specify how the network to host conversion
+ *  routines are handled.
+ *
+ *  @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
+ *  same values.
+ *
+ *  @see CPU_BIG_ENDIAN
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_LITTLE_ENDIAN                        FALSE
+/*
+/**
+ *  @ingroup CPUInterrupt
  *  The following defines the number of bits actually used in the
  *  interrupt field of the task mode.  How those bits map to the
+ *  CPU interrupt levels is defined by the routine _CPU_ISR_Set_level().
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_MODES_INTERRUPT_MASK   0x00000001
 …
  *  Processor defined structures required for cpukit/score.
+ *
  *  NO_CPU Specific Information:
+ *  Port Specific Information:
+ *
  *  XXX document implementation including references if appropriate
 …
 /* may need to put some structures here.  */
+/*
+ * Contexts
+ *
+ *  Generally there are 2 types of context to save.
+ *     1. Interrupt registers to save
+ *     2. Task level registers to save
+ *
+ *  This means we have the following 3 context items:
+ *     1. task level context stuff::  Context_Control
+ *     2. floating point task stuff:: Context_Control_fp
+ *     3. special interrupt level context :: Context_Control_interrupt
+/**
+ * @defgroup CPUContext Processor Dependent Context Management
+ *
+ *  From the highest level viewpoint, there are 2 types of context to save.
+ *
+ *     -# Interrupt registers to save
+ *     -# Task level registers to save
+ *
+ *  Since RTEMS handles integer and floating point contexts separately, this
+ *  means we have the following 3 context items:
+ *
+ *     -# task level context stuff::  Context_Control
+ *     -# floating point task stuff:: Context_Control_fp
+ *     -# special interrupt level context :: CPU_Interrupt_frame
+ *
  *  On some processors, it is cost-effective to save only the callee
 …
  *  a debugger such as gdb.  But that is another problem.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+/**
+ *  @ingroup CPUContext Management
+ *  This defines the minimal set of integer and processor state registers
+ *  that must be saved during a voluntary context switch from one thread
+ *  to another.
+ */
 typedef struct {
+    /** This field is a hint that a port will have a number of integer
+     *  registers that need to be saved at a context switch.
+     */
     uint32_t   some_integer_register;
+    /** This field is a hint that a port will have a number of system
+     *  registers that need to be saved at a context switch.
+     */
     uint32_t   some_system_register;
 } Context_Control;
+/**
+ *  @ingroup CPUContext Management
+ *  This defines the complete set of floating point registers that must
+ *  be saved during any context switch from one thread to another.
+ */
 typedef struct {
     double      some_float_register;
 } Context_Control_fp;
+/**
+ *  @ingroup CPUContext Management
+ *  This defines the set of integer and processor state registers that must
+ *  be saved during an interrupt.  This set does not include any which are
+ *  in @ref Context_Control.
+ */
 typedef struct {
+    /** This field is a hint that a port will have a number of integer
+     *  registers that need to be saved when an interrupt occurs or
+     *  when a context switch occurs at the end of an ISR.
+     */
     uint32_t   special_interrupt_register;
 } CPU_Interrupt_frame;
 /*
+/**
  *  The following table contains the information required to configure
  *  the XXX processor specific parameters.
+ *
  *  NO_CPU Specific Information:
+ *  Port Specific Information:
+ *
  *  XXX document implementation including references if appropriate
 …
 typedef struct {
+  /** This element points to the BSP's pretasking hook. */
   void       (*pretasking_hook)( void );
+  /** This element points to the BSP's predriver hook. */
   void       (*predriver_hook)( void );
+  /** This element points to the BSP's postdriver hook. */
   void       (*postdriver_hook)( void );
+  /** This element points to the BSP's optional idle task which may override
+   *  the default one provided with RTEMS.
+   */
   void       (*idle_task)( void );
+  /** If this element is TRUE, then RTEMS will zero the Executive Workspace.
+   *  When this element is FALSE, it is assumed that the BSP or invoking
+   *  environment has ensured that memory was cleared before RTEMS was
+   *  invoked.
+   */
   boolean      do_zero_of_workspace;
+  /** This field specifies the size of the IDLE task's stack.  If less than or
+   *  equal to the minimum stack size, then the IDLE task will have the minimum
+   *  stack size.
+   */
   uint32_t     idle_task_stack_size;
+  /** This field specifies the size of the interrupt stack.  If less than or
+   *  equal to the minimum stack size, then the interrupt stack will be of
+   *  minimum stack size.
+   */
   uint32_t     interrupt_stack_size;
+  /** The MPCI Receive server is assumed to have a stack of at least
+   *  minimum stack size.  This field specifies the amount of extra
+   *  stack this task will be given in bytes.
+   */
   uint32_t     extra_mpci_receive_server_stack;
+  /** The BSP may want to provide it's own stack allocation routines.
+   *  In this case, the BSP will provide this stack allocation hook.
+   */
   void *     (*stack_allocate_hook)( uint32_t   );
+  void       (*stack_free_hook)( void* );
+  /** The BSP may want to provide it's own stack free routines.
+   *  In this case, the BSP will provide this stack free hook.
+   */
+  void       (*stack_free_hook)( void *);
   /* end of fields required on all CPUs */
 }   rtems_cpu_table;
 …
  *  the file rtems/system.h.
+ *
  *  NO_CPU Specific Information:
+ *  Port Specific Information:
+ *
  *  XXX document implementation including references if appropriate
 …
  *  Macros to access NO_CPU specific additions to the CPU Table
+ *
  *  NO_CPU Specific Information:
+ *  Port Specific Information:
+ *
  *  XXX document implementation including references if appropriate
 …
 /* There are no CPU specific additions to the CPU Table for this port. */
 /*
+/**
  *  This variable is optional.  It is used on CPUs on which it is difficult
  *  to generate an "uninitialized" FP context.  It is filled in by
+ *  _CPU_Initialize and copied into the task's FP context area during
+ *  _CPU_Context_Initialize.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @ref _CPU_Initialize and copied into the task's FP context area during
+ *  @ref _CPU_Context_Initialize.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 SCORE_EXTERN Context_Control_fp  _CPU_Null_fp_context;
+/*
+/**
+ *  @defgroup CPUInterrupt Processor Dependent Interrupt Management
+ *
  *  On some CPUs, RTEMS supports a software managed interrupt stack.
  *  This stack is allocated by the Interrupt Manager and the switch
  *  is performed in _ISR_Handler.  These variables contain pointers
+ *  is performed in @ref _ISR_Handler.  These variables contain pointers
  *  to the lowest and highest addresses in the chunk of memory allocated
  *  for the interrupt stack.  Since it is unknown whether the stack
 …
  *  code the option of picking the version it wants to use.
+ *
+ *  NOTE: These two variables are required if the macro
+ *        CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @note These two variables are required if the macro
+ *        @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+/**
+ *  @ingroup CPUInterrupt
+ *  This variable points to the lowest physical address of the interrupt
+ *  stack.
+ */
 SCORE_EXTERN void               *_CPU_Interrupt_stack_low;
+/**
+ *  @ingroup CPUInterrupt
+ *  This variable points to the lowest physical address of the interrupt
+ *  stack.
+ */
 SCORE_EXTERN void               *_CPU_Interrupt_stack_high;
+/*
+/**
+ *  @ingroup CPUInterrupt
  *  With some compilation systems, it is difficult if not impossible to
  *  call a high-level language routine from assembly language.  This
  *  is especially true of commercial Ada compilers and name mangling
  *  C++ ones.  This variable can be optionally defined by the CPU porter
  *  and contains the address of the routine _Thread_Dispatch.  This
+ *  and contains the address of the routine @ref _Thread_Dispatch.  This
  *  can make it easier to invoke that routine at the end of the interrupt
  *  sequence (if a dispatch is necessary).
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 SCORE_EXTERN void           (*_CPU_Thread_dispatch_pointer)();
 …
  *  Nothing prevents the porter from declaring more CPU specific variables.
+ *
  *  NO_CPU Specific Information:
+ *  Port Specific Information:
+ *
  *  XXX document implementation including references if appropriate
 …
 /* XXX: if needed, put more variables here */
+/*
+/**
+ *  @ingroup CPUContext
  *  The size of the floating point context area.  On some CPUs this
  *  will not be a "sizeof" because the format of the floating point
 …
  *  CPUs with a "floating point save context" instruction.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
 /*
+/**
  *  Amount of extra stack (above minimum stack size) required by
  *  MPCI receive server thread.  Remember that in a multiprocessor
  *  system this thread must exist and be able to process all directives.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
+/*
+ *  This defines the number of entries in the ISR_Vector_table managed
+/**
+ *  @ingroup CPUInterrupt
+ *  This defines the number of entries in the @ref _ISR_Vector_table managed
  *  by RTEMS.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_INTERRUPT_NUMBER_OF_VECTORS      32
+/**
+ *  @ingroup CPUInterrupt
+ *  This defines the highest interrupt vector number for this port.
+ */
 #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER  (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
+/*
+/**
+ *  @ingroup CPUInterrupt
  *  This is defined if the port has a special way to report the ISR nesting
+ *  level.  Most ports maintain the variable _ISR_Nest_level.
+ */
+ *  level.  Most ports maintain the variable @a _ISR_Nest_level.
+ */
 #define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE
+/*
+ *  Should be large enough to run all RTEMS tests.  This insures
+/**
+ *  @ingroup CPUContext
+ *  Should be large enough to run all RTEMS tests.  This ensures
  *  that a "reasonable" small application should not have any problems.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_STACK_MINIMUM_SIZE          (1024*4)
 /*
+/**
  *  CPU's worst alignment requirement for data types on a byte boundary.  This
  *  alignment does not take into account the requirements for the stack.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_ALIGNMENT              8
 /*
+/**
  *  This number corresponds to the byte alignment requirement for the
  *  heap handler.  This alignment requirement may be stricter than that
  *  for the data types alignment specified by CPU_ALIGNMENT.  It is
+ *  for the data types alignment specified by @ref CPU_ALIGNMENT.  It is
  *  common for the heap to follow the same alignment requirement as
  *  CPU_ALIGNMENT.  If the CPU_ALIGNMENT is strict enough for the heap,
  *  then this should be set to CPU_ALIGNMENT.
+ *
  *  NOTE:  This does not have to be a power of 2 although it should be
+ *  @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is strict enough for
+ *  the heap, then this should be set to @ref CPU_ALIGNMENT.
+ *
+ *  @note  This does not have to be a power of 2 although it should be
  *         a multiple of 2 greater than or equal to 2.  The requirement
  *         to be a multiple of 2 is because the heap uses the least
 …
  *         length blocks really putting length data in that bit.
+ *
  *         On byte oriented architectures, CPU_HEAP_ALIGNMENT normally will
  *         have to be greater or equal to than CPU_ALIGNMENT to ensure that
+ *         On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
+ *         have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
  *         elements allocated from the heap meet all restrictions.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_HEAP_ALIGNMENT         CPU_ALIGNMENT
 /*
+/**
  *  This number corresponds to the byte alignment requirement for memory
  *  buffers allocated by the partition manager.  This alignment requirement
  *  may be stricter than that for the data types alignment specified by
  *  CPU_ALIGNMENT.  It is common for the partition to follow the same
  *  alignment requirement as CPU_ALIGNMENT.  If the CPU_ALIGNMENT is strict
  *  enough for the partition, then this should be set to CPU_ALIGNMENT.
+ *
  *  NOTE:  This does not have to be a power of 2.  It does have to
  *         be greater or equal to than CPU_ALIGNMENT.
+ *
  *  NO_CPU Specific Information:
+ *
  *  XXX document implementation including references if appropriate
  */
+ *  @ref CPU_ALIGNMENT.  It is common for the partition to follow the same
+ *  alignment requirement as @ref CPU_ALIGNMENT.  If the @ref CPU_ALIGNMENT is
+ *  strict enough for the partition, then this should be set to
+ *  @ref CPU_ALIGNMENT.
+ *
+ *  @note  This does not have to be a power of 2.  It does have to
+ *         be greater or equal to than @ref CPU_ALIGNMENT.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_PARTITION_ALIGNMENT    CPU_ALIGNMENT
 /*
+/**
  *  This number corresponds to the byte alignment requirement for the
  *  stack.  This alignment requirement may be stricter than that for the
  *  data types alignment specified by CPU_ALIGNMENT.  If the CPU_ALIGNMENT
  *  is strict enough for the stack, then this should be set to 0.
+ *
  *  NOTE:  This must be a power of 2 either 0 or greater than CPU_ALIGNMENT.
+ *
  *  NO_CPU Specific Information:
+ *
  *  XXX document implementation including references if appropriate
  */
+ *  data types alignment specified by @ref CPU_ALIGNMENT.  If the
+ *  @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
+ *  set to 0.
+ *
+ *  @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define CPU_STACK_ALIGNMENT        0
 …
  */
+/*
+/**
+ *  @ingroup CPUInterrupt
  *  Support routine to initialize the RTEMS vector table after it is allocated.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_Initialize_vectors()
+/*
+/**
+ *  @ingroup CPUInterrupt
  *  Disable all interrupts for an RTEMS critical section.  The previous
+ *  level is returned in _level.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  level is returned in @a _isr_cookie.
+ *
+ *  @param _isr_cookie (out) will contain the previous level cookie
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_ISR_Disable( _isr_cookie ) \
   { \
 …
+  }
+/*
+/**
+ *  @ingroup CPUInterrupt
  *  Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
  *  This indicates the end of an RTEMS critical section.  The parameter
+ *  _level is not modified.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @a _isr_cookie is not modified.
+ *
+ *  @param _isr_cookie (in) contain the previous level cookie
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_ISR_Enable( _isr_cookie )  \
   { \
+  }
+/*
+ *  This temporarily restores the interrupt to _level before immediately
+/**
+ *  @ingroup CPUInterrupt
+ *  This temporarily restores the interrupt to @a _isr_cookie before immediately
  *  disabling them again.  This is used to divide long RTEMS critical
+ *  sections into two or more parts.  The parameter _level is not
+ * modified.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  sections into two or more parts.  The parameter @a _isr_cookie is not
+ *  modified.
+ *
+ *  @param _isr_cookie (in) contain the previous level cookie
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_ISR_Flash( _isr_cookie ) \
   { \
+  }
+/*
+ *  Map interrupt level in task mode onto the hardware that the CPU
+/**
+ *  @ingroup CPUInterrupt
+ *
+ *  This routine and @ref _CPU_ISR_Get_level
+ *  Map the interrupt level in task mode onto the hardware that the CPU
  *  actually provides.  Currently, interrupt levels which do not
  *  map onto the CPU in a generic fashion are undefined.  Someday,
 …
  *  via the rtems_task_mode directive.
+ *
+ *  The get routine usually must be implemented as a subroutine.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_ISR_Set_level( new_level ) \
   { \
+  }
+/**
+ *  @ingroup CPUInterrupt
+ *  Return the current interrupt disable level for this task in
+ *  the format used by the interrupt level portion of the task mode.
+ *
+ *  @note This routine usually must be implemented as a subroutine.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 uint32_t   _CPU_ISR_Get_level( void );
 …
 /* Context handler macros */
+/*
+/**
+ *  @ingroup CPUContext
  *  Initialize the context to a state suitable for starting a
  *  task after a context restore operation.  Generally, this
 …
  *  undefined at task start time.
+ *
+ *  NOTE: This is_fp parameter is TRUE if the thread is to be a floating
+ *  @param _the_context (in) is the context structure to be initialized
+ *  @param _stack_base (in) is the lowest physical address of this task's stack
+ *  @param _size (in) is the size of this task's stack
+ *  @param _isr (in) is the interrupt disable level
+ *  @param _entry_point (in) is the thread's entry point.  This is
+ *         always @a _Thread_Handler
+ *  @param _is_fp (in) is TRUE if the thread is to be a floating
  *        point thread.  This is typically only used on CPUs where the
  *        FPU may be easily disabled by software such as on the SPARC
  *        where the PSR contains an enable FPU bit.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_Context_Initialize( _the_context, _stack_base, _size, \
                                  _isr, _entry_point, _is_fp ) \
 …
  *  is restoring the context.  Otherwise, there will need to be
  *  a special assembly routine which does something special in this
  *  case.  Context_Restore should work most of the time.  It will
+ *  case.  @ref _CPU_Context_Restore should work most of the time.  It will
  *  not work if restarting self conflicts with the stack frame
  *  assumptions of restoring a context.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_Context_Restart_self( _the_context ) \
    _CPU_Context_restore( (_the_context) );
+/*
+/**
+ *  @ingroup CPUContext
  *  The purpose of this macro is to allow the initial pointer into
  *  a floating point context area (used to save the floating point
 …
  *  or low to high based on the whim of the CPU designers.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param _base (in) is the lowest physical address of the floating point
+ *         context area
+ *  @param _offset (in) is the offset into the floating point area
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_Context_Fp_start( _base, _offset ) \
    ( (void *) _Addresses_Add_offset( (_base), (_offset) ) )
 /*
+/**
  *  This routine initializes the FP context area passed to it to.
  *  There are a few standard ways in which to initialize the
  *  floating point context.  The code included for this macro assumes
  *  that this is a CPU in which a "initial" FP context was saved into
  *  _CPU_Null_fp_context and it simply copies it to the destination
+ *  @a _CPU_Null_fp_context and it simply copies it to the destination
  *  context passed to it.
+ *
+ *  Other models include (1) not doing anything, and (2) putting
+ *  a "null FP status word" in the correct place in the FP context.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Other floating point context save/restore models include:
+ *    -# not doing anything, and
+ *    -# putting a "null FP status word" in the correct place in the FP context.
+ *
+ *  @param _destination (in) is the floating point context area
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_Context_Initialize_fp( _destination ) \
   { \
 …
 /* Fatal Error manager macros */
 /*
+/**
  *  This routine copies _error into a known place -- typically a stack
  *  location or a register, optionally disables interrupts, and
  *  halts/stops the CPU.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #define _CPU_Fatal_halt( _error ) \
   { \
 …
 /* Bitfield handler macros */
+/*
+ *  This routine sets _output to the bit number of the first bit
+ *  set in _value.  _value is of CPU dependent type Priority_Bit_map_control.
+ *  This type may be either 16 or 32 bits wide although only the 16
+ *  least significant bits will be used.
+/**
+ *  @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
+ *
+ *  This set of routines are used to implement fast searches for
+ *  the most important ready task.
+ */
+/**
+ *  @ingroup CPUBitfield
+ *  This definition is set to TRUE if the port uses the generic bitfield
+ *  manipulation implementation.
+ */
+#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
+/**
+ *  @ingroup CPUBitfield
+ *  This definition is set to TRUE if the port uses the data tables provided
+ *  by the generic bitfield manipulation implementation.
+ *  This can occur when actually using the generic bitfield manipulation
+ *  implementation or when implementing the same algorithm in assembly
+ *  language for improved performance.  It is unlikely that a port will use
+ *  the data if it has a bitfield scan instruction.
+ */
+#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
+/**
+ *  @ingroup CPUBitfield
+ *  This routine sets @a _output to the bit number of the first bit
+ *  set in @a _value.  @a _value is of CPU dependent type
+ *  @a Priority_Bit_map_control.  This type may be either 16 or 32 bits
+ *  wide although only the 16 least significant bits will be used.
+ *
  *  There are a number of variables in using a "find first bit" type
  *  instruction.
+ *
  *    (1) What happens when run on a value of zero?
  *    (2) Bits may be numbered from MSB to LSB or vice-versa.
  *    (3) The numbering may be zero or one based.
  *    (4) The "find first bit" instruction may search from MSB or LSB.
+ *    -# What happens when run on a value of zero?
+ *    -# Bits may be numbered from MSB to LSB or vice-versa.
+ *    -# The numbering may be zero or one based.
+ *    -# The "find first bit" instruction may search from MSB or LSB.
+ *
  *  RTEMS guarantees that (1) will never happen so it is not a concern.
  *  (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
  *  _CPU_Priority_bits_index().  These three form a set of routines
+ *  (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
+ *  @ref _CPU_Priority_bits_index.  These three form a set of routines
  *  which must logically operate together.  Bits in the _value are
  *  set and cleared based on masks built by _CPU_Priority_mask().
  *  The basic major and minor values calculated by _Priority_Major()
  *  and _Priority_Minor() are "massaged" by _CPU_Priority_bits_index()
+ *  set and cleared based on masks built by @ref _CPU_Priority_Mask.
+ *  The basic major and minor values calculated by @ref _Priority_Major
+ *  and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
  *  to properly range between the values returned by the "find first bit"
  *  instruction.  This makes it possible for _Priority_Get_highest() to
+ *  instruction.  This makes it possible for @ref _Priority_Get_highest to
  *  calculate the major and directly index into the minor table.
  *  This mapping is necessary to ensure that 0 (a high priority major/minor)
 …
  *  to implement this in software:
+ *
+ *    - a series of 16 bit test instructions
+ *    - a "binary search using if's"
+ *    - _number = 0
+ *      if _value > 0x00ff
+ *        _value >>=8
+ *        _number = 8;
+ *
+ *      if _value > 0x0000f
+ *        _value >=8
+ *        _number += 4
+ *
+ *      _number += bit_set_table[ _value ]
+ *
+@verbatim
+      - a series of 16 bit test instructions
+      - a "binary search using if's"
+      - _number = 0
+        if _value > 0x00ff
+          _value >>=8
+          _number = 8;
+        if _value > 0x0000f
+          _value >=8
+          _number += 4
+        _number += bit_set_table[ _value ]
+@endverbatim
  *    where bit_set_table[ 16 ] has values which indicate the first
  *      bit set
+ *
  *  NO_CPU Specific Information:
+ *
  *  XXX document implementation including references if appropriate
  */
+#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
+#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
+ *  @param _value (in) is the value to be scanned
+ *  @param _output (in) is the first bit set
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
 #define _CPU_Bitfield_Find_first_bit( _value, _output ) \
   { \
     (_output) = 0;   /* do something to prevent warnings */ \
+  }
 #endif
 /* end of Bitfield handler macros */
 /*
+/**
  *  This routine builds the mask which corresponds to the bit fields
  *  as searched by _CPU_Bitfield_Find_first_bit().  See the discussion
+ *  as searched by @ref _CPU_Bitfield_Find_first_bit.  See the discussion
  *  for that routine.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
 …
 #endif
+/*
+/**
+ *  @ingroup CPUBitfield
  *  This routine translates the bit numbers returned by
  *  _CPU_Bitfield_Find_first_bit() into something suitable for use as
+ *  @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
  *  a major or minor component of a priority.  See the discussion
  *  for that routine.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param _priority (in) is the major or minor number to translate
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
 …
 /* functions */
+/*
+ *  _CPU_Initialize
+ *
+/**
  *  This routine performs CPU dependent initialization.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param cpu_table (in) is the CPU Dependent Configuration Table
+ *  @param thread_dispatch (in) is the address of @ref _Thread_Dispatch
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Initialize(
   rtems_cpu_table  *cpu_table,
 …
 );
+/*
+ *  _CPU_ISR_install_raw_handler
+ *
+/**
+ *  @ingroup CPUInterrupt
  *  This routine installs a "raw" interrupt handler directly into the
  *  processor's vector table.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param vector (in) is the vector number
+ *  @param new_handler (in) is the raw ISR handler to install
+ *  @param old_handler (in) is the previously installed ISR Handler
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_ISR_install_raw_handler(
   uint32_t    vector,
 …
 );
+/*
+ *  _CPU_ISR_install_vector
+ *
+/**
+ *  @ingroup CPUInterrupt
  *  This routine installs an interrupt vector.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param vector (in) is the vector number
+ *  @param new_handler (in) is the RTEMS ISR handler to install
+ *  @param old_handler (in) is the previously installed ISR Handler
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_ISR_install_vector(
   uint32_t    vector,
 …
 );
+/*
+ *  _CPU_Install_interrupt_stack
+ *
+/**
+ *  @ingroup CPUInterrupt
  *  This routine installs the hardware interrupt stack pointer.
+ *
  *  NOTE:  It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STACK
+ *  @note  It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK
  *         is TRUE.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Install_interrupt_stack( void );
+/*
+ *  _CPU_Thread_Idle_body
+ *
+/**
  *  This routine is the CPU dependent IDLE thread body.
+ *
  *  NOTE:  It need only be provided if CPU_PROVIDES_IDLE_THREAD_BODY
+ *  @note  It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY
  *         is TRUE.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Thread_Idle_body( void );
+/*
+ *  _CPU_Context_switch
+ *
+/**
+ *  @ingroup CPUContext
  *  This routine switches from the run context to the heir context.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param run (in) points to the context of the currently executing task
+ *  @param heir (in) points to the context of the heir task
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Context_switch(
   Context_Control  *run,
 …
 );
+/*
+ *  _CPU_Context_restore
+ *
+/**
+ *  @ingroup CPUContext
  *  This routine is generally used only to restart self in an
+ *  efficient manner.  It may simply be a label in _CPU_Context_switch.
+ *
+ *  NOTE: May be unnecessary to reload some registers.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  efficient manner.  It may simply be a label in @ref _CPU_Context_switch.
+ *
+ *  @param new_context (in) points to the context to be restored.
+ *
+ *  @note May be unnecessary to reload some registers.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Context_restore(
   Context_Control *new_context
 );
+/*
+ *  _CPU_Context_save_fp
+ *
+/**
+ *  @ingroup CPUContext
  *  This routine saves the floating point context passed to it.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param fp_context_ptr (in) is a pointer to a pointer to a floating
+ *  point context area
+ *
+ *  @return on output @a *fp_context_ptr will contain the address that
+ *  should be used with @ref _CPU_Context_restore_fp to restore this context.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Context_save_fp(
   void **fp_context_ptr
 );
+/*
+ *  _CPU_Context_restore_fp
+ *
+/**
+ *  @ingroup CPUContext
  *  This routine restores the floating point context passed to it.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param fp_context_ptr (in) is a pointer to a pointer to a floating
+ *  point context area to restore
+ *
+ *  @return on output @a *fp_context_ptr will contain the address that
+ *  should be used with @ref _CPU_Context_save_fp to save this context.
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 void _CPU_Context_restore_fp(
   void **fp_context_ptr
 );
+/*  The following routine swaps the endian format of an unsigned int.
+/**
+ *  @ingroup CPUEndian
+ *  The following routine swaps the endian format of an unsigned int.
  *  It must be static because it is referenced indirectly.
+ *
 …
  *  will be fetched incorrectly.
+ *
+ *  NO_CPU Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
+ *  @param value (in) is the value to be swapped
+ *  @return the value after being endian swapped
+ *
+ *  Port Specific Information:
+ *
+ *  XXX document implementation including references if appropriate
+ */
 static inline unsigned int CPU_swap_u32(
   unsigned int value
 …
+}
+/**
+ *  @ingroup CPUEndian
+ *  This routine swaps a 16 bir quantity.
+ *
+ *  @param value (in) is the value to be swapped
+ *  @return the value after being endian swapped
+ */
 #define CPU_swap_u16( value ) \
   (((value&0xff) << 8) | ((value >> 8)&0xff))

cpukit/score/include/rtems/debug.h

-                      r7ce11b2
+                      rbaff4da
+/*  debug.h
+/**
+ *  @file debug.h
+ *
  *  This include file contains the information pertaining to the debug
  *  support within RTEMS.  It is currently cast in the form of a
  *  Manager since it is externally accessible.
+ *
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *

cpukit/score/include/rtems/score/address.h

-                      r7ce11b2
+                      rbaff4da
+/*  address.h
+/**
+ *  @file address.h
+ *
  *  This include file contains the information required to manipulate
  *  physical addresses.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_ADDRESSES_h
+/**
+ *  @defgroup ScoreAddress Address Handler
+ *
+ *  This group contains functionality which abstracts address manipulation
+ *  in a portable manner.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/apiext.h

-                      r7ce11b2
+                      rbaff4da
+/*  apiext.h
+/**
+ *  @file apiext.h
+ *
  *  This is the API Extensions Handler.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
  */
 #ifndef __API_EXTENSIONS_h
 #define __API_EXTENSIONS_h
+/**
+ *  @defgroup ScoreAPIExtension API Extension Handler
+ *
+ *  This group contains functionality which provides mechanisms for the
+ *  SuperCore to perform API specific actions without there being
+ *  "up-references" from the SuperCore to APIs.  If these references
+ *  were allowed in the implementation, the cohesion would be too high
+ *  and adding an API would be more difficult.  The SuperCore is supposed
+ *  to be largely independent of any API.
+ */
+/**@{*/
 #include <rtems/score/chain.h>
 #include <rtems/score/thread.h>
+/*
+ *  The control structure which defines the points at which an API
+ *  can add an extension to the system initialization thread.
+/**
+ *  This type defines the prototype of the Predriver Hook.
  */
+typedef void (*API_extensions_Predriver_hook)(void);
+typedef void (*API_extensions_Predriver_hook)(void);
+/**
+ *  This type defines the prototype of the Postdriver Hook.
+ */
 typedef void (*API_extensions_Postdriver_hook)(void);
+/**
+ *  This type defines the prototype of the Postswitch Hook.
+ */
 typedef void (*API_extensions_Postswitch_hook)(
                  Thread_Control *
              );
+/**
+ *  The control structure which defines the points at which an API
+ *  can add an extension to the system initialization thread.
+ */
 typedef struct {
+  /** This field allows this structure to be used with the Chain Handler. */
   Chain_Node                      Node;
+  /**
+   * This field is the callout invoked during RTEMS initialization after
+   * RTEMS data structures are initialized before device driver initialization
+   * has occurred.
+   *
+   * @note If this field is NULL, no extension is invoked.
+   */
   API_extensions_Predriver_hook   predriver_hook;
+  /**
+   * This field is the callout invoked during RTEMS initialization after
+   * RTEMS data structures and device driver initialization has occurred
+   * but before multitasking is initiated.
+   *
+   * @note If this field is NULL, no extension is invoked.
+   */
   API_extensions_Postdriver_hook  postdriver_hook;
+  /**
+   * This field is the callout invoked during each context switch
+   * in the context of the heir thread.
+   *
+   * @note If this field is NULL, no extension is invoked.
+   */
   API_extensions_Postswitch_hook  postswitch_hook;
 }  API_extensions_Control;
 /*
+/**
  *  This is the list of API extensions to the system initialization.
  */
 SCORE_EXTERN Chain_Control _API_extensions_List;
+/*
+ *  _API_extensions_Initialization
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine initializes the API extension handler.
+ *
  */
 void _API_extensions_Initialization( void );
 /*
  *  _API_extensions_Add
+/**
+ *  This routine adds an extension to the active set of API extensions.
+ *
+ *  DESCRIPTION:
+ *
+ *  XXX
+ *  @param the_extension (in) is the extension set to add.
  */
 void _API_extensions_Add(
   API_extensions_Control *the_extension
 );
+/*
+ *  _API_extensions_Run_predriver
+ *
+ *  DESCRIPTION:
+ *
+ *  XXX
+/**
+ *  This routine executes all of the predriver callouts.
  */
 void _API_extensions_Run_predriver( void );
+/*
+ *  _API_extensions_Run_postdriver
+ *
+ *  DESCRIPTION:
+ *
+ *  XXX
+/**
+ *  This routine executes all of the postdriver callouts.
  */
 void _API_extensions_Run_postdriver( void );
+/*
+ *  _API_extensions_Run_postswitch
+ *
+ *  DESCRIPTION:
+ *
+ *  XXX
+/**
+ *  This routine executes all of the post context switch callouts.
  */
+ */
+void _API_extensions_Run_postswitch( void );
+void _API_extensions_Run_postswitch( void );
+/**@}*/
 #endif

cpukit/score/include/rtems/score/apimutex.h

-                      r7ce11b2
+                      rbaff4da
+/*  apimutex.h
+/**
+ *  @file apimutex.h
+ *
  *  This include file contains all the constants and structures associated
  *  with the API Mutex Handler.  This handler is used by API level
  *  routines to manage mutual exclusion.
+ *
+ *  COPYRIGHT (c) 1989-2002.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __API_MUTEX_h
+/**
+ *  @defgroup ScoreAPIMutex API Mutex Handler
+ *
+ *  This group contains functionality which provides mutexes to be used
+ *  in the implementation of API functionality.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
 #include <rtems/score/object.h>
+/*
+ *  The following defines the control block used to manage each mutex.
+/**
+ *  The following defines the control block used to manage each API mutex.
+ *  An API Mutex is an aggregration of an Object and a SuperCore Mutex.
  */
 typedef struct {
+  /** This field allows each API Mutex to be a full-fledged RTEMS object.
   Objects_Control       Object;
+  /** This field contains the SuperCore mutex information. */
   CORE_mutex_Control    Mutex;
 }   API_Mutex_Control;
 /*
  *  The following defines the information control block used to manage
+/**
+ *  The following variable is the information control block used to manage
  *  this class of objects.
  */
 SCORE_EXTERN Objects_Information  _API_Mutex_Information;
 /*
  *  _API_Mutex_Initialization
+/**
+ *  This routine performs the initialization necessary for this handler.
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine performs the initialization necessary for this handler.
+ *  @param _maximum_mutexes (in) is the maximum number of API mutexes
+ *         that may exist at any time
  */
 #if defined(RTEMS_MULTIPROCESSING)
 #define _API_Mutex_Initialization( _maximum_mutexes ) \
 …
 #endif
 /*
  *  _API_Mutex_Allocate
+/**
+ *  This routine allocates an API mutex from the inactive set.
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine allocates an api mutex from the inactive set.
+ *  @param _the_mutex (out) will contain the allocated mutex.
  */
 #define _API_Mutex_Allocate( _the_mutex ) \
   do { \
 …
   } while (0)
 /*
  *  _API_Mutex_Lock
+/**
+ *  This routine acquires the specified API mutex.
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine acquires the specified api mutex.
+ *  @param _the_mutex (in) is the mutex to acquire.
  */
 #define _API_Mutex_Lock( _the_mutex ) \
   do { \
 …
   } while (0)
 /*
  *  _API_Mutex_Unlock
+/**
+ *  This routine releases the specified API mutex.
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine releases the specified api mutex.
+ *  @param _the_mutex (in) is the mutex to release.
  */
 …
   } while (0);
+/*XXX when the APIs all use this for allocation and deallocation
+ *XXX protection, then they should be renamed and probably moved
+/**
+ *  This variable points to the API Mutex instance that is used
+ *  to protect all memory allocation and deallocation in RTEMS.
+ *
+ *  @note When the APIs all use this for allocation and deallocation
+ *  protection, then this possibly should be renamed and moved to a
+ *  higher level in the hierarchy.
  */
 SCORE_EXTERN API_Mutex_Control  *_RTEMS_Allocator_Mutex;
+/**
+ *  This macro locks the RTEMS Allocation Mutex.
+ *
+ *  @see _RTEMS_Allocator_Mutex
+ */
 #define _RTEMS_Lock_allocator() \
   _API_Mutex_Lock( _RTEMS_Allocator_Mutex )
+/**
+ *  This macro unlocks the RTEMS Allocation Mutex.
+ *
+ *  @see _RTEMS_Allocator_Mutex
+ */
 #define _RTEMS_Unlock_allocator() \
   _API_Mutex_Unlock( _RTEMS_Allocator_Mutex )
 …
 #endif
+/*!@}*/
 #endif
 /*  end of include file */

cpukit/score/include/rtems/score/bitfield.h

-                      r7ce11b2
+                      rbaff4da
+/*  bitfield.h
+/**
+ *  @file bitfield.h
+ *
  *  This include file contains all bit field manipulation routines.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_BITFIELD_h
+/**
+ *  @defgroup ScoreBitfield Bitfield Handler
+ *
+ *  This group contains functionality that is used to manipulate the
+ *  priority bitfields used to lookup which priority has the highest
+ *  priority ready to execute thread.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
-/*
- *  _Bitfield_Find_first_bit
+ *
- *  DESCRIPTION:
+ *
- *  This routine returns the bit_number of the first bit set
- *  in the specified value.  The correspondence between bit_number
- *  and actual bit position is processor dependent.  The search for
- *  the first bit set may run from most to least significant bit
- *  or vice-versa.
+ *
- *  NOTE:
+ *
- *  This routine is used when the executing thread is removed
- *  from the ready state and, as a result, its performance has a
- *  significant impact on the performance of the executive as a whole.
- */
 #if ( CPU_USE_GENERIC_BITFIELD_DATA == TRUE )
+/**
+ *  This table is used by the generic bitfield routines to perform
+ *  a highly optimized bit scan without the use of special CPU
+ *  instructions.
+ */
 #ifndef SCORE_INIT
 extern const unsigned char __log2table[256];
 …
 #endif
+/**
+ *  This routine returns the @a _bit_number of the first bit set
+ *  in the specified value.  The correspondence between @a _bit_number
+ *  and actual bit position is processor dependent.  The search for
+ *  the first bit set may run from most to least significant bit
+ *  or vice-versa.
+ *
+ *  @param _value (in) is the value to bit scan.
+ *  @param _bit_number (in) is the position of the first bit set.
+ *
+ *  @note This routine is used when the executing thread is removed
+ *  from the ready state and, as a result, its performance has a
+ *  significant impact on the performance of the executive as a whole.
+ *
+ *  @note This routine must be a macro because if a CPU specific version
+ *  is used it will most likely use inline assembly.
+ */
 #if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE )
 #define _Bitfield_Find_first_bit( _value, _bit_number ) \
         _CPU_Bitfield_Find_first_bit( _value, _bit_number )
 #else
-/*
- *  The following must be a macro because if a CPU specific version
- *  is used it will most likely use inline assembly.
- */
 #define _Bitfield_Find_first_bit( _value, _bit_number ) \
   { \
 …
       (_bit_number) = __p[ __value >> 8 ]; \
+  }
 #endif
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/chain.h

-                      r7ce11b2
+                      rbaff4da
+/*  chain.h
+/**
+ *  @file chain.h
+ *
  *  This include file contains all the constants and structures associated
+ *  with the Doubly Linked Chain Handler.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ *  with the Doubly-Linked Chain Handler.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_CHAIN_h
+/**
+ *  @defgroup ScoreChain Chain Handler
+ *
+ *  The Chain Handler contains XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
 #include <rtems/score/address.h>
+/*
+/**
+ *  @typedef Chain_Node
+ *
+ *  This type definition promotes the name for the Chain Node used by
+ *  all RTEMS code.  It is a separate type definition because a forward
+ *  reference is required to define it.
+ */
+typedef struct Chain_Node_struct Chain_Node;
+/**
+ *  @struct Chain_Node_struct
+ *
  *  This is used to manage each element (node) which is placed
  *  on a chain.
+ *
  *  NOTE:  Typically, a more complicated structure will use the
  *         chain package.  The more complicated structure will
  *         include a chain node as the first element in its
  *         control structure.  It will then call the chain package
  *         with a pointer to that node element.  The node pointer
  *         and the higher level structure start at the same address
  *         so the user can cast the pointers back and forth.
+ *  @note Typically, a more complicated structure will use the
+ *        chain package.  The more complicated structure will
+ *        include a chain node as the first element in its
+ *        control structure.  It will then call the chain package
+ *        with a pointer to that node element.  The node pointer
+ *        and the higher level structure start at the same address
+ *        so the user can cast the pointers back and forth.
+ *
  */
-typedef struct Chain_Node_struct Chain_Node;
 struct Chain_Node_struct {
+  /** This points to the node after to this one on this chain. */
   Chain_Node *next;
+  /** This points to the node immediate prior to this one on this chain. */
   Chain_Node *previous;
 };
+/*
+ *  This is used to manage a chain.  A chain consists of a doubly
+ *  linked list of zero or more nodes.
+/**
+ *  @struct Chain_Control
+ *
+ *  NOTE:  This implementation does not require special checks for
+ *         manipulating the first and last elements on the chain.
+ *         To accomplish this the chain control structure is
+ *         treated as two overlapping chain nodes.  The permanent
+ *         head of the chain overlays a node structure on the
+ *         first and permanent_null fields.  The permanent tail
+ *         of the chain overlays a node structure on the
+ *         permanent_null and last elements of the structure.
+ * This is used to manage a chain.  A chain consists of a doubly
+ * linked list of zero or more nodes.
+ *
+ * @note This implementation does not require special checks for
+ *   manipulating the first and last elements on the chain.
+ *   To accomplish this the @a Chain_Control structure is
+ *   treated as two overlapping @ref Chain_Node structures.
+ *   The permanent head of the chain overlays a node structure on the
+ *   @a first and @a permanent_null fields.  The permanent tail
+ *   of the chain overlays a node structure on the
+ *   @a permanent_null and @a last elements of the structure.
+ *
  */
 typedef struct {
+  /** This points to the first node on this chain. */
   Chain_Node *first;
+  /** This field is always 0. */
   Chain_Node *permanent_null;
+  /** This points to the last node on this chain. */
   Chain_Node *last;
 } Chain_Control;
 /*
  *  _Chain_Initialize
+/**
+ *  @brief Initialize a Chain Header
+ *
+ *  DESCRIPTION:
+ *  This routine initializes @a the_chain structure to manage the
+ *  contiguous array of @a number_nodes nodes which starts at
+ *  @a starting_address.  Each node is of @a node_size bytes.
+ *
+ *  This routine initializes the_chain structure to manage the
+ *  contiguous array of number_nodes nodes which starts at
+ *  starting_address.  Each node is of node_size bytes.
+ *
+ *  @param the_chain (in) specifies the chain to initialize
+ *  @param starting_address (in) is the starting address of the array
+ *         of elements
+ *  @param number_nodes (in) is the numebr of nodes that will be in the chain
+ *  @param node_size (in) is the size of each node
  */
 void _Chain_Initialize(
   Chain_Control *the_chain,
   void          *starting_address,
   uint32_t       number_nodes,
   uint32_t       node_size
+  unsigned32     number_nodes,
+  unsigned32     node_size
 );
+/*
+ *  _Chain_Get_first_unprotected
+#ifndef RTEMS_INLINES
+/**
+ *  @brief Get the first node (do not disable interrupts)
+ *
+ *  This method attempts to obtain the first node from \a the_chain.
+ *
+ *  @param the_chain (in) points to the chain to operate upon
+ *  @return If successful, a chain node is returned.  Otherwise, NULL
+ *  is returned.
  */
-#ifndef RTEMS_INLINES
 Chain_Node *_Chain_Get_first_unprotected(
   Chain_Control *the_chain
 …
 #endif
 /*
  *  _Chain_Extract
+/**
+ *  @brief Extract the specified node from a chain
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine extracts the_node from the chain on which it resides.
+ *  This routine extracts \a the_node from the chain on which it resides.
  *  It disables interrupts to insure the atomicity of the
  *  extract operation.
+ *
+ *  @arg the_node specifies the node to extract
  */
 void _Chain_Extract(
   Chain_Node *the_node
 );
 /*
  *  _Chain_Get
+/**
+ *  @brief Obtain the first node on a chain
+ *
+ *  DESCRIPTION:
+ *  This function removes the first node from \a the_chain and returns
+ *  a pointer to that node.  If \a the_chain is empty, then NULL is returned.
+ *
+ *  This function removes the first node from the_chain and returns
+ *  a pointer to that node.  If the_chain is empty, then NULL is returned.
+ *  It disables interrupts to insure the atomicity of the
+ *  @note It disables interrupts to insure the atomicity of the
  *  get operation.
+ *
  */
 Chain_Node *_Chain_Get(
   Chain_Control *the_chain
 );
 /*
  *  _Chain_Insert
+/**
+ *  @brief Insert a node on a chain
+ *
+ *  DESCRIPTION:
+ *  This routine inserts \a the_node on a chain immediately following
+ *  \a after_node.
+ *
+ *  This routine inserts the_node on a chain immediately following
+ *  after_node.  It disables interrupts to insure the atomicity
+ *  @note It disables interrupts to insure the atomicity
  *  of the extract operation.
+ *
  */
 void _Chain_Insert(
   Chain_Node *after_node,
 …
 );
 /*
  *  _Chain_Append
+/**
+ *  @brief Append a node on the end of a chain
+ *
  *  DESCRIPTION:
+ *  This routine appends \a the_node onto the end of \a the_chain.
+ *
+ *  This routine appends the_node onto the end of the_chain.
+ *  It disables interrupts to insure the atomicity of the
+ *  @note It disables interrupts to insure the atomicity of the
  *  append operation.
+ *
  */
 void _Chain_Append(
   Chain_Control *the_chain,
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/context.h

-                      r7ce11b2
+                      rbaff4da
+/*  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).
+ *
 …
 #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" {
 …
 #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
+/**
+ *  @ingroup ScoreContext
+ *  This routine saves the current context into the @a _executing
+ *  context record and restores the context specified by @a _heir.
+ *
+ *  DESCRIPTION:
+ *
+ *  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
+/**
+ *  @ingroup ScoreContext
+ *  This routine restores the floating point context contained
+ *  in the @a _fp area.  It is assumed that the current
+ *  floating point context has been saved by a previous invocation
+ *  of @a _Context_Save_fp.
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine restores the floating point context contained
+ *  in the FP_CONTEXT area.  It is assumed that the current
+ *  floating point context has been saved by a previous invocation
+ *  of 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
+/**
+ *  @ingroup ScoreContext
+ *  This routine saves the current floating point context
+ *  in the @a _fp area.
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine saves the current floating point context
+ *  in the FP_CONTEXT area.
+ *  @param _fp (in) points to the floating point context area to restore.
  */
 #define _Context_Save_fp( _fp ) \
    _CPU_Context_save_fp( _fp )
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/copyrt.h

-                      r7ce11b2
+                      rbaff4da
+/*  copyrt.h
+/**
+ *  @file copyrt.h
+ *
  *  This include file contains the copyright notice for RTEMS
  *  which is included in every binary copy of the executive.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #endif
+/**
+ *  This is the copyright string for RTEMS.
+ */
 #ifdef SCORE_INIT
 const char _Copyright_Notice[] =
 "COPYRIGHT (c) 1989-1999.\n\
+"COPYRIGHT (c) 1989-2004.\n\
 On-Line Applications Research Corporation (OAR).\n";
 #else
 extern const char _Copyright_Notice[];
 #endif

cpukit/score/include/rtems/score/coremsg.h

-                      r7ce11b2
+                      rbaff4da
+/*  coremsg.h
+/**
+ *  @file coremsg.h
+ *
  *  This include file contains all the constants and structures associated
  *  with the Message queue Handler.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __RTEMS_CORE_MESSAGE_QUEUE_h
 #define __RTEMS_CORE_MESSAGE_QUEUE_h
+/**
+ *  @defgroup ScoreMessageQueue Message Queue Handler
+ *
+ *  This group contains functionality which provides the foundation
+ *  Message Queue services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
 #ifdef __cplusplus
 …
 #include <rtems/score/watchdog.h>
 /*
+/**
  *  The following type defines the callout which the API provides
  *  to support global/multiprocessor operations on message_queues.
  */
 typedef void ( *CORE_message_queue_API_mp_support_callout )(
                  Thread_Control *,
 …
              );
 /*
+/**
  *  The following defines the data types needed to manipulate
  *  the contents of message buffers.
+ *
  *  NOTE:  The buffer field is normally longer than a single uint32_t  .
+ *  @note  The buffer field is normally longer than a single uint32_t
  *         but since messages are variable length we just make a ptr to 1.
  */
 typedef struct {
+    uint32_t    size;
+    uint32_t    buffer[1];
+  /** This field is the size of this message. */
+  uint32_t    size;
+  /** This field contains the actual message. */
+  uint32_t    buffer[1];
 } CORE_message_queue_Buffer;
 /*
+/**
  *  The following records define the organization of a message
  *  buffer.
  */
 typedef struct {
+  /** This element allows this structure to be placed on chains. */
   Chain_Node                 Node;
+  /** This field is the priority of this message. */
   int                        priority;
+  /** This field points to the contents of the message. */
   CORE_message_queue_Buffer  Contents;
 }   CORE_message_queue_Buffer_control;
+/*
+ *  Blocking disciplines for a message_queue.
+ */
+/**
+ *  Blocking disciplines for a message queue.
+ */
 typedef enum {
+  /** This value indicates that pending messages are in FIFO order. */
   CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
+  /** This value indicates that pending messages are in priority order. */
   CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
 }   CORE_message_queue_Disciplines;
+/*
+/**
+ *  This is the priority constant used when appending messages onto
+ *  a message queue.
+ */
+#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
+/**
+ *  This is the priority constant used when prepending messages onto
+ *  a message queue.
+ */
+#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
+/**
  *  The following enumerated type details the modes in which a message
  *  may be submitted to a message queue.  The message may be posted
  *  in a send or urgent fashion.
+ *
  *  NOTE:  All other values are message priorities.  Numerically smaller
+ *  @note  All other values are message priorities.  Numerically smaller
  *         priorities indicate higher priority messages.
+ *
+ */
+#define  CORE_MESSAGE_QUEUE_SEND_REQUEST   INT_MAX
+#define  CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
+ */
 typedef int CORE_message_queue_Submit_types;
 /*
+/**
  *  Core Message queue handler return statuses.
  */
 typedef enum {
+  /** This value indicates the operation completed sucessfully. */
   CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
+  /** This value indicates that the message was too large for this queue. */
   CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
+  /** This value indicates that there are too many messages pending. */
   CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
+  /** This value indicates that a receive was unsuccessful. */
   CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
+  /** This value indicates that a blocking send was unsuccessful. */
   CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
+  /** This value indicates that the message queue being blocked upon
+   *  was deleted while the thread was waiting.
+   */
   CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
+  /** This value indicates that the thread had to timeout while waiting
+   *  to receive a message because one did not become available.
+   */
   CORE_MESSAGE_QUEUE_STATUS_TIMEOUT,
+  /** This value indicates that a blocking receive was unsuccessful. */
   CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
 }   CORE_message_queue_Status;
 /*
+/**
  *  The following defines the control block used to manage the
  *  attributes of each message queue.
  */
 typedef struct {
+  /** This field specifies the order in which blocking tasks will be ordered. */
   CORE_message_queue_Disciplines  discipline;
 }   CORE_message_queue_Attributes;
 /*
+/**
  *  The following defines the type for a Notification handler.  A notification
  *  handler is invoked when the message queue makes a 0->1 transition on
  *  pending messages.
  */
 typedef void (*CORE_message_queue_Notify_Handler)( void * );
 /*
+/**
  *  The following defines the control block used to manage each
  *  counting message_queue.
  */
 typedef struct {
+  /** This field is the Waiting Queue used to manage the set of tasks
+   *  which are blocked waiting to receive a message from this queue.
+   */
   Thread_queue_Control               Wait_queue;
+  /** This element is the set of attributes which define this instance's
+   *  behavior.
+   */
   CORE_message_queue_Attributes      Attributes;
+  /** This element is maximum number of messages which may be pending
+   *  at any given time.
+   */
   uint32_t                           maximum_pending_messages;
+  /** This element is the number of messages which are currently pending.
+   */
   uint32_t                           number_of_pending_messages;
+  /** This is the size in bytes of the largest message which may be
+   *  sent via this queue.
+   */
   uint32_t                           maximum_message_size;
+  /** This chain is the set of pending messages.  It may be ordered by
+   *  message priority or in FIFO order.
+   */
   Chain_Control                      Pending_messages;
+  /** This is the address of the memory allocated for message buffers.
+   *  It is allocated are part of message queue initialization and freed
+   *  as part of destroying it.
+   */
   CORE_message_queue_Buffer         *message_buffers;
+  /** This is the routine invoked when the message queue transitions
+   *  from zero (0) messages pending to one (1) message pending.
+   */
   CORE_message_queue_Notify_Handler  notify_handler;
+  /** This field is the argument passed to the @ref notify_argument. */
   void                              *notify_argument;
+  /** This chain is the set of inactive messages.  A message is inactive
+   *  when it does not contain a pending message.
+   */
   Chain_Control                      Inactive_messages;
 }   CORE_message_queue_Control;
+/*
+ *  _CORE_message_queue_Initialize
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine initializes the message_queue based on the parameters passed.
+ */
+ *
+ *  @param the_message_queue (in) points to the message queue to initialize
+ *  @param the_message_queue_attributes (in) points to the attributes that
+ *         will be used with this message queue instance
+ *  @param maximum_pending_messages (in) is the maximum number of messages
+ *         that will be allowed to pend at any given time
+ *  @param maximum_message_size (in) is the size of largest message that
+ *         may be sent to this message queue instance
+ *
+ *  @return TRUE if the message queue can be initialized.  In general,
+ *         FALSE will only be returned if memory for the pending
+ *         messages cannot be allocated.
+ */
 boolean _CORE_message_queue_Initialize(
   CORE_message_queue_Control    *the_message_queue,
 …
 );
+/*
+ *  _CORE_message_queue_Close
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function closes a message by returning all allocated space and
  *  flushing the message_queue's task wait queue.
+ */
+ *
+ *  @param the_message_queue (in) points to the message queue to close
+ *  @param remote_extract_callout (in) is the routine to call for each thread
+ *         that is extracted from the set of waiting threads
+ *  @param status (in) is the status that each waiting thread will return
+ *         from it's blocking service
+ */
 void _CORE_message_queue_Close(
   CORE_message_queue_Control *the_message_queue,
 …
 );
+/*
+ *  _CORE_message_queue_Flush
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function flushes the message_queue's pending message queue.  The
  *  number of messages flushed from the queue is returned.
+ *
+ */
+ *  @param the_message_queue (in) points to the message queue to flush
+ *  @return the number of message pending messages flushed
+ */
 uint32_t   _CORE_message_queue_Flush(
   CORE_message_queue_Control *the_message_queue
 );
+/*
+ *  _CORE_message_queue_Flush_support
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine flushes all outstanding messages and returns
  *  them to the inactive message chain.
+ */
+ *
+ *  @param the_message_queue (in) points to the message queue to flush
+ *  @return the number of message pending messages flushed
+ */
 uint32_t   _CORE_message_queue_Flush_support(
   CORE_message_queue_Control *the_message_queue
 );
+/*
+ *  _CORE_message_queue_Flush_waiting_threads
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function flushes the threads which are blocked on this
  *  message_queue's pending message queue.  They are unblocked whether
  *  blocked sending or receiving.
+ */
+ *
+ *  @param the_message_queue (in) points to the message queue to flush
+ */
 void _CORE_message_queue_Flush_waiting_threads(
   CORE_message_queue_Control *the_message_queue
 );
+/*
+ *  _CORE_message_queue_Broadcast
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function sends a message for every thread waiting on the queue and
  *  returns the number of threads made ready by the message.
+ *
+ */
+ *  @param the_message_queue (in) points to the message queue
+ *  @param buffer (in) is the starting address of the message to broadcast
+ *  @param size (in) is the size of the message being broadcast
+ *  @param id (in) is the RTEMS object Id associated with this message queue.
+ *         It is used when unblocking a remote thread.
+ *  @param api_message_queue_mp_support (in) is the routine to invoke if
+ *         a thread that is unblocked is actually a remote thread.
+ *  @param count (out) points to the variable that will contain the
+ *         number of tasks that are sent this message
+ *  @return @a *count will contain the number of messages sent
+ *  @return indication of the successful completion or reason for failure
+ */
 CORE_message_queue_Status _CORE_message_queue_Broadcast(
   CORE_message_queue_Control                *the_message_queue,
 …
 );
+/*
+ *  _CORE_message_queue_Submit
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine implements the send and urgent message functions. It
  *  processes a message that is to be submitted to the designated
 …
  *  at the front of the queue.
+ *
+ */
+ *  @param the_message_queue (in) points to the message queue
+ *  @param buffer (in) is the starting address of the message to send
+ *  @param size (in) is the size of the message being send
+ *  @param id (in) is the RTEMS object Id associated with this message queue.
+ *         It is used when unblocking a remote thread.
+ *  @param api_message_queue_mp_support (in) is the routine to invoke if
+ *         a thread that is unblocked is actually a remote thread.
+ *  @param submit_type (in) determines whether the message is prepended,
+ *         appended, or enqueued in priority order.
+ *  @param wait (in) indicates whether the calling thread is willing to block
+ *         if the message queue is full.
+ *  @param timeout (in) is the maximum number of clock ticks that the calling
+ *         thread is willing to block if the message queue is full.
+ *  @return indication of the successful completion or reason for failure
+ */
 CORE_message_queue_Status _CORE_message_queue_Submit(
   CORE_message_queue_Control                *the_message_queue,
 …
 );
+/*
+ *  _CORE_message_queue_Seize
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This kernel routine dequeues a message, copies the message buffer to
  *  a given destination buffer, and frees the message buffer to the
 …
  *  otherwise an error will be given to the thread if no messages are available.
+ *
+ *  NOTE: Returns message priority via return are in TCB.
+ */
+ *  @param the_message_queue (in) points to the message queue
+ *  @param id (in) is the RTEMS object Id associated with this message queue.
+ *         It is used when unblocking a remote thread.
+ *  @param buffer (in) is the starting address of the message buffer to
+ *         to be filled in with a message
+ *  @param size (in) is the size of the @a buffer and indicates the maximum
+ *         size message that the caller can receive.
+ *  @param wait (in) indicates whether the calling thread is willing to block
+ *         if the message queue is empty.
+ *  @param timeout (in) is the maximum number of clock ticks that the calling
+ *         thread is willing to block if the message queue is empty.
+ *
+ *  @return indication of the successful completion or reason for failure
+ *  @note Returns message priority via return are in TCB.
+ */
 void _CORE_message_queue_Seize(
   CORE_message_queue_Control      *the_message_queue,
 …
 );
+/*
+ *  _CORE_message_queue_Insert_message
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This kernel routine inserts the specified message into the
  *  message queue.  It is assumed that the message has been filled
  *  in before this routine is called.
+ */
+ *
+ *  @param the_message_queue (in) points to the message queue
+ *  @param the_message (in) is the message to enqueue
+ *  @param submit_type (in) determines whether the message is prepended,
+ *         appended, or enqueued in priority order.
+ */
 void _CORE_message_queue_Insert_message(
   CORE_message_queue_Control        *the_message_queue,
 …
 #endif
+/**@}*/
 #endif
 /*  end of include file */

cpukit/score/include/rtems/score/coremutex.h

-                      r7ce11b2
+                      rbaff4da
+/*  mutex.h
+/**
+ *  @file coremutex.h
+ *
  *  This include file contains all the constants and structures associated
 …
  *  Dijkstra binary semaphore used to provide synchronization and mutual
  *  exclusion capabilities.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __RTEMS_CORE_MUTEX_h
 #define __RTEMS_CORE_MUTEX_h
+/**
+ *  @defgroup ScoreMutex Mutex Handler
+ *
+ *  This group contains functionality which provides the foundation
+ *  Mutex services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
 #ifdef __cplusplus
 …
 #include <rtems/score/sysstate.h>
 /*
+/**
  *  The following type defines the callout which the API provides
  *  to support global/multiprocessor operations on mutexes.
  */
 typedef void ( *CORE_mutex_API_mp_support_callout )(
                  Thread_Control *,
 …
              );
 /*
+/**
  *  Blocking disciplines for a mutex.
  */
 typedef enum {
+  /** This specifies that threads will wait for the mutex in FIFO order. */
   CORE_MUTEX_DISCIPLINES_FIFO,
+  /** This specifies that threads will wait for the mutex in priority order.  */
   CORE_MUTEX_DISCIPLINES_PRIORITY,
+  /** This specifies that threads will wait for the mutex in priority order.
+   *  Additionally, the Priority Inheritance Protocol will be in effect.
+   */
   CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT,
+  /** This specifies that threads will wait for the mutex in priority order.
+   *  Additionally, the Priority Ceiling Protocol will be in effect.
+   */
   CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING
 }   CORE_mutex_Disciplines;
 /*
+/**
  *  Mutex handler return statuses.
  */
 typedef enum {
+  /** This status indicates that the operation completed successfully. */
   CORE_MUTEX_STATUS_SUCCESSFUL,
+  /** This status indicates that the calling task did not want to block
+   *  and the operation was unable to complete immediately because the
+   *  resource was unavailable.
+   */
   CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
+  /** This status indicates that an attempt was made to relock a mutex
+   *  for which nesting is not configured.
+   */
   CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
+  /** This status indicates that an attempt was made to release a mutex
+   *  by a thread other than the thread which locked it.
+   */
   CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
+  /** This status indicates that the thread was blocked waiting for an
+   *  operation to complete and the mutex was deleted.
+   */
   CORE_MUTEX_WAS_DELETED,
+  /** This status indicates that the calling task was willing to block
+   *  but the operation was unable to complete within the time allotted
+   *  because the resource never became available.
+   */
   CORE_MUTEX_TIMEOUT,
+  /** This status indicates that a thread of logically greater importance
+   *  than the ceiling priority attempted to lock this mutex.
+   */
   CORE_MUTEX_STATUS_CEILING_VIOLATED
 }   CORE_mutex_Status;
 /*
+/**
  *  Mutex lock nesting behavior
+ *
  *  CORE_MUTEX_NESTING_ACQUIRES:
+ *  + CORE_MUTEX_NESTING_ACQUIRES:
  *    This sequence has no blocking or errors:
+ *         lock(m)
+ *         lock(m)
+ *         unlock(m)
+ *         unlock(m)
+ *
+ *  CORE_MUTEX_NESTING_IS_ERROR
+ *
+ *         + lock(m)
+ *         + lock(m)
+ *         + unlock(m)
+ *         + unlock(m)
+ *
+ *  + CORE_MUTEX_NESTING_IS_ERROR
  *    This sequence returns an error at the indicated point:
+ *        lock(m)
+ *        lock(m)   - already locked error
+ *        unlock(m)
+ *
+ *  CORE_MUTEX_NESTING_BLOCKS
+ *
+ *        + lock(m)
+ *        + lock(m)   - already locked error
+ *        + unlock(m)
+ *
+ *  + CORE_MUTEX_NESTING_BLOCKS
  *    This sequence performs as indicated:
+ *        lock(m)
+ *        lock(m)   - deadlocks or timeouts
+ *        unlock(m) - releases
+ */
+ *        + lock(m)
+ *        + lock(m)   - deadlocks or timeouts
+ *        + unlock(m) - releases
+ */
 typedef enum {
   CORE_MUTEX_NESTING_ACQUIRES,
 …
 }  CORE_mutex_Nesting_behaviors;
+/*
+ *  Locked and unlocked values
+ */
+/**
+ *  This is the value of a mutex when it is unlocked.
+ */
 #define CORE_MUTEX_UNLOCKED 1
+/**
+ *  This is the value of a mutex when it is locked.
+ */
 #define CORE_MUTEX_LOCKED   0
 /*
+/**
  *  The following defines the control block used to manage the
  *  attributes of each mutex.
  */
 typedef struct {
+  /** This field determines what the behavior of this mutex instance will
+   *  be when attempting to acquire the mutex when it is already locked.
+   */
   CORE_mutex_Nesting_behaviors lock_nesting_behavior;
+  /** When this field is TRUE, then only the thread that locked the mutex
+   *  is allowed to unlock it.
+   */
   boolean                      only_owner_release;
+  /** This field indicates whether threads waiting on the mutex block in
+   *  FIFO or priority order.
+   */
   CORE_mutex_Disciplines       discipline;
+  /** This field contains the ceiling priority to be used if that protocol
+   *  is selected.
+   */
   Priority_Control             priority_ceiling;
 }   CORE_mutex_Attributes;
 /*
+/**
  *  The following defines the control block used to manage each mutex.
  */
 typedef struct {
+  /** This field is the Waiting Queue used to manage the set of tasks
+   *  which are blocked waiting to lock the mutex.
+   */
   Thread_queue_Control    Wait_queue;
+  /** This element is the set of attributes which define this instance's
+   *  behavior.
+   */
   CORE_mutex_Attributes   Attributes;
+  /** This element contains the current state of the mutex.
+   */
   uint32_t                lock;
+  /** This element contains the number of times the mutex has been acquired
+   *  nested.  This must be zero (0) before the mutex is actually unlocked.
+   */
   uint32_t                nest_count;
+  /** This is the number of waiting threads. */
   uint32_t                blocked_count;
+  /** This element points to the thread which is currently holding this mutex.
+   *  The holder is the last thread to successfully lock the mutex and which
+   *  has not unlocked it.  If the thread is not locked, there is no holder.
+   */
   Thread_Control         *holder;
+  /** This element contains the object Id of the holding thread.  */
   Objects_Id              holder_id;
 }   CORE_mutex_Control;
+/*
+ *  _CORE_mutex_Initialize
+ *
+ *  DESCRIPTION:
+/**
+ *
  *  This routine initializes the mutex based on the parameters passed.
+ */
+ *
+ *  @param the_mutex (in) is the mutex to initalize
+ *  @param the_mutex_attributes (in) is the attributes associated with this
+ *         mutex instance
+ *  @param initial_lock (in) is the initial value of the mutex
+ */
 void _CORE_mutex_Initialize(
   CORE_mutex_Control           *the_mutex,
 …
 );
+/*
+ *  _CORE_mutex_Seize
+ *
+ *  DESCRIPTION:
+ *
+#ifndef __RTEMS_APPLICATION__
+/**
  *  This routine attempts to receive a unit from the_mutex.
  *  If a unit is available or if the wait flag is FALSE, then the routine
 …
  *  available.
+ *
+ *  NOTE:  For performance reasons, this routine is implemented as
+ *  @param the_mutex (in) is the mutex to attempt to lock
+ *  @param level_p (in) is the interrupt level holder
+ *
+ *  @note  For performance reasons, this routine is implemented as
  *         a macro that uses two support routines.
  */
-#ifndef __RTEMS_APPLICATION__
 RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
   CORE_mutex_Control  *the_mutex,
 …
 );
+/**
+ *  This routine performs the blocking portion of a mutex obtain.
+ *  It is an actual subroutine and is not implemented as something
+ *  that may be inlined.
+ *
+ *  @param the_mutex (in) is the mutex to attempt to lock
+ *  @param timeout (in) is the maximum number of ticks to block
+ */
 void _CORE_mutex_Seize_interrupt_blocking(
   CORE_mutex_Control  *the_mutex,
 …
 );
+/**
+ *  This routine attempts to obtain the mutex.  If the mutex is available,
+ *  then it will return immediately.  Otherwise, it will invoke the
+ *  support routine @a _Core_mutex_Seize_interrupt_blocking.
+ *
+ *  @param _the_mutex (in) is the mutex to attempt to lock
+ *  @param _id (in) is the Id of the owning API level Semaphore object
+ *  @param _wait (in) is TRUE if the thread is willing to wait
+ *  @param _timeout (in) is the maximum number of ticks to block
+ *  @param _level (in) is a temporary variable used to contain the ISR
+ *         disable level cookie
+ */
 #define _CORE_mutex_Seize( \
   _the_mutex, _id, _wait, _timeout, _level ) \
   do { \
         if ( _Thread_Dispatch_disable_level \
                 && (_wait) \
                 && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
            ) { \
                 _Internal_error_Occurred( \
                                                         INTERNAL_ERROR_CORE, \
                                                         FALSE, \
 /* called from wrong environment */); \
         } \
+    if ( _Thread_Dispatch_disable_level \
+        && (_wait) \
+        && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
+       ) { \
+        _Internal_error_Occurred( \
+           INTERNAL_ERROR_CORE, \
+           FALSE, \
+/* called from wrong environment */); \
+    } \
     if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
       if ( !_wait ) { \
 …
   } while (0)
+/*
+ *  _CORE_mutex_Surrender
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine frees a unit to the mutex.  If a task was blocked waiting for
  *  a unit from this mutex, then that task will be readied and the unit
  *  given to that task.  Otherwise, the unit will be returned to the mutex.
+ */
+ *
+ *  @param the_mutex (in) is the mutex to surrender
+ *  @param id (in) is the id of the RTEMS Object associated with this mutex
+ *  @param api_mutex_mp_support (in) is the routine that will be called when
+ *         unblocking a remote mutex
+ *
+ *  @return an indication of whether the routine succeeded or failed
+ */
 CORE_mutex_Status _CORE_mutex_Surrender(
   CORE_mutex_Control                *the_mutex,
 …
 );
+/*
+ *  _CORE_mutex_Flush
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine assists in the deletion of a mutex by flushing the associated
  *  wait queue.
+ */
+ *
+ *  @param the_mutex (in) is the mutex to flush
+ *  @param remote_extract_callout (in) is the routine to invoke when a remote
+ *         thread is extracted
+ *  @param status (in) is the status value which each unblocked thread will
+ *         return to its caller.
+ */
 void _CORE_mutex_Flush(
   CORE_mutex_Control         *the_mutex,
 …
 #endif
+/**@}*/
 #endif
 /*  end of include file */

cpukit/score/include/rtems/score/coresem.h

-                      r7ce11b2
+                      rbaff4da
+/*  core_sem.h
+/**
+ *  @file coresem.h
+ *
  *  This include file contains all the constants and structures associated
 …
  *  standard Dijkstra binary semaphore used to provide synchronization
  *  and mutual exclusion capabilities.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_CORE_COUNTING_SEMAPHORE_h
+/**
+ *  @defgroup ScoreSemaphore Semaphore Handler
+ *
+ *  This group contains functionality which provides the foundation
+ *  Semaphore services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
 #include <rtems/score/watchdog.h>
 /*
+/**
  *  The following type defines the callout which the API provides
  *  to support global/multiprocessor operations on semaphores.
  */
 typedef void ( *CORE_semaphore_API_mp_support_callout )(
                  Thread_Control *,
 …
              );
 /*
+/**
  *  Blocking disciplines for a semaphore.
  */
 typedef enum {
+  /** This specifies that threads will wait for the semaphore in FIFO order. */
   CORE_SEMAPHORE_DISCIPLINES_FIFO,
+  /** This specifies that threads will wait for the semaphore in
+   *  priority order.
+   */
   CORE_SEMAPHORE_DISCIPLINES_PRIORITY
 }   CORE_semaphore_Disciplines;
 /*
+/**
  *  Core Semaphore handler return statuses.
  */
 typedef enum {
+  /** This status indicates that the operation completed successfully. */
   CORE_SEMAPHORE_STATUS_SUCCESSFUL,
+  /** This status indicates that the calling task did not want to block
+   *  and the operation was unable to complete immediately because the
+   *  resource was unavailable.
+   */
   CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT,
+  /** This status indicates that the thread was blocked waiting for an
+   *  operation to complete and the semaphore was deleted.
+   */
   CORE_SEMAPHORE_WAS_DELETED,
+  /** This status indicates that the calling task was willing to block
+   *  but the operation was unable to complete within the time allotted
+   *  because the resource never became available.
+   */
   CORE_SEMAPHORE_TIMEOUT,
+  /** This status indicates that an attempt was made to unlock the semaphore
+   *  and this would have made its count greater than that allowed.
   CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED
 }   CORE_semaphore_Status;
 /*
+/**
  *  The following defines the control block used to manage the
  *  attributes of each semaphore.
  */
 typedef struct {
+  /** This element indicates the maximum count this semaphore may have. */
   uint32_t                    maximum_count;
+  /** This field indicates whether threads waiting on the semaphore block in
+   *  FIFO or priority order.
+   */
   CORE_semaphore_Disciplines  discipline;
 }   CORE_semaphore_Attributes;
 /*
+/**
  *  The following defines the control block used to manage each
  *  counting semaphore.
  */
 typedef struct {
+  /** This field is the Waiting Queue used to manage the set of tasks
+   *  which are blocked waiting to obtain the semaphore.
+   */
   Thread_queue_Control        Wait_queue;
+  /** This element is the set of attributes which define this instance's
+   *  behavior.
+   */
   CORE_semaphore_Attributes   Attributes;
+  /** This element contains the current count of this semaphore. */
   uint32_t                    count;
 }   CORE_semaphore_Control;
 /*
  *  _CORE_semaphore_Initialize
+/**
+ *  This routine initializes the semaphore based on the parameters passed.
+ *
  *  DESCRIPTION:
+ *
  *  This routine initializes the semaphore based on the parameters passed.
+ *  @param the_semaphore (in) is the semaphore to initialize
+ *  @param the_semaphore_attributes (in) define the behavior of this instance
+ *  @param initial_value (in) is the initial count of the semaphore
  */
 void _CORE_semaphore_Initialize(
   CORE_semaphore_Control       *the_semaphore,
 …
 );
+/*
+ *  _CORE_semaphore_Seize
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine attempts to receive a unit from the_semaphore.
  *  If a unit is available or if the wait flag is FALSE, then the routine
  *  returns.  Otherwise, the calling task is blocked until a unit becomes
  *  available.
+ *
+ *  @param the_semaphore (in) is the semaphore to seize
+ *  @param id (in) is the Id of the API level Semaphore object associated
+ *         with this instance of a SuperCore Semaphore
+ *  @param wait (in) is TRUE if the calling thread is willing to wait
+ *  @param timeout (in) is the number of ticks the calling thread is willing
+ *         to wait if @a wait is TRUE.
  */
 void _CORE_semaphore_Seize(
   CORE_semaphore_Control  *the_semaphore,
 …
 );
+/*
+ *  _CORE_semaphore_Surrender
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine frees a unit to the semaphore.  If a task was blocked waiting
  *  for a unit from this semaphore, then that task will be readied and the unit
  *  given to that task.  Otherwise, the unit will be returned to the semaphore.
+ *
+ *  @param the_semaphore (in) is the semaphore to surrender
+ *  @param id (in) is the Id of the API level Semaphore object associated
+ *         with this instance of a SuperCore Semaphore
+ *  @param api_semaphore_mp_support (in) is the routine to invoke if the
+ *         thread unblocked is remote
+ *
+ *  @return an indication of whether the routine succeeded or failed
  */
 CORE_semaphore_Status _CORE_semaphore_Surrender(
   CORE_semaphore_Control                *the_semaphore,
 …
 );
+/*
+ *  _CORE_semaphore_Flush
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine assists in the deletion of a semaphore by flushing the
  *  associated wait queue.
+ *
+ *  @param the_semaphore (in) is the semaphore to flush
+ *  @param remote_extract_callout (in) is the routine to invoke if the
+ *         thread unblocked is remote
+ *  @param status (in) is the status to be returned to the unblocked thread
  */
 void _CORE_semaphore_Flush(
   CORE_semaphore_Control         *the_semaphore,
 …
 #endif
+/**@}*/
 #endif
 /*  end of include file */

cpukit/score/include/rtems/score/heap.h

-                      r7ce11b2
+                      rbaff4da
+/*  heap.h
+/**
+ *  @file heap.h
+ *
  *  This include file contains the information pertaining to the Heap
 …
  *  and unallocated blocks is contained in the heap space.  A heap header
  *  contains control information for the heap.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_HEAP_h
+/**
+ *  @defgroup ScoreHeap Heap Handler
+ *
+ *  This group contains functionality which provides the foundation
+ *  Heap services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 /*
+/**
  *  Status codes for heap_extend
  */
 typedef enum {
   HEAP_EXTEND_SUCCESSFUL,
 …
 }  Heap_Extend_status;
 /*
+/**
  *  Status codes for _Heap_Get_information
  */
 typedef enum {
     HEAP_GET_INFORMATION_SUCCESSFUL = 0,
 …
 }  Heap_Get_information_status;
 /*
+/**
  *  Information block returned by _Heap_Get_information
  */
 typedef struct {
+  /** This field is the number of free blocks in this heap. */
   uint32_t     free_blocks;
+  /** This field is the amount of free memory in this heap. */
   uint32_t     free_size;
+  /** This field is the number of used blocks in this heap. */
   uint32_t     used_blocks;
+  /** This field is the amount of used memory in this heap. */
   uint32_t     used_size;
 } Heap_Information_block;
+/*
+ *  Constants used in the size/used field of each heap block to
+ *  indicate when a block is free or in use.
+ */
+#define HEAP_BLOCK_USED    1           /* indicates block is in use */
+#define HEAP_BLOCK_FREE    0           /* indicates block is free */
+/*
+/**
+ *  This constant is used in the size/used field of each heap block to
+ *  indicate when a block is in use.
+ */
+#define HEAP_BLOCK_USED    1
+/**
+ *  This constant is used in the size/used field of each heap block to
+ *  indicate when a block is free.
+ */
+#define HEAP_BLOCK_FREE    0
+/**
  *  The size/used field value for the dummy front and back flags.
  */
 #define HEAP_DUMMY_FLAG    (0 + HEAP_BLOCK_USED)
 …
  *  heap data structures which impact the management of a heap.
+ *
  * NOTE:   Because free block overhead is greater than used block
+ *  NOTE:  Because free block overhead is greater than used block
  *         overhead AND a portion of the allocated space is from
  *         the extra free block overhead, the absolute lower bound
 …
  */
+#define HEAP_OVERHEAD \
+  (sizeof( uint32_t   ) * 2)         /* size dummy first and last blocks */
+#define HEAP_BLOCK_USED_OVERHEAD \
+  (sizeof( void * ) * 2)             /* num bytes overhead in used block */
+#define HEAP_MINIMUM_SIZE \
+  (HEAP_OVERHEAD + sizeof (Heap_Block))
+                                     /* min number of bytes the user may */
+                                     /*   specify for the heap size      */
+/*
+/** size dummy first and last blocks */
+#define HEAP_OVERHEAD (sizeof( uint32_t   ) * 2)
+/** number of bytes of overhead in used block */
+#define HEAP_BLOCK_USED_OVERHEAD (sizeof( void * ) * 2)
+/** Minimum number of bytes the user may specify for the heap size */
+#define HEAP_MINIMUM_SIZE (HEAP_OVERHEAD + sizeof (Heap_Block))
+/**
+ *  Forward reference
+ *
+ *  @ref Heap_Block
+ */
+typedef struct Heap_Block_struct Heap_Block;
+/**
  *  The following defines the data structure used to manage
  *  individual blocks in a heap.   When the block is allocated, the
 …
  *  the address of the next field.
+ *
  *  NOTE:  The next and previous pointers are only valid when the
+ *  @note  The next and previous pointers are only valid when the
  *         block is free.  Caution must be exercised to insure that
  *         allocated blocks are large enough to contain them and
 …
  *         block is actually allocated.
  */
-typedef struct Heap_Block_struct Heap_Block;
 struct Heap_Block_struct {
+  uint32_t    back_flag;   /* size and status of prev block */
+  uint32_t    front_flag;  /* size and status of block */
+  Heap_Block *next;        /* pointer to next block */
+  Heap_Block *previous;    /* pointer to previous block */
+  /** size and status of prev block */
+  uint32_t    back_flag;
+  /** size and status of block */
+  uint32_t    front_flag;
+  /** pointer to next block */
+  Heap_Block *next;
+  /** pointer to previous block */
+  Heap_Block *previous;
 };
 /*
+/**
  *  The following defines the control block used to manage each heap.
+ *
+ *  NOTE:
+ *
+ *  This structure is layed out such that it can be used a a dummy
+ *  @note This structure is layed out such that it can be used a a dummy
  *  first and last block on the free block chain.  The extra padding
  *  insures the dummy last block is the correct size.
 …
  *  Handler.
  */
 typedef struct {
+  Heap_Block *start;       /* first valid block address in heap */
+  Heap_Block *final;       /* last valid block address in heap */
+  Heap_Block *first;       /* pointer to first block in heap */
+  Heap_Block *permanent_null;  /* always NULL pointer */
+  Heap_Block *last;        /* pointer to last block in heap */
+  uint32_t    page_size;   /* allocation unit */
+  /** first valid block address in heap */
+  Heap_Block *start;
+  /** last valid block address in heap */
+  Heap_Block *final;
+  /** pointer to first block in heap */
+  Heap_Block *first;
+  /** always NULL pointer */
+  Heap_Block *permanent_null;
+  /** pointer to last block in heap */
+  Heap_Block *last;
+  /** allocation unit */
+  uint32_t    page_size;
+  /** reserved field */
   uint32_t    reserved;
 }   Heap_Control;
+/*
+ *  _Heap_Initialize
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine initializes the_heap record to manage the
+ *  contiguous heap of size bytes which starts at starting_address.
+/**
+ *  This routine initializes @a the_heap record to manage the
+ *  contiguous heap of @a size bytes which starts at @a starting_address.
  *  Blocks of memory are allocated from the heap in multiples of
+ *  page_size byte units.
+ */
+ *  @a page_size byte units.
+ *
+ *  @param the_heap (in) is the heap to operate upon
+ *  @param starting_address (in) is the starting address of the memory for
+ *         the heap
+ *  @param size (in) is the size in bytes of the memory area for the heap
+ *  @param page_size (in) is the size in bytes of the allocation unit
+ *  @return XXX
+ */
 uint32_t   _Heap_Initialize(
   Heap_Control *the_heap,
 …
 );
+/*
+ *  _Heap_Extend
+ *
+ *  DESCRIPTION:
+ *
+ *  This routine grows the_heap memory area using the size bytes which
+ *  begin at starting_address.
+ */
+/**
+ *  This routine grows @a the_heap memory area using the size bytes which
+ *  begin at @a starting_address.
+ *
+ *  @param the_heap (in) is the heap to operate upon
+ *  @param starting_address (in) is the starting address of the memory
+ *         to add to the heap
+ *  @param size (in) is the size in bytes of the memory area to add
+ *  @param amount_extended (in) points to a user area to return the
+ *  @return a status indicating success or the reason for failure
+ *  @return *size filled in with the amount of memory added to the heap
+ */
 Heap_Extend_status _Heap_Extend(
   Heap_Control *the_heap,
 …
 );
+/*
+ *  _Heap_Allocate
+ *
+ *  DESCRIPTION:
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function attempts to allocate a block of size bytes from
  *  the_heap.  If insufficient memory is free in the_heap to allocate
+ *  @a the_heap.  If insufficient memory is free in @a the_heap to allocate
  *  a  block of the requested size, then NULL is returned.
+ */
+ *
+ *  @param the_heap (in) is the heap to operate upon
+ *  @param size (in) is the amount of memory to allocate in bytes
+ *  @return NULL if unsuccessful and a pointer to the block if successful
+ */
 void *_Heap_Allocate(
   Heap_Control *the_heap,
 …
 );
+/*
+ *  _Heap_Size_of_user_area
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This kernel routine sets size to the size of the given heap block.
  *  It returns TRUE if the starting_address is in the heap, and FALSE
+ *  It returns TRUE if the @a starting_address is in @a the_heap, and FALSE
  *  otherwise.
+ */
+ *
+ *  @param the_heap (in) is the heap to operate upon
+ *  @param starting_address (in) is the starting address of the user block
+ *         to obtain the size of
+ *  @param size (in) points to a user area to return the size in
+ *  @return TRUE if successfully able to determine the size, FALSE otherwise
+ *  @return *size filled in with the size of the user area for this block
+ */
 boolean _Heap_Size_of_user_area(
   Heap_Control        *the_heap,
 …
 );
+/*
+ *  _Heap_Free
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine returns the block of memory which begins
  *  at starting_address to the_heap.  Any coalescing which is
+ *  at @a starting_address to @a the_heap.  Any coalescing which is
  *  possible with the freeing of this routine is performed.
+ */
+ *
+ *  @param the_heap (in) is the heap to operate upon
+ *  @param starting_address (in) is the starting address of the user block
+ *         to free
+ *  @return TRUE if successfully freed, FALSE otherwise
+ */
 boolean _Heap_Free(
   Heap_Control *the_heap,
 …
 );
+/*
+ *  _Heap_Walk
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine walks the heap to verify its integrity.
+ */
+ *
+ *  @param the_heap (in) is the heap to operate upon
+ *  @param source (in) XXX
+ *  @param do_dump (in) is set to TRUE if errors should be printed
+ */
 void _Heap_Walk(
   Heap_Control *the_heap,
 …
 );
+/*PAGE
+ *
+ *  _Heap_Get_information
+ *
+/**
  *  This kernel routine walks the heap and tots up the free and allocated
  *  sizes.  Derived from _Heap_Walk.
+ *
+ *  Input parameters:
+ *    the_heap  - pointer to heap header
+ *    the_info  - pointer to information block
+ *
+ *  Output parameters:
+ *    *the_info - status information
+ *    return 0=success, otherwise heap is corrupt.
+ */
+ *  @param the_heap (in) pointer to heap header
+ *  @param the_info (in) pointer to a status information area
+ *  @return *the_info is filled with status information
+ *  @return 0=success, otherwise heap is corrupt.
+ */
 Heap_Get_information_status _Heap_Get_information(
   Heap_Control            *the_heap,
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/interr.h

-                      r7ce11b2
+                      rbaff4da
+/*  interr.h
+/**
+ *  @file interr.h
+ *
  *  This include file contains constants and prototypes related
  *  to the Internal Error Handler.
+ *
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_INTERNAL_ERROR_h
+/**
+ *  @defgroup ScoreIntErr Internal Error Handler
+ *
+ *  This group contains functionality which provides the foundation
+ *  Semaphore services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 /*
+/**
  *  This type lists the possible sources from which an error
  *  can be reported.
  */
 typedef enum {
   INTERNAL_ERROR_CORE,
 …
  *  A list of errors which are generated internally by the executive core.
  */
 typedef enum {
   INTERNAL_ERROR_NO_CONFIGURATION_TABLE,
 …
  *  This type holds the fatal error information.
  */
 typedef struct {
   Internal_errors_Source  the_source;
 …
  *  When a fatal error occurs, the error information is stored here.
  */
 SCORE_EXTERN Internal_errors_Information Internal_errors_What_happened;
+/*
+ *  _Internal_error_Occurred
+ *
+ *  DESCRIPTION:
+/** @brief  Internal error Occurred
+ *
  *  This routine is invoked when the application or the executive itself
  *  determines that a fatal error has occurred.
  */
 void volatile _Internal_error_Occurred(
   Internal_errors_Source  the_source,
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/isr.h

-                      r7ce11b2
+                      rbaff4da
+/*  isr.h
+/**
+ *  @file isr.h
+ *
  *  This include file contains all the constants and structures associated
 …
  *  supports interrupt critical sections, vectoring of user interrupt
  *  handlers, nesting of interrupts, and manipulating interrupt levels.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __ISR_h
+/**
+ *  @defgroup ScoreISR ISR Handler
+ *
+ *  This group contains functionality which provides the foundation
+ *  ISR services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 /*
+/**
  *  The following type defines the control block used to manage
  *  the interrupt level portion of the status register.
  */
 typedef uint32_t   ISR_Level;
 /*
+/**
  *  The following type defines the type used to manage the vectors.
  */
 typedef uint32_t   ISR_Vector_number;
 /*
+/**
  *  Return type for ISR Handler
  */
 typedef void ISR_Handler;
 /*
+/**
  *  Pointer to an ISR Handler
  */
 #if (CPU_ISR_PASSES_FRAME_POINTER == 1)
 typedef ISR_Handler ( *ISR_Handler_entry )(
 …
              );
 #endif
+/*
+/**
  *  This constant promotes out the number of vectors truly supported by
  *  the current CPU being used.  This is usually the number of distinct vectors
  *  the cpu can vector.
  */
 #define ISR_NUMBER_OF_VECTORS                CPU_INTERRUPT_NUMBER_OF_VECTORS
 /*
+/**
  *  This constant promotes out the highest valid interrupt vector number.
  */
 #define ISR_INTERRUPT_MAXIMUM_VECTOR_NUMBER  CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER
 /*
+/**
  *  The following is TRUE if signals have been sent to the currently
  *  executing thread by an ISR handler.
  */
 SCORE_EXTERN boolean    _ISR_Signals_to_thread_executing;
 /*
+/**
  *  The following contains the interrupt service routine nest level.
  *  When this variable is zero, a thread is executing.
  */
 SCORE_EXTERN volatile uint32_t   _ISR_Nest_level;
 /*
+/**
  *  The following declares the Vector Table.  Application
  *  interrupt service routines are vectored by the ISR Handler via this table.
  */
 SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table;
+/*
+ *  _ISR_Handler_initialization
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine performs the initialization necessary for this handler.
  */
 void _ISR_Handler_initialization ( void );
+/*
+ *  _ISR_Disable
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine disables all interrupts so that a critical section
  *  of code can be executing without being interrupted.  Upon return,
  *  the argument _level will contain the previous interrupt mask level.
  */
 #define _ISR_Disable( _level ) \
         _CPU_ISR_Disable( _level )
+/*
+ *  _ISR_Enable
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine enables interrupts to the previous interrupt mask
  *  LEVEL.  It is used at the end of a critical section of code to
  *  enable interrupts so they can be processed again.
  */
 #define _ISR_Enable( _level ) \
         _CPU_ISR_Enable( _level )
+/*
+ *  _ISR_Flash
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine temporarily enables interrupts to the previous
  *  interrupt mask level and then disables all interrupts so that
 …
  *  properly protects itself.
  */
 #define _ISR_Flash( _level ) \
         _CPU_ISR_Flash( _level )
+/*
+ *  _ISR_Install_vector
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine installs new_handler as the interrupt service routine
  *  for the specified vector.  The previous interrupt service routine is
  *  returned as old_handler.
  */
 #define _ISR_Install_vector( _vector, _new_handler, _old_handler ) \
   _CPU_ISR_install_vector( _vector, _new_handler, _old_handler )
+/*
+ *  _ISR_Get_level
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine returns the current interrupt level.
  */
 #define _ISR_Get_level() \
         _CPU_ISR_Get_level()
+/*
+ *  _ISR_Set_level
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine sets the current interrupt level to that specified
  *  by new_level.  The new interrupt level is effective when the
  *  routine exits.
  */
 #define _ISR_Set_level( _new_level ) \
         _CPU_ISR_Set_level( _new_level )
+/*
+ *  _ISR_Handler
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine is the interrupt dispatcher.  ALL interrupts
  *  are vectored to this routine so that minimal context can be saved
 …
  *  performed when the outermost interrupt service routine exits.
+ *
+ *  NOTE:  Implemented in assembly language.
+ */
+ *  @note  Implemented in assembly language.
+ */
 void _ISR_Handler( void );
+/*
+ *  _ISR_Dispatch
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine provides a wrapper so that the routine
  *  _Thread_Dispatch can be invoked when a reschedule is necessary
+ *  @ref _Thread_Dispatch can be invoked when a reschedule is necessary
  *  at the end of the outermost interrupt service routine.  This
  *  wrapper is necessary to establish the processor context needed
 …
  *  of registers which are not preserved across routine invocations.
+ *
+ *  NOTE:  Implemented in assembly language.
+ */
+ *  @note  Implemented in assembly language.
+ */
 void _ISR_Dispatch( void );
+/*PAGE
+ *
+ *  _ISR_Is_in_progress
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function returns TRUE if the processor is currently servicing
  *  and interrupt and FALSE otherwise.   A return value of TRUE indicates
  *  that the caller is an interrupt service routine, NOT a thread.  The
  */
 #if (CPU_PROVIDES_ISR_IS_IN_PROGRESS == TRUE)
 boolean _ISR_Is_in_progress( void );
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/mpci.h

-                      r7ce11b2
+                      rbaff4da
+/*  mpci.h
+/**
+ *  @file mpci.h
+ *
  *  This include file contains all the constants and structures associated
  *  with the MPCI layer.  It provides mechanisms to utilize packets.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __MPCI_h
 #define __MPCI_h
+/**
+ *  @defgroup ScoreMPCI MPCI Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 …
  *  the system threads.
  */
 #define MPCI_RECEIVE_SERVER_STACK_SIZE \
   ( STACK_MINIMUM_SIZE + \
 …
  *  The following defines the node number used when a broadcast is desired.
  */
 #define MPCI_ALL_NODES 0
 …
  *   should take to complete.
  */
 #define MPCI_DEFAULT_TIMEOUT    0xFFFFFFFF
 …
  */
+/**
+ *  This type is returned by all user provided MPCI routines.
+ */
 typedef void MPCI_Entry;
+/**
+ *  This type is XXX
+ */
 typedef MPCI_Entry ( *MPCI_initialization_entry )( void );
+/**
+ *  This type is XXX
+ */
 typedef MPCI_Entry ( *MPCI_get_packet_entry )(
                  MP_packet_Prefix **
              );
+/**
+ *  This type is XXX
+ */
 typedef MPCI_Entry ( *MPCI_return_packet_entry )(
                  MP_packet_Prefix *
              );
+/**
+ *  This type is XXX
+ */
 typedef MPCI_Entry ( *MPCI_send_entry )(
                  uint32_t  ,
 …
              );
+/**
+ *  This type is XXX
+ */
 typedef MPCI_Entry ( *MPCI_receive_entry )(
                  MP_packet_Prefix **
              );
+/**
+ *  This type is XXX
+ */
 typedef struct {
+  uint32_t                   default_timeout;        /* in ticks */
+  /** timeout for MPCI operations in ticks */
+  uint32_t                   default_timeout;
+  /** XXX */
   uint32_t                   maximum_packet_size;
+  /** XXX */
   MPCI_initialization_entry  initialization;
+  /** XXX */
   MPCI_get_packet_entry      get_packet;
+  /** XXX */
   MPCI_return_packet_entry   return_packet;
+  /** XXX */
   MPCI_send_entry            send_packet;
+  /** XXX */
   MPCI_receive_entry         receive_packet;
 } MPCI_Control;
 /*
+/**
  *  The following defines the type for packet processing routines
  *  invoked by the MPCI Receive server.
  */
 typedef void (*MPCI_Packet_processor)( MP_packet_Prefix * );
 /*
+/**
  *  The following enumerated type defines the list of
  *  internal MP operations.
  */
 typedef enum {
   MPCI_PACKETS_SYSTEM_VERIFY  =  0
 }   MPCI_Internal_Remote_operations;
 /*
+/**
  *  The following data structure defines the packet used to perform
  *  remote event operations.
  */
 typedef struct {
+  /** XXX */
   MP_packet_Prefix                 Prefix;
+  /** XXX */
   MPCI_Internal_Remote_operations  operation;
+  /** XXX */
   uint32_t                         maximum_nodes;
+  /** XXX */
   uint32_t                         maximum_global_objects;
 }    MPCI_Internal_packet;
 /*
+/**
  *  This is the core semaphore which the MPCI Receive Server blocks on.
  */
 SCORE_EXTERN CORE_semaphore_Control _MPCI_Semaphore;
+/*
+/**
  *  The following thread queue is used to maintain a list of tasks
  *  which currently have outstanding remote requests.
  */
 SCORE_EXTERN Thread_queue_Control _MPCI_Remote_blocked_threads;
 /*
+/**
  *  The following define the internal pointers to the user's
  *  configuration information.
  */
 SCORE_EXTERN MPCI_Control *_MPCI_table;
 /*
+/**
  *  The following points to the MPCI Receive Server.
  */
 SCORE_EXTERN Thread_Control *_MPCI_Receive_server_tcb;
 /*
+/**
  *  The following table contains the process packet routines provided
  *  by each object that supports MP operations.
  */
 SCORE_EXTERN MPCI_Packet_processor
                _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1];
+/*
+ *  _MPCI_Handler_initialization
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine performs the initialization necessary for this handler.
  */
 void _MPCI_Handler_initialization(
   MPCI_Control            *users_mpci_table,
 …
 );
+/*
+ *  _MPCI_Create_server
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine creates the packet receive server used in MP systems.
  */
 void _MPCI_Create_server( void );
+/*
+ *  _MPCI_Initialization
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine initializes the MPCI driver by
  *  invoking the user provided MPCI initialization callout.
  */
 void _MPCI_Initialization ( void );
+/*
+ *  _MPCI_Register_packet_processor
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine registers the MPCI packet processor for the
  *  designated object class.
  */
 void _MPCI_Register_packet_processor(
   MP_packet_Classes      the_class,
 …
 );
+/*
+ *  _MPCI_Get_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This function obtains a packet by invoking the user provided
  *  MPCI get packet callout.
  */
 MP_packet_Prefix *_MPCI_Get_packet ( void );
+/*
+ *  _MPCI_Return_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine returns a packet by invoking the user provided
  *  MPCI return packet callout.
  */
 void _MPCI_Return_packet (
   MP_packet_Prefix *the_packet
 );
+/*
+ *  _MPCI_Send_process_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine sends a process packet by invoking the user provided
  *  MPCI send callout.
  */
 void _MPCI_Send_process_packet (
   uint32_t          destination,
 …
 );
+/*
+ *  _MPCI_Send_request_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine sends a request packet by invoking the user provided
  *  MPCI send callout.
  */
 uint32_t   _MPCI_Send_request_packet (
   uint32_t           destination,
 …
 );
+/*
+ *  _MPCI_Send_response_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine sends a response packet by invoking the user provided
  *  MPCI send callout.
  */
 void _MPCI_Send_response_packet (
   uint32_t          destination,
 …
 );
+/*
+ *  _MPCI_Receive_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine receives a packet by invoking the user provided
  *  MPCI receive callout.
  */
 MP_packet_Prefix  *_MPCI_Receive_packet ( void );
+/*
+ *  _MPCI_Process_response
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine obtains a packet by invoking the user provided
  *  MPCI get packet callout.
  */
 Thread_Control *_MPCI_Process_response (
   MP_packet_Prefix *the_packet
 );
+/*PAGE
+ *
+ *  _MPCI_Receive_server
+ *
+ */
+/**
+ *  This is the server thread which receives and processes all MCPI packets.
+ */
 Thread _MPCI_Receive_server(
   uint32_t   ignored
 );
+/*PAGE
+ *
+ *  _MPCI_Announce
+ *
+ *  DESCRIPTION:
+ *
+ *  XXX
+ */
+/**
+ *  This routine informs RTEMS of the availability of an MPCI packet.
+ */
 void _MPCI_Announce ( void );
+/*
+ *  _MPCI_Internal_packets_Send_process_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine performs a remote procedure call so that a
  *  process operation can be performed on another node.
  */
 void _MPCI_Internal_packets_Send_process_packet (
    MPCI_Internal_Remote_operations operation
 …
  *  _MPCI_Internal_packets_Send_request_packet
+ *
- *  DESCRIPTION:
+ *
  *  This routine performs a remote procedure call so that a
  *  directive operation can be initiated on another node.
 …
  *  _MPCI_Internal_packets_Send_response_packet
+ *
- *  DESCRIPTION:
+ *
  *  This routine performs a remote procedure call so that a
  *  directive can be performed on another node.
 …
  */
+/*
+ *
+ *  _MPCI_Internal_packets_Process_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine performs the actions specific to this package for
  *  the request from another node.
  */
 void _MPCI_Internal_packets_Process_packet (
   MP_packet_Prefix *the_packet_prefix
 …
 /*
  *  _MPCI_Internal_packets_Send_object_was_deleted
+ *
- *  DESCRIPTION:
+ *
  *  This routine is invoked indirectly by the thread queue
 …
  *  _MPCI_Internal_packets_Send_extract_proxy
+ *
- *  DESCRIPTION:
+ *
  *  This routine is invoked when a task is deleted and it
  *  has a proxy which must be removed from a thread queue and
 …
  */
+/*
+ *  _MPCI_Internal_packets_Get_packet
+ *
+ *  DESCRIPTION:
+ *
+/**
  *  This routine is used to obtain a internal threads mp packet.
  */
+ MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
+MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
 #ifdef __cplusplus
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/mppkt.h

-                      r7ce11b2
+                      rbaff4da
+/*  mppkt.h
+/**
+ *  @file mppkt.h
+ *
  *  This package is the specification for the Packet Handler.
 …
  *  Packets are the fundamental basis for messages passed between
  *  nodes in an MP system.
+ *
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __MP_PACKET_h
+/**
+ *  @defgroup ScoreMPPacket MP Packet Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
 #include <rtems/score/watchdog.h>
 /*
+/**
  *  The following enumerated type defines the packet classes.
+ *
  *  NOTE:  In general, each class corresponds to a manager
+ *  @note  In general, each class corresponds to a manager
  *         which supports global operations.  Each manager
  *         defines the set of supported operations.
  */
 typedef enum {
   MP_PACKET_MPCI_INTERNAL    = 0,
 …
 }   MP_packet_Classes;
+/**
+ *  XXX
+ */
 #define MP_PACKET_CLASSES_FIRST  MP_PACKET_MPCI_INTERNAL
+/**
+ *  XXX
+ */
 #define MP_PACKET_CLASSES_LAST   MP_PACKET_SIGNAL
 /*
+/**
  *  The following record contains the prefix for every packet
  *  passed between nodes in an MP system.
+ *
  *  NOTE: This structure is padded to ensure that anything following it
+ *  @note This structure is padded to ensure that anything following it
  *        is on a 16 byte boundary.  This is the most stringent structure
  *        alignment rule encountered yet.
  */
 typedef struct {
+  /** XXX */
   MP_packet_Classes       the_class;
+  /** XXX */
   Objects_Id              id;
+  /** XXX */
   Objects_Id              source_tid;
+  /** XXX */
   Priority_Control        source_priority;
+  /** XXX */
   uint32_t                return_code;
+  /** XXX */
   uint32_t                length;
+  /** XXX */
   uint32_t                to_convert;
+  /** XXX */
   Watchdog_Interval       timeout;
 }   MP_packet_Prefix;
 /*
+/**
  *  An MPCI must support packets of at least this size.
  */
 #define MP_PACKET_MINIMUM_PACKET_SIZE  64
 /*
+/**
  *  The following constant defines the number of uint32_t  's
  *  in a packet which must be converted to native format in a
 …
  *  may a user message buffer which is not automatically endian swapped.
  */
 #define MP_PACKET_MINIMUN_HETERO_CONVERSION  \
   ( sizeof( MP_packet_Prefix ) / sizeof( uint32_t   ) )
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/objectmp.h

-                      r7ce11b2
+                      rbaff4da
+/*  objectmp.h
+/**
+ *  @file objectmp.h
+ *
  *  This include file contains all the constants and structures associated
  *  with the manipulation of Global RTEMS Objects.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __RTEMS_OBJECTS_MP_h
+/**
+ *  @defgroup ScoreObjectMP Object Handler Multiprocessing Support
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
  *  objects resident on other nodes.
  */
 typedef struct {
   Objects_Control Object;
 …
 }   Objects_MP_Control;
+/*
+ *  _Objects_MP_Handler_initialization
+ *
+ *  DESCRIPTION:
+/** @brief  Objects MP Handler initialization
+ *
  *  This routine intializes the inactive global object chain
  *  based on the maximum number of global objects configured.
  */
 void _Objects_MP_Handler_initialization (
   uint32_t   node,
 …
 );
+/*PAGE
+ *
+ *  _Objects_MP_Open
+ *
+ *  DESCRIPTION:
+/** @brief Objects MP Open
+ *
  *  This routine place the specified global object in the
 …
 );
+/*
+ *  _Objects_MP_Allocate_and_open
+ *
+ *  DESCRIPTION:
+/** @brief  Objects MP Allocate and open
+ *
  *  This routine allocates a global object control block
 …
  *  error processing actions taken.
  */
 boolean _Objects_MP_Allocate_and_open (
   Objects_Information *information,
 …
 );
+/*
+ *  _Objects_MP_Close
+ *
+ *  DESCRIPTION:
+/** @brief  Objects MP Close
+ *
  *  This routine removes a global object from the specified
  *  information table and deallocates the global object control block.
  */
 void _Objects_MP_Close (
   Objects_Information *information,
 …
 );
+/*
+ *  _Objects_MP_Global_name_search
+ *
+ *  DESCRIPTION:
+/** @brief  Objects MP Global name search
+ *
  *  This routine looks for the object with the_name in the global
 …
  *  object with that name if one is found.
  */
 Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
   Objects_Information *information,
 …
 );
+/*
+ *  _Objects_MP_Is_remote
+ *
+ *  DESCRIPTION:
+/** @brief  Objects MP Is remote
+ *
  *  This function searches the Global Object Table managed
 …
  *  is undefined.
  */
 void _Objects_MP_Is_remote (
   Objects_Information  *information,
 …
  *  inactive global object control blocks.
  */
 SCORE_EXTERN uint32_t       _Objects_MP_Maximum_global_objects;
 SCORE_EXTERN Chain_Control  _Objects_MP_Inactive_global_objects;
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/priority.h

-                      r7ce11b2
+                      rbaff4da
+/*  priority.h
+/**
+ *  @file priority.h
+ *
  *  This include file contains all thread priority manipulation routines.
  *  This Handler provides mechanisms which can be used to
  *  initialize and manipulate thread priorities.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #define __PRIORITY_h
+/**
+ *  @defgroup ScorePriority Priority Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 …
  *  thread priorities.
+ *
  *  NOTE: Priority 0 is reserved for internal threads only.
+ *  @note Priority 0 is reserved for internal threads only.
  */
 …
  *  Priority Bitfield Manipulation Routines
+ *
  *  NOTE:
+ *  @note
+ *
  *  These may simply be pass throughs to CPU dependent routines.
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/stack.h

-                      r7ce11b2
+                      rbaff4da
+/*  stack.h
+/**
+ *  @file stack.h
+ *
  *  This include file contains all information about the thread
  *  Stack Handler.  This Handler provides mechanisms which can be used to
  *  initialize and utilize stacks.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __STACK_h
 #define __STACK_h
+/**
+ *  @defgroup ScoreStack Stack Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/states.h

-                      r7ce11b2
+                      rbaff4da
+/*  states.h
+/**
+ *  @file states.h
+ *
  *  This include file contains thread execution state information.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __RTEMS_STATES_h
 #define __RTEMS_STATES_h
+/**
+ *  @defgroup ScoreStates Thread States Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/sysstate.h

-                      r7ce11b2
+                      rbaff4da
+/*  sysstates.h
+/**
+ *  @file sysstate.h
+ *
  *  This include file contains information regarding the system state.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __RTEMS_SYSTEM_STATE_h
 #define __RTEMS_SYSTEM_STATE_h
+/**
+ *  @defgroup ScoreSysState System State Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 …
 #endif
+/**@}*/
 #endif
 /* end of include file */

cpukit/score/include/rtems/score/thread.h

-                      r7ce11b2
+                      rbaff4da
+/*  thread.h
+/**
+ *  @file thread.h
+ *
  *  This include file contains all constants and structures associated
  *  with the thread control block.
+ *
+ *  COPYRIGHT (c) 1989-1999.
+ */
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
+ *
 …
 #ifndef __THREAD_h
 #define __THREAD_h
+/**
+ *  @defgroup ScoreThread Thread Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
 #ifdef __cplusplus
 …
 #include <rtems/score/watchdog.h>
 /*
+/**
  *  The following defines the "return type" of a thread.
+ *
  *  NOTE:  This cannot always be right.  Some APIs have void
+ *  @note  This cannot always be right.  Some APIs have void
  *         tasks/threads, others return pointers, others may
  *         return a numeric value.  Hopefully a pointer is
  *         always at least as big as an uint32_t  . :)
  */
 typedef void *Thread;
 /*
+/**
  *  The following defines the ways in which the entry point for a
  *  thread can be invoked.  Basically, it can be passed any
  *  combination/permutation of a pointer and an uint32_t   value.
+ *
+ *  NOTE: For now, we are ignoring the return type.
+ */
+ *  @note For now, we are ignoring the return type.
+ */
 typedef enum {
   THREAD_START_NUMERIC,
 …
 } Thread_Start_types;
+/**
+ */
 typedef Thread ( *Thread_Entry )();   /* basic type */
 typedef Thread ( *Thread_Entry_numeric )( uint32_t   );
+/**
+ */
 typedef Thread ( *Thread_Entry_pointer )( void * );
+/**
+ */
 typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t   );
+/**
+ */
 typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t  , void * );
 /*
+/**
  *  The following lists the algorithms used to manage the thread cpu budget.
+ *
 …
  *  Callout:           Execute routine when budget is consumed.
  */
 typedef enum {
   THREAD_CPU_BUDGET_ALGORITHM_NONE,
 …
 }  Thread_CPU_budget_algorithms;
+/**
+ */
 typedef struct Thread_Control_struct Thread_Control;
+/**
+ */
 typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );
 /*
  *  Per task variable structure
  */
+/** @brief Per Task Variable Manager Structure Forward Reference
+ *
+ *  Forward reference to the per task variable structure.
+ */
 struct rtems_task_variable_tt;
+/** @brief Per Task Variable Manager Structure
+ *
+ *  This is the internal structure used to manager per Task Variables.
+ */
 struct rtems_task_variable_tt {
+  /** This field points to the next per task variable for this task. */
   struct rtems_task_variable_tt  *next;
+  /** This field points to the physical memory location of this per
+   *  task variable.
+   */
   void                          **ptr;
+  /** This field is to the global value for this per task variable. */
   void                           *gval;
+  /** This field is to this thread's value for this per task variable. */
   void                           *tval;
+  /** This field points to the destructor for this per task variable. */
   void                          (*dtor)(void *);
 };
+/**
+ */
 typedef struct rtems_task_variable_tt   rtems_task_variable_t;
 /*
+/**
  *  The following structure contains the information which defines
  *  the starting state of a thread.
  */
 typedef struct {
   Thread_Entry         entry_point;      /* starting thread address         */
 …
 }   Thread_Start_information;
 /*
+/**
  *  The following structure contains the information necessary to manage
  *  a thread which it is  waiting for a resource.
  */
 #define THREAD_STATUS_PROXY_BLOCKING 0x1111111
+/** @brief Thread Blocking Management Information
+ *
+ *  This contains the information required to manage a thread while it is
+ *  blocked and to return information to it.
+ */
 typedef struct {
+  Objects_Id            id;              /* waiting on this object       */
+  uint32_t              count;           /* "generic" fields to be used */
+  void                 *return_argument; /*   when blocking */
+  /** This field is the Id of the object this thread is waiting upon. */
+  Objects_Id            id;
+  /** This field is used to return an integer while when blocked. */
+  uint32_t              count;
+  /** This field is the first pointer to a user return argument. */
+  void                 *return_argument;
+  /** This field is the second pointer to a user return argument. */
   void                 *return_argument_1;
+  /** This field contains any options in effect on this blocking operation. */
   uint32_t              option;
   /*
    *  NOTE: The following assumes that all API return codes can be
    *        treated as an uint32_t  .
+  /** This field will contain the return status from a blocking operation.
+   *
+   *  @note The following assumes that all API return codes can be
+   *        treated as an uint32_t.
    */
+  uint32_t              return_code;     /* status for thread awakened   */
+  Chain_Control         Block2n;         /* 2 - n priority blocked chain */
+  Thread_queue_Control *queue;           /* pointer to thread queue      */
+  uint32_t              return_code;
+  /** This field is the chain header for the second through Nth tasks
+   *  of the same priority blocked waiting on the same object.
+   */
+  Chain_Control         Block2n;
+  /** This field points to the thread queue on which this thread is blocked. */
+  Thread_queue_Control *queue;
 }   Thread_Wait_information;
 /*
+/**
  *  The following defines the control block used to manage
  *  each thread proxy.
+ *
  *  NOTE: It is critical that proxies and threads have identical
+ *  @note It is critical that proxies and threads have identical
  *        memory images for the shared part.
  */
 typedef struct {
   Objects_Control          Object;
 …
 }   Thread_Proxy_control;
+/*
+/**
  *  The following record defines the control block used
  *  to manage each thread.
+ *
  *  NOTE: It is critical that proxies and threads have identical
+ *  @note It is critical that proxies and threads have identical
  *        memory images for the shared part.
  */
 typedef enum {
   THREAD_API_RTEMS,
 …
 }  Thread_APIs;
+/**
+ */
 #define THREAD_API_FIRST THREAD_API_RTEMS
+/**
+ */
 #define THREAD_API_LAST  THREAD_API_ITRON
+/**
+ */
 struct Thread_Control_struct {
   Objects_Control                       Object;
 …
 };
 /*
+/**
  *  Self for the GNU Ada Run-Time
  */
 SCORE_EXTERN void *rtems_ada_self;
 /*
+/**
  *  The following defines the information control block used to
  *  manage this class of objects.
  */
 SCORE_EXTERN Objects_Information _Thread_Internal_information;
 /*
+/**
  *  The following define the thread control pointers used to access
  *  and manipulate the idle thread.
  */
 SCORE_EXTERN Thread_Control *_Thread_Idle;
 /*
+/**
  *  The following context area contains the context of the "thread"
  *  which invoked the start multitasking routine.  This context is
 …
  *  which initiated the system.
  */
 SCORE_EXTERN Context_Control _Thread_BSP_context;
 /*
+/***
  *  The following declares the dispatch critical section nesting
  *  counter which is used to prevent context switches at inopportune
  *  moments.
  */
 SCORE_EXTERN volatile uint32_t   _Thread_Dispatch_disable_level;
 /*
+/**
  *  If this is non-zero, then the post-task switch extension
  *  is run regardless of the state of the per thread flag.
  */
 SCORE_EXTERN uint32_t   _Thread_Do_post_task_switch_extension;
 /*
+/**
  *  The following holds how many user extensions are in the system.  This
  *  is used to determine how many user extension data areas to allocate
  *  per thread.
  */
 SCORE_EXTERN uint32_t   _Thread_Maximum_extensions;
 /*
+/**
  *  The following is used to manage the length of a timeslice quantum.
  */
 SCORE_EXTERN uint32_t   _Thread_Ticks_per_timeslice;
 /*
+/**
  *  The following points to the array of FIFOs used to manage the
  *  set of ready threads.
  */
 SCORE_EXTERN Chain_Control *_Thread_Ready_chain;
 /*
+/**
  *  The following points to the thread which is currently executing.
  *  This thread is implicitly manipulated by numerous directives.
  */
 SCORE_EXTERN Thread_Control *_Thread_Executing;
 /*
+/**
  *  The following points to the highest priority ready thread
  *  in the system.  Unless the current thread is not preemptibl,
 …
  *  dispatch occurs.
  */
 SCORE_EXTERN Thread_Control *_Thread_Heir;

Context Navigation

Changeset baff4da in rtems

Legend:

cpukit/ChangeLog

cpukit/score/cpu/no_cpu/rtems/score/cpu.h

cpukit/score/include/rtems/debug.h

cpukit/score/include/rtems/score/address.h

cpukit/score/include/rtems/score/apiext.h

cpukit/score/include/rtems/score/apimutex.h

cpukit/score/include/rtems/score/bitfield.h

cpukit/score/include/rtems/score/chain.h

cpukit/score/include/rtems/score/context.h

cpukit/score/include/rtems/score/copyrt.h

cpukit/score/include/rtems/score/coremsg.h

cpukit/score/include/rtems/score/coremutex.h

cpukit/score/include/rtems/score/coresem.h

cpukit/score/include/rtems/score/heap.h

cpukit/score/include/rtems/score/interr.h

cpukit/score/include/rtems/score/isr.h

cpukit/score/include/rtems/score/mpci.h

cpukit/score/include/rtems/score/mppkt.h

cpukit/score/include/rtems/score/objectmp.h

cpukit/score/include/rtems/score/priority.h

cpukit/score/include/rtems/score/stack.h

cpukit/score/include/rtems/score/states.h

cpukit/score/include/rtems/score/sysstate.h

cpukit/score/include/rtems/score/thread.h