From 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 16 Jan 2006 15:13:58 +0000 Subject: 2006-01-16 Joel Sherrill Large patch to improve Doxygen output. As a side-effect, grammar and spelling errors were corrected, spacing errors were address, and some variable names were improved. * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. * score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output. * 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/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/object.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/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes. --- cpukit/ChangeLog | 108 ++++++ cpukit/libmisc/monitor/mon-object.c | 2 +- cpukit/libmisc/monitor/monitor.h | 2 +- cpukit/score/Doxyfile | 7 +- cpukit/score/cpu/arm/rtems/score/cpu.h | 9 +- cpukit/score/include/rtems/debug.h | 40 +- cpukit/score/include/rtems/score/address.h | 6 +- cpukit/score/include/rtems/score/apiext.h | 27 +- cpukit/score/include/rtems/score/apimutex.h | 12 +- cpukit/score/include/rtems/score/bitfield.h | 8 +- cpukit/score/include/rtems/score/chain.h | 48 ++- cpukit/score/include/rtems/score/context.h | 61 +-- cpukit/score/include/rtems/score/coremsg.h | 136 ++++--- cpukit/score/include/rtems/score/coremutex.h | 119 +++--- cpukit/score/include/rtems/score/coresem.h | 30 +- cpukit/score/include/rtems/score/heap.h | 123 +++--- cpukit/score/include/rtems/score/interr.h | 13 +- cpukit/score/include/rtems/score/isr.h | 8 +- cpukit/score/include/rtems/score/mpci.h | 162 +++++--- cpukit/score/include/rtems/score/mppkt.h | 26 +- cpukit/score/include/rtems/score/object.h | 527 ++++++++++++++++++-------- cpukit/score/include/rtems/score/objectmp.h | 75 +++- cpukit/score/include/rtems/score/priority.h | 81 ++-- cpukit/score/include/rtems/score/stack.h | 17 +- cpukit/score/include/rtems/score/states.h | 33 +- cpukit/score/include/rtems/score/sysstate.h | 41 +- cpukit/score/include/rtems/score/thread.h | 151 ++++++-- cpukit/score/include/rtems/score/threadmp.h | 10 +- cpukit/score/include/rtems/score/threadq.h | 5 +- cpukit/score/include/rtems/score/tod.h | 60 +-- cpukit/score/include/rtems/score/tqdata.h | 53 ++- cpukit/score/include/rtems/score/userext.h | 103 +++-- cpukit/score/include/rtems/score/watchdog.h | 35 +- cpukit/score/include/rtems/score/wkspace.h | 11 +- cpukit/score/include/rtems/seterr.h | 18 +- cpukit/score/include/rtems/system.h | 115 ++++-- cpukit/score/inline/rtems/score/address.inl | 58 ++- cpukit/score/inline/rtems/score/chain.inl | 218 ++++++++--- cpukit/score/inline/rtems/score/coremutex.inl | 52 ++- cpukit/score/inline/rtems/score/coresem.inl | 16 +- cpukit/score/inline/rtems/score/heap.inl | 135 +++++-- cpukit/score/inline/rtems/score/object.inl | 185 ++++----- cpukit/score/inline/rtems/score/stack.inl | 4 +- cpukit/score/inline/rtems/score/thread.inl | 8 +- cpukit/score/inline/rtems/score/tqdata.inl | 6 +- cpukit/score/macros/README | 6 +- cpukit/score/src/heap.c | 12 +- cpukit/score/src/threadmp.c | 4 +- cpukit/score/src/threadready.c | 4 +- cpukit/score/src/threadstartmultitasking.c | 4 +- 50 files changed, 2013 insertions(+), 981 deletions(-) (limited to 'cpukit') diff --git a/cpukit/ChangeLog b/cpukit/ChangeLog index 4bab8b24e8..030bee738f 100644 --- a/cpukit/ChangeLog +++ b/cpukit/ChangeLog @@ -1,3 +1,111 @@ +2006-01-16 Joel Sherrill + + Large patch to improve Doxygen output. As a side-effect, grammar and + spelling errors were corrected, spacing errors were address, and some + variable names were improved. + * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: + Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. + * score/Doxyfile: Set output directory. Predefine some macro values. + Turn on graphical output. + * 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/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/object.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/coremutex.inl, + score/inline/rtems/score/coresem.inl, + score/inline/rtems/score/heap.inl, + score/inline/rtems/score/object.inl, + score/inline/rtems/score/stack.inl, + score/inline/rtems/score/thread.inl, + score/inline/rtems/score/tqdata.inl, score/macros/README, + score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, + score/src/threadstartmultitasking.c: Improve generated Doxygen + output. Fix spelling and grammar errors in comments. Correct names of + some variables and propagate changes. + +2006-01-16 Joel Sherrill + + Large patch to improve Doxygen output. As a side-effect, grammar and + spelling errors were corrected, spacing errors were address, and some + variable names were improved. + * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: + Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. + * score/Doxyfile: Set output directory. Predefine some macro values. + Turn on graphical output. + * score/cpu/arm/rtems/score/cpu.h, + score/cpu/avr/rtems/score/cpu.h, score/cpu/c4x/rtems/score/cpu.h, + score/cpu/h8300/rtems/score/cpu.h, score/cpu/m68k/rtems/score/cpu.h, + score/cpu/mips/rtems/score/cpu.h, score/cpu/no_cpu/rtems/asm.h, + score/cpu/no_cpu/rtems/score/cpu.h, + score/cpu/no_cpu/rtems/score/types.h, + score/cpu/powerpc/rtems/new-exceptions/cpu.h, + score/cpu/powerpc/rtems/old-exceptions/cpu.h, + score/cpu/powerpc/rtems/score/cpu.h, score/cpu/sh/rtems/score/cpu.h, + score/cpu/sparc/rtems/score/cpu.h, score/cpu/unix/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/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/object.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/coremutex.inl, + score/inline/rtems/score/coresem.inl, + score/inline/rtems/score/heap.inl, + score/inline/rtems/score/object.inl, + score/inline/rtems/score/stack.inl, + score/inline/rtems/score/thread.inl, + score/inline/rtems/score/tqdata.inl, score/macros/README, + score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, + score/src/threadstartmultitasking.c: Improve generated Doxygen + output. Fix spelling and grammar errors in comments. Correct names of + some variables and propagate changes. + 2006-01-15 Eric Norum * /posix/inline/rtems/posix/cond.inl, /posix/inline/rtems/posix/mutex.inl, diff --git a/cpukit/libmisc/monitor/mon-object.c b/cpukit/libmisc/monitor/mon-object.c index 3e714fa35c..b01fe74f5d 100644 --- a/cpukit/libmisc/monitor/mon-object.c +++ b/cpukit/libmisc/monitor/mon-object.c @@ -130,7 +130,7 @@ rtems_monitor_id_fixup( node = rtems_get_node(id); if (node == 0) { - if (rtems_get_class(id) != OBJECTS_NO_CLASS) + if (rtems_get_class(id) != OBJECTS_CLASSIC_NO_CLASS) type = rtems_get_class(id); id = _Objects_Build_id( diff --git a/cpukit/libmisc/monitor/monitor.h b/cpukit/libmisc/monitor/monitor.h index 0c4680c683..3248e2f836 100644 --- a/cpukit/libmisc/monitor/monitor.h +++ b/cpukit/libmisc/monitor/monitor.h @@ -26,7 +26,7 @@ typedef struct _rtems_symbol_table_t rtems_symbol_table_t; */ typedef enum { - RTEMS_MONITOR_OBJECT_INVALID = OBJECTS_NO_CLASS, + RTEMS_MONITOR_OBJECT_INVALID = OBJECTS_CLASSIC_NO_CLASS, RTEMS_MONITOR_OBJECT_TASK = OBJECTS_RTEMS_TASKS, RTEMS_MONITOR_OBJECT_EXTENSION = OBJECTS_RTEMS_EXTENSIONS, RTEMS_MONITOR_OBJECT_QUEUE = OBJECTS_RTEMS_MESSAGE_QUEUES, diff --git a/cpukit/score/Doxyfile b/cpukit/score/Doxyfile index 0749e983c1..dd384bf7ba 100644 --- a/cpukit/score/Doxyfile +++ b/cpukit/score/Doxyfile @@ -30,7 +30,7 @@ PROJECT_NUMBER = # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = score_doxy # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this @@ -875,7 +875,8 @@ INCLUDE_FILE_PATTERNS = # or name=definition (no spaces). If the definition and the = are # omitted =1 is assumed. -PREDEFINED = RTEMS_INLINES +PREDEFINED = RTEMS_INLINES FALSE=0 \ + CPU_USE_GENERIC_BITFIELD_DATA=0 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -958,7 +959,7 @@ HIDE_UNDOC_RELATIONS = YES # toolkit from AT&T and Lucent Bell Labs. The other options in this section # have no effect if this option is set to NO (the default) -HAVE_DOT = NO +HAVE_DOT = YES # If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and diff --git a/cpukit/score/cpu/arm/rtems/score/cpu.h b/cpukit/score/cpu/arm/rtems/score/cpu.h index 68c6b291f5..ca1ac70334 100644 --- a/cpukit/score/cpu/arm/rtems/score/cpu.h +++ b/cpukit/score/cpu/arm/rtems/score/cpu.h @@ -8,6 +8,8 @@ * This include file contains information pertaining to the ARM * processor. * + * Copyright (c) 2006 OAR Corporation + * * Copyright (c) 2002 Advent Networks, Inc. * Jay Monkman * @@ -123,8 +125,7 @@ extern "C" { * If TRUE, then the memory is allocated during initialization. * 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. + * This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE. */ #define CPU_ALLOCATE_INTERRUPT_STACK FALSE @@ -449,7 +450,7 @@ SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context; #define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE /* - * Should be large enough to run all RTEMS tests. This insures + * Should be large enough to run all RTEMS tests. This ensures * that a "reasonable" small application should not have any problems. */ @@ -803,7 +804,7 @@ void _CPU_Context_restore_fp( * Some CPUs have special instructions which swap a 32-bit quantity in * a single instruction (e.g. i486). It is probably best to avoid * an "endian swapping control bit" in the CPU. One good reason is - * that interrupts would probably have to be disabled to insure that + * that interrupts would probably have to be disabled to ensure that * an interrupt does not try to access the same "chunk" with the wrong * endian. Another good reason is that on some CPUs, the endian bit * endianness for ALL fetches -- both code and data -- so the code diff --git a/cpukit/score/include/rtems/debug.h b/cpukit/score/include/rtems/debug.h index 31f0005709..abdb6200d0 100644 --- a/cpukit/score/include/rtems/debug.h +++ b/cpukit/score/include/rtems/debug.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,69 +24,49 @@ extern "C" { #endif -/* +/** * The following type is used to manage the debug mask. */ - typedef uint32_t rtems_debug_control; /* * These constants represent various classes of debugging. */ +/** Macro which indicates that all debugging modes are enabled */ #define RTEMS_DEBUG_ALL_MASK 0xffffffff + +/** Macro which indicates that debugging for heaps/regions is enabled */ #define RTEMS_DEBUG_REGION 0x00000001 -/* +/** * This variable contains the current debug level. */ - SCORE_EXTERN rtems_debug_control _Debug_Level; -/* - * _Debug_Manager_initialization - * - * DESCRIPTION: - * +/** * This routine performs the initialization necessary for this manager. */ - void _Debug_Manager_initialization( void ); -/* - * rtems_debug_enable - * - * DESCRIPTION: - * +/** * This routine enables the specified types of debug checks. */ - void rtems_debug_enable ( rtems_debug_control to_be_enabled ); -/* - * rtems_debug_disable - * - * DESCRIPTION: - * +/** * This routine disables the specified types of debug checks. */ - void rtems_debug_disable ( rtems_debug_control to_be_disabled ); -/* - * - * _Debug_Is_enabled - * - * DESCRIPTION: - * +/** * This routine returns TRUE if the requested debug level is * enabled, and FALSE otherwise. */ - boolean _Debug_Is_enabled( rtems_debug_control level ); diff --git a/cpukit/score/include/rtems/score/address.h b/cpukit/score/include/rtems/score/address.h index aab714afd4..405c5b715c 100644 --- a/cpukit/score/include/rtems/score/address.h +++ b/cpukit/score/include/rtems/score/address.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,8 +22,8 @@ /** * @defgroup ScoreAddress Address Handler * - * This group contains functionality which abstracts address manipulation - * in a portable manner. + * This handler encapsulates functionality which abstracts address + * manipulation in a portable manner. */ /**@{*/ diff --git a/cpukit/score/include/rtems/score/apiext.h b/cpukit/score/include/rtems/score/apiext.h index cd794bc2d1..e1135fbd63 100644 --- a/cpukit/score/include/rtems/score/apiext.h +++ b/cpukit/score/include/rtems/score/apiext.h @@ -1,11 +1,11 @@ -/** +/** * @file rtems/score/apiext.h * * This is the API Extensions Handler. */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,9 +21,9 @@ /** * @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 + * This handler encapsulates functionality which provides mechanisms for the + * SuperCore to perform API specific actions without there beingg + * "up-references" from the SuperCore to APIs. If these referencesg * 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. @@ -87,31 +87,36 @@ typedef struct { */ SCORE_EXTERN Chain_Control _API_extensions_List; -/** +/** @brief Initialize the API Extensions Handler + * * This routine initializes the API extension handler. */ void _API_extensions_Initialization( void ); -/** +/** @brief Add Extension Set to the Active Set + * * This routine adds an extension to the active set of API extensions. * - * @param the_extension (in) is the extension set to add. + * @param[in] the_extension is the extension set to add. */ void _API_extensions_Add( API_extensions_Control *the_extension ); -/** +/** @brief Execute all Pre-Driver Extensions + * * This routine executes all of the predriver callouts. */ void _API_extensions_Run_predriver( void ); -/** +/** @brief Execute all Post-Driver Extensions + * * This routine executes all of the postdriver callouts. */ void _API_extensions_Run_postdriver( void ); -/** +/** @brief Execute all Post Context Switch Extensions + * * This routine executes all of the post context switch callouts. */ void _API_extensions_Run_postswitch( void ); diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h index 914207fc81..ea257f4a7e 100644 --- a/cpukit/score/include/rtems/score/apimutex.h +++ b/cpukit/score/include/rtems/score/apimutex.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,7 @@ /** * @defgroup ScoreAPIMutex API Mutex Handler * - * This group contains functionality which provides mutexes to be used + * This handler encapsulates functionality which provides mutexes to be used * in the implementation of API functionality. */ /**@{*/ @@ -56,7 +56,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine performs the initialization necessary for this handler. * - * @param _maximum_mutexes (in) is the maximum number of API mutexes + * @param[in] _maximum_mutexes is the maximum number of API mutexes * that may exist at any time */ #if defined(RTEMS_MULTIPROCESSING) @@ -88,7 +88,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine allocates an API mutex from the inactive set. * - * @param _the_mutex (out) will contain the allocated mutex. + * @param[out] _the_mutex will contain the allocated mutex. */ #define _API_Mutex_Allocate( _the_mutex ) \ do { \ @@ -104,7 +104,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine acquires the specified API mutex. * - * @param _the_mutex (in) is the mutex to acquire. + * @param[in] _the_mutex is the mutex to acquire. */ #define _API_Mutex_Lock( _the_mutex ) \ do { \ @@ -117,7 +117,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine releases the specified API mutex. * - * @param _the_mutex (in) is the mutex to release. + * @param[in] _the_mutex is the mutex to release. */ #define _API_Mutex_Unlock( _the_mutex ) \ diff --git a/cpukit/score/include/rtems/score/bitfield.h b/cpukit/score/include/rtems/score/bitfield.h index 71fe09db6f..bfeef76dfc 100644 --- a/cpukit/score/include/rtems/score/bitfield.h +++ b/cpukit/score/include/rtems/score/bitfield.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,7 @@ /** * @defgroup ScoreBitfield Bitfield Handler * - * This group contains functionality that is used to manipulate the + * This handler encapsulates functionality that is used to manipulate the * priority bitfields used to lookup which priority has the highest * priority ready to execute thread. */ @@ -70,8 +70,8 @@ const unsigned char __log2table[256] = { * 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. + * @param[in] _value is the value to bit scan. + * @param[in] _bit_number 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 diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h index 0e3e930257..4a908cd19c 100644 --- a/cpukit/score/include/rtems/score/chain.h +++ b/cpukit/score/include/rtems/score/chain.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,11 @@ /** * @defgroup ScoreChain Chain Handler * - * The Chain Handler contains XXX + * The Chain Handler is used to manage sets of entities. This handler + * provides two data structures. The Chain Node data structure is included + * as the first part of every data structure that will be placed on + * a chain. The second data structure is Chain Control which is used + * to manage a set of Chain Nodes. */ /**@{*/ @@ -37,7 +41,8 @@ extern "C" { * * 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. + * reference is required to define it. See @ref Chain_Node_struct for + * detailed information. */ typedef struct Chain_Node_struct Chain_Node; @@ -95,11 +100,11 @@ typedef struct { * contiguous array of @a number_nodes nodes which starts at * @a starting_address. Each node is of @a node_size bytes. * - * @param the_chain (in) specifies the chain to initialize - * @param starting_address (in) is the starting address of the array + * @param[in] the_chain specifies the chain to initialize + * @param[in] starting_address 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 + * @param[in] number_nodes is the numebr of nodes that will be in the chain + * @param[in] node_size is the size of each node */ void _Chain_Initialize( Chain_Control *the_chain, @@ -112,9 +117,9 @@ void _Chain_Initialize( /** * @brief Get the first node (do not disable interrupts) * - * This method attempts to obtain the first node from \a the_chain. + * This method attempts to obtain the first node from @a the_chain. * - * @param the_chain (in) points to the chain to operate upon + * @param[in] the_chain points to the chain to operate upon * @return If successful, a chain node is returned. Otherwise, NULL * is returned. */ @@ -126,8 +131,8 @@ Chain_Node *_Chain_Get_first_unprotected( /** * @brief Extract the specified node from a chain * - * This routine extracts \a the_node from the chain on which it resides. - * It disables interrupts to insure the atomicity of the + * This routine extracts @a the_node from the chain on which it resides. + * It disables interrupts to ensure the atomicity of the * extract operation. * * @arg the_node specifies the node to extract @@ -139,11 +144,14 @@ void _Chain_Extract( /** * @brief Obtain the first node on a chain * - * 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 @a the_chain and returns + * a pointer to that node. If @a the_chain is empty, then NULL is returned. * - * @note It disables interrupts to insure the atomicity of the - * get operation. + * @return This method returns a pointer a node. If a node was removed, + * then a pointer to that node is returned. If @a the_chain was + * empty, then NULL is returned. + * + * @note It disables interrupts to ensure the atomicity of the get operation. */ Chain_Node *_Chain_Get( Chain_Control *the_chain @@ -152,10 +160,10 @@ Chain_Node *_Chain_Get( /** * @brief Insert a node on a chain * - * This routine inserts \a the_node on a chain immediately following - * \a after_node. + * This routine inserts @a the_node on a chain immediately following + * @a after_node. * - * @note It disables interrupts to insure the atomicity + * @note It disables interrupts to ensure the atomicity * of the extract operation. */ void _Chain_Insert( @@ -166,9 +174,9 @@ void _Chain_Insert( /** * @brief Append a node on the end of a chain * - * This routine appends \a the_node onto the end of \a the_chain. + * This routine appends @a the_node onto the end of @a the_chain. * - * @note It disables interrupts to insure the atomicity of the + * @note It disables interrupts to ensure the atomicity of the * append operation. */ void _Chain_Append( diff --git a/cpukit/score/include/rtems/score/context.h b/cpukit/score/include/rtems/score/context.h index 5c7e0fa3b9..87c61957ba 100644 --- a/cpukit/score/include/rtems/score/context.h +++ b/cpukit/score/include/rtems/score/context.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,7 @@ /** * @defgroup ScoreContext Context Handler * - * This group contains functionality which abstracts thread context + * This handler encapsulates functionality which abstracts thread context * management in a portable manner. */ /**@{*/ @@ -33,14 +33,16 @@ extern "C" { #include /** - * @ingroup ScoreContext + * @brief Size of Floating Point Context Area + * * This constant defines the number of bytes required * to store a full floating point context. */ #define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE /** - * @ingroup ScoreContext + * @brief Is Context Switch Needed? + * * 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. @@ -49,54 +51,56 @@ extern "C" { SCORE_EXTERN volatile boolean _Context_Switch_necessary; /** - * @ingroup ScoreContext + * @brief Initialize Context Area * 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 + * @param[in] _the_context will be initialized + * @param[in] _stack 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 + * @param[in] _size is the size in octets of the thread's context + * @param[in] _isr is the ISR enable level for this thread + * @param[in] _entry is this thread's entry point + * @param[in] _is_fp is set to TRUE if this thread has floating point * enabled */ -#define \ - _Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) \ +#define _Context_Initialize(_the_context, _stack, _size, _isr, _entry, _is_fp) \ _CPU_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) /** - * @ingroup ScoreContext + * @brief Perform Context Switch + * * This routine saves the current context into the @a _executing * context record and restores the context specified by @a _heir. * - * @param _executing (in) is the currently executing thread's context - * @param _heir (in) is the context of the thread to be switched to + * @param[in] _executing is the currently executing thread's context + * @param[in] _heir is the context of the thread to be switched to */ #define _Context_Switch( _executing, _heir ) \ _CPU_Context_switch( _executing, _heir ) /** - * @ingroup ScoreContext + * @brief Restart Currently Executing Thread + * * 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 + * @param[in] _the_context is the context of the thread to restart */ #define _Context_Restart_self( _the_context ) \ _CPU_Context_Restart_self( _the_context ) /** - * @ingroup ScoreContext + * @brief Return Starting Address of Floating Point Context + * * 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 + * @param[in] _base is lowest physical address of the floating point * context save area. - * @param _offset (in) is XXX + * @param[in] _offset is the offset into the floating point area * * @return the initial FP context pointer */ @@ -104,34 +108,37 @@ SCORE_EXTERN volatile boolean _Context_Switch_necessary; _CPU_Context_Fp_start( (_base), (_offset) ) /** - * @ingroup ScoreContext + * @brief Initialize Floating Point Context Area + * * 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 + * @param[in] _fp_area 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 ) /** - * @ingroup ScoreContext + * @brief Restore Floating Point Context Area + * * 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. * - * @param _fp (in) points to the floating point context area to restore. + * @param[in] _fp points to the floating point context area to restore. */ #define _Context_Restore_fp( _fp ) \ _CPU_Context_restore_fp( _fp ) /** - * @ingroup ScoreContext + * @brief Save Floating Point Context Area + * * This routine saves the current floating point context * in the @a _fp area. * - * @param _fp (in) points to the floating point context area to restore. + * @param[in] _fp points to the floating point context area to restore. */ #define _Context_Save_fp( _fp ) \ _CPU_Context_save_fp( _fp ) diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h index 55817f3ff4..08343a1e19 100644 --- a/cpukit/score/include/rtems/score/coremsg.h +++ b/cpukit/score/include/rtems/score/coremsg.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,7 @@ /** * @defgroup ScoreMessageQueue Message Queue Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Message Queue services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -38,6 +38,8 @@ extern "C" { #include /** + * @brief Message Queue MP Callback Prototype + * * The following type defines the callout which the API provides * to support global/multiprocessor operations on message_queues. */ @@ -47,6 +49,8 @@ typedef void ( *CORE_message_queue_API_mp_support_callout )( ); /** + * @brief Message Buffer Contents Management Structure + * * The following defines the data types needed to manipulate * the contents of message buffers. * @@ -61,6 +65,8 @@ typedef struct { } CORE_message_queue_Buffer; /** + * @brief Message Structure + * * The following records define the organization of a message * buffer. */ @@ -74,7 +80,10 @@ typedef struct { } CORE_message_queue_Buffer_control; /** - * Blocking disciplines for a message queue. + * @brief Message Queue Blocking Disciplines + * + * This enumerated types defines the possible blocking disciplines + * for a message queue. */ typedef enum { /** This value indicates that pending messages are in FIFO order. */ @@ -84,19 +93,25 @@ typedef enum { } CORE_message_queue_Disciplines; /** + * @brief Message Priority for Appending + * * This is the priority constant used when appending messages onto * a message queue. */ #define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX /** + * @brief Message Priority for Prepending + * * 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 + * @brief Message Insertion Operation Types + * + * The following 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. * @@ -106,7 +121,10 @@ typedef enum { typedef int CORE_message_queue_Submit_types; /** - * Core Message queue handler return statuses. + * @brief Core Message Queue Return Statuses + * + * This enumerated type defines the possible set of Core Message + * Queue handler return statuses. */ typedef enum { /** This value indicates the operation completed sucessfully. */ @@ -132,6 +150,8 @@ typedef enum { } CORE_message_queue_Status; /** + * @brief Message Queue Attributes Type + * * The following defines the control block used to manage the * attributes of each message queue. */ @@ -141,6 +161,8 @@ typedef struct { } CORE_message_queue_Attributes; /** + * @brief Message Queue Notification Callback Prototype + * * 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. @@ -148,8 +170,10 @@ typedef struct { typedef void (*CORE_message_queue_Notify_Handler)( void * ); /** + * @brief Core Message Queue Control Structure + * * The following defines the control block used to manage each - * counting message_queue. + * Message Queue */ typedef struct { /** This field is the Waiting Queue used to manage the set of tasks @@ -193,14 +217,16 @@ typedef struct { } CORE_message_queue_Control; /** - * This routine initializes the message_queue based on the parameters passed. + * @brief Initialize a Message Queue * - * @param the_message_queue (in) points to the message queue to initialize - * @param the_message_queue_attributes (in) points to the attributes that + * This routine initializes @a the_message_queue based on the parameters passed. + * + * @param[in] the_message_queue points to the message queue to initialize + * @param[in] the_message_queue_attributes points to the attributes that * will be used with this message queue instance - * @param maximum_pending_messages (in) is the maximum number of messages + * @param[in] maximum_pending_messages 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 + * @param[in] maximum_message_size 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, @@ -215,13 +241,15 @@ boolean _CORE_message_queue_Initialize( ); /** + * @brief Close a Message Queue + * * This function closes a message by returning all allocated space and - * flushing the message_queue's task wait queue. + * flushing @a 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 + * @param[in] the_message_queue points to the message queue to close + * @param[in] remote_extract_callout 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 + * @param[in] status is the status that each waiting thread will return * from it's blocking service */ void _CORE_message_queue_Close( @@ -231,50 +259,60 @@ void _CORE_message_queue_Close( ); /** - * This function flushes the message_queue's pending message queue. The + * @brief Flush Pending Messages + * + * This function flushes @a 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 + * @param[in] the_message_queue points to the message queue to flush + * + * @return This method returns the number of message pending messages flushed. */ uint32_t _CORE_message_queue_Flush( CORE_message_queue_Control *the_message_queue ); /** + * @brief Flush Messages Support Routine + * * 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 + * @param[in] the_message_queue points to the message queue to flush + * + * @return This method returns the number of message pending messages flushed. */ uint32_t _CORE_message_queue_Flush_support( CORE_message_queue_Control *the_message_queue ); /** - * This function flushes the threads which are blocked on this - * message_queue's pending message queue. They are unblocked whether - * blocked sending or receiving. + * @brief Flush Waiting Threads. + * + * This function flushes the threads which are blocked on + * @a the_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 + * @param[in] the_message_queue points to the message queue to flush */ void _CORE_message_queue_Flush_waiting_threads( CORE_message_queue_Control *the_message_queue ); /** + * @brief Broadcast a Message to the Message Queue + * * 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. + * @param[in] the_message_queue points to the message queue + * @param[in] buffer is the starting address of the message to broadcast + * @param[in] size is the size of the message being broadcast + * @param[in] id 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 + * @param[in] api_message_queue_mp_support 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 + * @param[out] count 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 @@ -289,6 +327,8 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( ); /** + * @brief Submit a Message to the Message Queue + * * This routine implements the send and urgent message functions. It * processes a message that is to be submitted to the designated * message queue. The message will either be processed as a @@ -296,18 +336,18 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( * or it will be processed as an urgent message which will be inserted * 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. + * @param[in] the_message_queue points to the message queue + * @param[in] buffer is the starting address of the message to send + * @param[in] size is the size of the message being send + * @param[in] id 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 + * @param[in] api_message_queue_mp_support 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, + * @param[in] submit_type determines whether the message is prepended, * appended, or enqueued in priority order. - * @param wait (in) indicates whether the calling thread is willing to block + * @param[in] wait 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 + * @param[in] timeout 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 */ @@ -323,21 +363,23 @@ CORE_message_queue_Status _CORE_message_queue_Submit( ); /** + * @brief Size a Message from the Message Queue + * * This kernel routine dequeues a message, copies the message buffer to * a given destination buffer, and frees the message buffer to the * inactive message pool. The thread will be blocked if wait is TRUE, * otherwise an error will be given to the thread if no messages are available. * - * @param the_message_queue (in) points to the message queue - * @param id (in) is the RTEMS object Id associated with this message queue. + * @param[in] the_message_queue points to the message queue + * @param[in] id 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 + * @param[in] buffer 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 + * @param[in] size 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 + * @param[in] wait 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 + * @param[in] timeout 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 @@ -357,9 +399,9 @@ void _CORE_message_queue_Seize( * 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, + * @param[in] the_message_queue points to the message queue + * @param[in] the_message is the message to enqueue + * @param[in] submit_type determines whether the message is prepended, * appended, or enqueued in priority order. */ void _CORE_message_queue_Insert_message( diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h index 1d95f8265e..4015ac97e4 100644 --- a/cpukit/score/include/rtems/score/coremutex.h +++ b/cpukit/score/include/rtems/score/coremutex.h @@ -8,7 +8,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,7 +24,7 @@ /** * @defgroup ScoreMutex Mutex Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Mutex services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -41,6 +41,8 @@ extern "C" { #include /** + * @brief MP Support Callback Prototype + * * The following type defines the callout which the API provides * to support global/multiprocessor operations on mutexes. */ @@ -50,7 +52,9 @@ typedef void ( *CORE_mutex_API_mp_support_callout )( ); /** - * Blocking disciplines for a mutex. + * @brief Blocking Disciplines Enumerated Type + * + * This enumerated type defines the blocking disciplines for a mutex. */ typedef enum { /** This specifies that threads will wait for the mutex in FIFO order. */ @@ -68,7 +72,9 @@ typedef enum { } CORE_mutex_Disciplines; /** - * Mutex handler return statuses. + * @brief Mutex method return statuses + * + * This enumerated type defines the possible Mutex handler return statuses. */ typedef enum { /** This status indicates that the operation completed successfully. */ @@ -102,32 +108,35 @@ typedef enum { } CORE_mutex_Status; /** - * Mutex lock nesting behavior - * - * + CORE_MUTEX_NESTING_ACQUIRES: - * This sequence has no blocking or errors: - * - * + lock(m) - * + lock(m) - * + unlock(m) - * + unlock(m) + * @brief Mutex Lock Nesting Behavior Enumeration * - * + 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 - * This sequence performs as indicated: - * + lock(m) - * + lock(m) - deadlocks or timeouts - * + unlock(m) - releases + * This enumerated type defines the possible behaviors for + * lock nesting. */ typedef enum { + /** + * This sequence has no blocking or errors: + * + * + lock(m) + * + lock(m) + * + unlock(m) + * + unlock(m) + */ CORE_MUTEX_NESTING_ACQUIRES, + /** + * This sequence returns an error at the indicated point: + * + * + lock(m) + * + lock(m) - already locked error + * + unlock(m) + */ CORE_MUTEX_NESTING_IS_ERROR, + /** + * This sequence performs as indicated: + * + lock(m) + * + lock(m) - deadlocks or timeouts + * + unlock(m) - releases + */ CORE_MUTEX_NESTING_BLOCKS } CORE_mutex_Nesting_behaviors; @@ -142,6 +151,8 @@ typedef enum { #define CORE_MUTEX_LOCKED 0 /** + * @brief Core Mutex Attributes + * * The following defines the control block used to manage the * attributes of each mutex. */ @@ -165,6 +176,8 @@ typedef struct { } CORE_mutex_Attributes; /** + * @brief Core Mutex Control Structure + * * The following defines the control block used to manage each mutex. */ typedef struct { @@ -195,13 +208,14 @@ typedef struct { } CORE_mutex_Control; /** + * @brief Initialize a Core Mutex * * 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 + * @param[in] the_mutex is the mutex to initalize + * @param[in] the_mutex_attributes is the attributes associated with this * mutex instance - * @param initial_lock (in) is the initial value of the mutex + * @param[in] initial_lock is the initial value of the mutex */ void _CORE_mutex_Initialize( CORE_mutex_Control *the_mutex, @@ -211,13 +225,20 @@ void _CORE_mutex_Initialize( #ifndef __RTEMS_APPLICATION__ /** + * @brief Seize Mutex with Quick Success Path + * * 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 * returns. Otherwise, the calling task is blocked until a unit becomes * available. * - * @param the_mutex (in) is the mutex to attempt to lock - * @param level_p (in) is the interrupt level holder + * @param[in] the_mutex is the mutex to attempt to lock + * @param[in] level_p is the interrupt level holder + * + * @return This routine returns 0 if "trylock" can resolve whether or not + * the mutex is immediately obtained or there was an error attempting to + * get it. It returns 1 to indicate that the caller cannot obtain + * the mutex and will have to block to do so. * * @note For performance reasons, this routine is implemented as * a macro that uses two support routines. @@ -228,12 +249,14 @@ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock( ); /** + * @brief Seize Mutex with Blockign + * * 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 + * @param[in] the_mutex is the mutex to attempt to lock + * @param[in] timeout is the maximum number of ticks to block */ void _CORE_mutex_Seize_interrupt_blocking( CORE_mutex_Control *the_mutex, @@ -241,16 +264,22 @@ void _CORE_mutex_Seize_interrupt_blocking( ); /** + * @brief Sieze Interrupt Wrapper + * * 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 + * @param[in] _the_mutex is the mutex to attempt to lock + * @param[in] _id is the Id of the owning API level Semaphore object + * @param[in] _wait is TRUE if the thread is willing to wait + * @param[in] _timeout is the maximum number of ticks to block + * @param[in] _level is a temporary variable used to contain the ISR * disable level cookie + * + * @note If the mutex is called from an interrupt service routine, + * with context switching disabled, or before multitasking, + * then a fatal error is generated. */ #define _CORE_mutex_Seize( \ _the_mutex, _id, _wait, _timeout, _level ) \ @@ -281,13 +310,15 @@ void _CORE_mutex_Seize_interrupt_blocking( } while (0) /** + * @brief Surrender the Mutex + * * 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 + * @param[in] the_mutex is the mutex to surrender + * @param[in] id is the id of the RTEMS Object associated with this mutex + * @param[in] api_mutex_mp_support is the routine that will be called when * unblocking a remote mutex * * @return an indication of whether the routine succeeded or failed @@ -299,13 +330,15 @@ CORE_mutex_Status _CORE_mutex_Surrender( ); /** + * @brief Flush all waiting threads + * * 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 + * @param[in] the_mutex is the mutex to flush + * @param[in] remote_extract_callout is the routine to invoke when a remote * thread is extracted - * @param status (in) is the status value which each unblocked thread will + * @param[in] status is the status value which each unblocked thread will * return to its caller. */ void _CORE_mutex_Flush( diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h index 866e59d360..54621fce84 100644 --- a/cpukit/score/include/rtems/score/coresem.h +++ b/cpukit/score/include/rtems/score/coresem.h @@ -8,7 +8,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,7 +24,7 @@ /** * @defgroup ScoreSemaphore Semaphore Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Semaphore services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -118,9 +118,9 @@ typedef struct { /** * 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 + * @param[in] the_semaphore is the semaphore to initialize + * @param[in] the_semaphore_attributes define the behavior of this instance + * @param[in] initial_value is the initial count of the semaphore */ void _CORE_semaphore_Initialize( CORE_semaphore_Control *the_semaphore, @@ -134,11 +134,11 @@ void _CORE_semaphore_Initialize( * 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 + * @param[in] the_semaphore is the semaphore to seize + * @param[in] id 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 + * @param[in] wait is TRUE if the calling thread is willing to wait + * @param[in] timeout is the number of ticks the calling thread is willing * to wait if @a wait is TRUE. */ void _CORE_semaphore_Seize( @@ -153,10 +153,10 @@ void _CORE_semaphore_Seize( * 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 + * @param[in] the_semaphore is the semaphore to surrender + * @param[in] id 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 + * @param[in] api_semaphore_mp_support is the routine to invoke if the * thread unblocked is remote * * @return an indication of whether the routine succeeded or failed @@ -171,10 +171,10 @@ CORE_semaphore_Status _CORE_semaphore_Surrender( * 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 + * @param[in] the_semaphore is the semaphore to flush + * @param[in] remote_extract_callout is the routine to invoke if the * thread unblocked is remote - * @param status (in) is the status to be returned to the unblocked thread + * @param[in] status is the status to be returned to the unblocked thread */ void _CORE_semaphore_Flush( CORE_semaphore_Control *the_semaphore, diff --git a/cpukit/score/include/rtems/score/heap.h b/cpukit/score/include/rtems/score/heap.h index 4ec7396854..c00e2c7098 100644 --- a/cpukit/score/include/rtems/score/heap.h +++ b/cpukit/score/include/rtems/score/heap.h @@ -18,7 +18,7 @@ * required to be multiple of CPU_ALIGNMENT and explicitly not * required to be a power of two. * - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -34,7 +34,7 @@ /** * @defgroup ScoreHeap Heap Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Heap services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -251,12 +251,14 @@ typedef struct { * @a page_size byte units. If @a page_size is 0 or is not multiple of * CPU_ALIGNMENT, it's aligned up to the nearest CPU_ALIGNMENT boundary. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the memory for + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address 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 + * @param[in] size is the size in bytes of the memory area for the heap + * @param[in] page_size is the size in bytes of the allocation unit + * + * @return This method returns the maximum memory available. If + * unsuccessful, 0 will be returned. */ uint32_t _Heap_Initialize( Heap_Control *the_heap, @@ -269,11 +271,11 @@ uint32_t _Heap_Initialize( * 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 + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address 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 + * @param[in] size is the size in bytes of the memory area to add + * @param[in] amount_extended 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 */ @@ -289,8 +291,8 @@ Heap_Extend_status _Heap_Extend( * @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 + * @param[in] the_heap is the heap to operate upon + * @param[in] size is the amount of memory to allocate in bytes * @return NULL if unsuccessful and a pointer to the block if successful */ void *_Heap_Allocate( @@ -307,9 +309,9 @@ void *_Heap_Allocate( * Returns pointer to the start of the memory block if success, NULL if * failure. * - * @param the_heap (in) is the heap to operate upon - * @param size (in) is the amount of memory to allocate in bytes - * @param alignment (in) the required alignment + * @param[in] the_heap is the heap to operate upon + * @param[in] size is the amount of memory to allocate in bytes + * @param[in] alignment the required alignment * @return NULL if unsuccessful and a pointer to the block if successful */ void *_Heap_Allocate_aligned( @@ -325,10 +327,10 @@ void *_Heap_Allocate_aligned( * Returns TRUE if the @a starting_address is in 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 + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address 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 + * @param[in] size 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 */ @@ -338,17 +340,17 @@ boolean _Heap_Size_of_user_area( size_t *size ); -/* +/** * This function tries to resize in place the block that is pointed to by the * @a starting_address to the new @a size. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the user block + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address is the starting address of the user block * to be resized - * @param size (in) is the new size - * @param old_mem_size (in) points to a user area to return the size of the + * @param[in] size is the new size + * @param[in] old_mem_size points to a user area to return the size of the * user memory area of the block before resizing. - * @param avail_mem_size (in) points to a user area to return the size of + * @param[in] avail_mem_size points to a user area to return the size of * the user memory area of the free block that has been enlarged or * created due to resizing, 0 if none. * @return HEAP_RESIZE_SUCCESSFUL if successfully able to resize the block, @@ -373,8 +375,8 @@ Heap_Resize_status _Heap_Resize_block( * 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 + * @param[in] the_heap is the heap to operate upon + * @param[in] start_address is the starting address of the user block * to free * @return TRUE if successfully freed, FALSE otherwise */ @@ -386,12 +388,12 @@ boolean _Heap_Free( /** * 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 + * @param[in] the_heap is the heap to operate upon + * @param[in] source is a user specified integer which may be used to + * indicate where in the application this was invoked from + * @param[in] do_dump is set to TRUE if errors should be printed * @return TRUE if the test passed fine, FALSE otherwise. */ - boolean _Heap_Walk( Heap_Control *the_heap, int source, @@ -402,8 +404,8 @@ boolean _Heap_Walk( * This routine walks the heap and tots up the free and allocated * sizes. * - * @param the_heap (in) pointer to heap header - * @param the_info (in) pointer to a status information area + * @param[in] the_heap pointer to heap header + * @param[in] the_info pointer to a status information area * @return *the_info is filled with status information * @return 0=success, otherwise heap is corrupt. */ @@ -416,12 +418,11 @@ Heap_Get_information_status _Heap_Get_information( * This heap routine returns information about the free blocks * in the specified heap. * - * @param the_heap (in) pointer to heap header. - * @param info (in) pointer to the free block information. + * @param[in] the_heap pointer to heap header. + * @param[in] info pointer to the free block information. * * @return free block information filled in. */ - void _Heap_Get_free_information( Heap_Control *the_heap, Heap_Information *info @@ -429,27 +430,53 @@ void _Heap_Get_free_information( #if !defined(__RTEMS_APPLICATION__) -/* +/** * A pointer to unsigned integer conversion. */ #define _H_p2u(_p) ((_H_uptr_t)(_p)) #include -/* - * Internal routines shared by _Heap_Allocate() and _Heap_Allocate_aligned(). - * Refer to 'heap.c' for details. +/** + * Convert user requested 'size' of memory block to the block size. + * + * @note This is an internal routine used by _Heap_Allocate() and + * _Heap_Allocate_aligned(). Refer to 'heap.c' for details. + * + * @param[in] size is the size of the block requested + * @param[in] page_size is the page size of this heap instance + * @param[in] min_size is minimum size block that should be allocated + * from this heap instance + * + * @return This method returns block size on success, 0 if overflow occured. */ - extern uint32_t _Heap_Calc_block_size( uint32_t size, uint32_t page_size, - uint32_t min_size); + uint32_t min_size +); +/** + * This method allocates a block of size @a alloc_size from @a the_block + * belonging to @a the_heap. Split @a the_block if possible, otherwise + * allocate it entirely. When split, make the lower part used, and leave + * the upper part free. + * + * This is an internal routines used by _Heap_Allocate() and + * _Heap_Allocate_aligned(). Refer to 'heap.c' for details. + * + * @param[in] the_heap is the heap to operate upon + * @param[in] the_block is the block to allocates the requested size from + * @param[in] alloc_size is the requested number of bytes to take out of + * the block + * + * @return This methods returns the size of the allocated block. + */ extern uint32_t _Heap_Block_allocate( Heap_Control* the_heap, - Heap_Block* the_block, - uint32_t alloc_size); + Heap_Block* the_block, + uint32_t alloc_size +); /* * Debug support @@ -459,16 +486,14 @@ extern uint32_t _Heap_Block_allocate( #define RTEMS_HEAP_DEBUG #endif -#if defined(RTEMS_HEAP_DEBUG) - -#include - -/* +/** * We do asserts only for heaps with instance number greater than 0 assuming * that the heap used for malloc is initialized first and thus has instance * number 0. Asserting malloc heap may lead to troubles as printf may invoke * malloc thus probably leading to infinite recursion. */ +#if defined(RTEMS_HEAP_DEBUG) +#include #define _HAssert(cond_) \ do { \ diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h index cdc4551b84..a9fb98c0ae 100644 --- a/cpukit/score/include/rtems/score/interr.h +++ b/cpukit/score/include/rtems/score/interr.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,7 @@ /** * @defgroup ScoreIntErr Internal Error Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Semaphore services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -42,7 +42,7 @@ typedef enum { INTERNAL_ERROR_ITRON_API } Internal_errors_Source; -/* +/** * A list of errors which are generated internally by the executive core. */ typedef enum { @@ -65,16 +65,19 @@ typedef enum { INTERNAL_ERROR_BAD_ATTRIBUTES } Internal_errors_Core_list; -/* +/** * This type holds the fatal error information. */ typedef struct { + /** This is the source of the error. */ Internal_errors_Source the_source; + /** This indicates if the error is internal of external. */ boolean is_internal; + /** This is the error code. */ uint32_t the_error; } Internal_errors_Information; -/* +/** * When a fatal error occurs, the error information is stored here. */ SCORE_EXTERN Internal_errors_Information Internal_errors_What_happened; diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h index 45a4f1f676..320332dfd7 100644 --- a/cpukit/score/include/rtems/score/isr.h +++ b/cpukit/score/include/rtems/score/isr.h @@ -8,7 +8,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,7 +24,7 @@ /** * @defgroup ScoreISR ISR Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * ISR services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -123,7 +123,7 @@ void _ISR_Handler_initialization ( void ); * critical code when a point is reached at which interrupts can * be temporarily enabled. Deciding where to flash interrupts * in a long critical section is often difficult and the point - * must be selected with care to insure that the critical section + * must be selected with care to ensure that the critical section * properly protects itself. */ #define _ISR_Flash( _level ) \ @@ -158,7 +158,7 @@ void _ISR_Handler_initialization ( void ); * interrupt service routine is invoked. After the application's * interrupt service routine returns control to this routine, it * will determine if a thread dispatch is necessary. If so, it will - * insure that the necessary thread scheduling operations are + * ensure that the necessary thread scheduling operations are * performed when the outermost interrupt service routine exits. * * @note Implemented in assembly language. diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h index cf82d2f3eb..d6fc3aa0c1 100644 --- a/cpukit/score/include/rtems/score/mpci.h +++ b/cpukit/score/include/rtems/score/mpci.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,8 +22,12 @@ /** * @defgroup ScoreMPCI MPCI Handler * - * This group contains functionality which XXX - */ + * The MPCI Handler encapsulates functionality which is related to the + * generation, receipt, and processing of remote operations in a + * multiprocessor system. This handler contains the message passing + * support for making remote service calls as well as the server thread + * which processes requests from remote nodes. +*/ /**@{*/ #ifdef __cplusplus @@ -38,7 +42,7 @@ extern "C" { #include #include -/* +/** * The following constants define the stack size requirements for * the system threads. */ @@ -48,12 +52,12 @@ extern "C" { _CPU_Table.extra_mpci_receive_server_stack \ ) -/* +/** * The following defines the node number used when a broadcast is desired. */ #define MPCI_ALL_NODES 0 -/* +/** * For packets associated with requests that don't already have a timeout, * use the one specified by this MPCI driver. The value specified by * the MPCI driver sets an upper limit on how long a remote request @@ -61,71 +65,83 @@ extern "C" { */ #define MPCI_DEFAULT_TIMEOUT 0xFFFFFFFF -/* - * The following records define the Multiprocessor Communications - * Interface (MPCI) Table. This table defines the user-provided - * MPCI which is a required part of a multiprocessor system. - * - * For non-blocking local operations that become remote operations, - * we need a timeout. This is a per-driver timeout: default_timeout - */ - /** * This type is returned by all user provided MPCI routines. */ typedef void MPCI_Entry; /** - * This type is XXX + * This type defines the prototype for the initization entry point + * in an Multiprocessor Communications Interface. */ typedef MPCI_Entry ( *MPCI_initialization_entry )( void ); /** - * This type is XXX + * This type defines the prototype for the get packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to the packet allocated. */ typedef MPCI_Entry ( *MPCI_get_packet_entry )( - MP_packet_Prefix ** - ); + MP_packet_Prefix ** + ); /** - * This type is XXX + * This type defines the prototype for the return packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to a packet previously allocated by the + * get packet MPCI entry. */ typedef MPCI_Entry ( *MPCI_return_packet_entry )( - MP_packet_Prefix * - ); + MP_packet_Prefix * + ); /** - * This type is XXX + * This type defines the prototype for send get packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to a packet previously allocated by the + * get packet entry point that has been filled in by the caller. */ typedef MPCI_Entry ( *MPCI_send_entry )( - uint32_t , - MP_packet_Prefix * - ); + uint32_t, + MP_packet_Prefix * + ); /** - * This type is XXX + * This type defines the prototype for the receive packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to a packet allocated and filled in by the + * receive packet handler. The caller will block until a packet is + * received. */ typedef MPCI_Entry ( *MPCI_receive_entry )( - MP_packet_Prefix ** - ); + MP_packet_Prefix ** + ); /** - * This type is XXX + * This type defines the Multiprocessor Communications + * Interface (MPCI) Table. This table defines the user-provided + * MPCI which is a required part of a multiprocessor system. + * + * For non-blocking local operations that become remote operations, + * we need a timeout. This is a per-driver timeout: default_timeout */ typedef struct { - /** timeout for MPCI operations in ticks */ + /** This fields contains the timeout for MPCI operations in ticks. */ uint32_t default_timeout; - /** XXX */ + /** This field contains the maximum size of a packet supported by this + * MPCI layer. This size places a limit on the size of a message + * which can be transmitted over this interface. + **/ uint32_t maximum_packet_size; - /** XXX */ + /** This field points to the MPCI initialization entry point. */ MPCI_initialization_entry initialization; - /** XXX */ + /** This field points to the MPCI get packet entry point. */ MPCI_get_packet_entry get_packet; - /** XXX */ + /** This field points to the MPCI return packet entry point. */ MPCI_return_packet_entry return_packet; - /** XXX */ + /** This field points to the MPCI send packet entry point. */ MPCI_send_entry send_packet; - /** XXX */ + /** This field points to the MPCI receive packet entry point. */ MPCI_receive_entry receive_packet; } MPCI_Control; @@ -148,13 +164,17 @@ typedef enum { * remote event operations. */ typedef struct { - /** XXX */ + /** This field is the general header for all packets. */ MP_packet_Prefix Prefix; - /** XXX */ + /** This value specifies the operation. */ MPCI_Internal_Remote_operations operation; - /** XXX */ + /** This is the maximum number of nodes in the system. It must agree + * on all nodes. + */ uint32_t maximum_nodes; - /** XXX */ + /** This field is the maximum number of concurrently existent + * globally offered objects. + */ uint32_t maximum_global_objects; } MPCI_Internal_packet; @@ -189,6 +209,12 @@ SCORE_EXTERN MPCI_Packet_processor /** * This routine performs the initialization necessary for this handler. + * + * @param[in] users_mpci_table is a pointer to the application configured + * MPCI Table. This table contains pointers to the MPCI Layers + * entry points. + * @param[in] timeout_status is the value which should be returned to + * blocking threads when they timeout on a remote operation. */ void _MPCI_Handler_initialization( MPCI_Control *users_mpci_table, @@ -209,6 +235,11 @@ void _MPCI_Initialization ( void ); /** * This routine registers the MPCI packet processor for the * designated object class. + * + * @param[in] the_class is the class indicator for packets which will + * be processed by @a the_packet_processor method. + * @param[in] the_packet_processor is a pointer to a method which is + * invoked when packets with @a the_class are received. */ void _MPCI_Register_packet_processor( MP_packet_Classes the_class, @@ -219,12 +250,18 @@ void _MPCI_Register_packet_processor( /** * This function obtains a packet by invoking the user provided * MPCI get packet callout. + * + * @return This method returns a pointer to a MPCI packet which can be + * filled in by the caller and used to perform a subsequent + * remote operation. */ MP_packet_Prefix *_MPCI_Get_packet ( void ); /** - * This routine returns a packet by invoking the user provided + * This routine deallocates a packet by invoking the user provided * MPCI return packet callout. + * + * @param[in] the_packet is the MP packet to deallocate. */ void _MPCI_Return_packet ( MP_packet_Prefix *the_packet @@ -233,6 +270,9 @@ void _MPCI_Return_packet ( /** * This routine sends a process packet by invoking the user provided * MPCI send callout. + * + * @param[in] destination is the node which should receive this packet. + * @param[in] the_packet is the packet to be sent. */ void _MPCI_Send_process_packet ( uint32_t destination, @@ -242,8 +282,17 @@ void _MPCI_Send_process_packet ( /** * This routine sends a request packet by invoking the user provided * MPCI send callout. + * + * @param[in] destination is the node which should receive this packet. + * @param[in] the_packet is the packet to be sent. + * @param[in] extra_state is the extra thread state bits which should be + * set in addition to the remote operation pending state. It + * may indicate the caller is blocking on a message queue + * operation. + * + * @return This method returns the operation status from the remote node. */ -uint32_t _MPCI_Send_request_packet ( +uint32_t _MPCI_Send_request_packet ( uint32_t destination, MP_packet_Prefix *the_packet, States_Control extra_state @@ -252,6 +301,9 @@ uint32_t _MPCI_Send_request_packet ( /** * This routine sends a response packet by invoking the user provided * MPCI send callout. + * + * @param[in] destination is the node which should receive this packet. + * @param[in] the_packet is the packet to be sent. */ void _MPCI_Send_response_packet ( uint32_t destination, @@ -261,12 +313,20 @@ void _MPCI_Send_response_packet ( /** * This routine receives a packet by invoking the user provided * MPCI receive callout. + * + * @return This method returns the packet received. */ MP_packet_Prefix *_MPCI_Receive_packet ( void ); /** - * This routine obtains a packet by invoking the user provided - * MPCI get packet callout. + * This routine is responsible for passing @a the_packet to the thread + * waiting on the remote operation to complete. The unblocked thread is + * responsible for eventually freeing @a the_packet. + * + * @param[in] the_packet is the response packet to be processed. + * + * @return This method returns a pointer to the thread which was if unblocked + * or NULL if the waiting thread no longer exists. */ Thread_Control *_MPCI_Process_response ( MP_packet_Prefix *the_packet @@ -274,6 +334,8 @@ Thread_Control *_MPCI_Process_response ( /** * This is the server thread which receives and processes all MCPI packets. + * + * @param[in] ignored is the thread argument. It is not used. */ Thread _MPCI_Receive_server( uint32_t ignored @@ -287,12 +349,14 @@ void _MPCI_Announce ( void ); /** * This routine performs a remote procedure call so that a * process operation can be performed on another node. + * + * @param[in] operation is the remote operation to perform. */ void _MPCI_Internal_packets_Send_process_packet ( MPCI_Internal_Remote_operations operation ); -/* +/** * _MPCI_Internal_packets_Send_request_packet * * This routine performs a remote procedure call so that a @@ -302,7 +366,7 @@ void _MPCI_Internal_packets_Send_process_packet ( * packets to be sent by this manager. */ -/* +/** * _MPCI_Internal_packets_Send_response_packet * * This routine performs a remote procedure call so that a @@ -320,7 +384,7 @@ void _MPCI_Internal_packets_Process_packet ( MP_packet_Prefix *the_packet_prefix ); -/* +/** * _MPCI_Internal_packets_Send_object_was_deleted * * This routine is invoked indirectly by the thread queue @@ -331,7 +395,7 @@ void _MPCI_Internal_packets_Process_packet ( * deleted by this manager. */ -/* +/** * _MPCI_Internal_packets_Send_extract_proxy * * This routine is invoked when a task is deleted and it diff --git a/cpukit/score/include/rtems/score/mppkt.h b/cpukit/score/include/rtems/score/mppkt.h index 1867ae45a9..b194610500 100644 --- a/cpukit/score/include/rtems/score/mppkt.h +++ b/cpukit/score/include/rtems/score/mppkt.h @@ -9,7 +9,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -25,7 +25,9 @@ /** * @defgroup ScoreMPPacket MP Packet Handler * - * This group contains functionality which XXX + * This handler encapsulates the primary definition of MPCI packets. This + * handler defines the part of the packet that is common to all remote + * operations. */ /**@{*/ @@ -56,12 +58,12 @@ typedef enum { } MP_packet_Classes; /** - * XXX + * This constant defines the first entry in the MP_packet_Classes enumeration. */ #define MP_PACKET_CLASSES_FIRST MP_PACKET_MPCI_INTERNAL /** - * XXX + * This constant defines the last entry in the MP_packet_Classes enumeration. */ #define MP_PACKET_CLASSES_LAST MP_PACKET_SIGNAL @@ -74,21 +76,21 @@ typedef enum { * alignment rule encountered yet. */ typedef struct { - /** XXX */ + /** This field indicates the API class of the operation being performed. */ MP_packet_Classes the_class; - /** XXX */ + /** This field is the id of the object to be acted upon. */ Objects_Id id; - /** XXX */ + /** This field is the ID of the originating thread. */ Objects_Id source_tid; - /** XXX */ + /** This field is the priority of the originating thread. */ Priority_Control source_priority; - /** XXX */ + /** This field is where the status of the operation will be returned. */ uint32_t return_code; - /** XXX */ + /** This field is the length of the data following the prefix. */ uint32_t length; - /** XXX */ + /** This field is the length of the data which required network conversion. */ uint32_t to_convert; - /** XXX */ + /** This field is the requested timeout for this operation. */ Watchdog_Interval timeout; } MP_packet_Prefix; diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index 145b003147..661f53eb11 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -8,7 +8,7 @@ * can be used to initialize and manipulate all objects which have * ids. * - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,25 +28,22 @@ extern "C" { #include #include -/* +/** * The following type defines the control block used to manage * object names. */ - typedef void * Objects_Name; -/* +/** * Space for object names is allocated in multiples of this. * * NOTE: Must be a power of 2. Matches the name manipulation routines. */ - #define OBJECTS_NAME_ALIGNMENT sizeof( uint32_t ) -/* +/** * Functions which compare names are prototyped like this. */ - typedef boolean (*Objects_Name_comparators)( void * /* name_1 */, void * /* name_2 */, @@ -54,7 +51,7 @@ typedef boolean (*Objects_Name_comparators)( ); #if defined(RTEMS_USE_16_BIT_OBJECT) -/* +/** * The following type defines the control block used to manage * object IDs. The format is as follows (0=LSB): * @@ -62,8 +59,12 @@ typedef boolean (*Objects_Name_comparators)( * Bits 8 .. 10 = API (up to 7 API classes) * Bits 11 .. 15 = class (up to 31 object types per API) */ - typedef uint16_t Objects_Id; + +/** + * This type is used to store the maximum number of allowed objects + * of each type. + */ typedef uint8_t Objects_Maximum; #define OBJECTS_INDEX_START_BIT 0 @@ -81,8 +82,11 @@ typedef uint8_t Objects_Maximum; #define OBJECTS_UNLIMITED_OBJECTS 0x8000 +#define OBJECTS_ID_INITIAL_INDEX (0) +#define OBJECTS_ID_FINAL_INDEX (0xff) + #else -/* +/** * The following type defines the control block used to manage * object IDs. The format is as follows (0=LSB): * @@ -91,39 +95,103 @@ typedef uint8_t Objects_Maximum; * Bits 24 .. 26 = API (up to 7 API classes) * Bits 27 .. 31 = class (up to 31 object types per API) */ - typedef uint32_t Objects_Id; + +/** + * This type is used to store the maximum number of allowed objects + * of each type. + */ typedef uint16_t Objects_Maximum; +/** + * This is the bit position of the starting bit of the index portion of + * the object Id. + */ #define OBJECTS_INDEX_START_BIT 0 + + +/** + * This is the bit position of the starting bit of the node portion of + * the object Id. + */ #define OBJECTS_NODE_START_BIT 16 + +/** + * This is the bit position of the starting bit of the API portion of + * the object Id. + */ #define OBJECTS_API_START_BIT 24 + +/** + * This is the bit position of the starting bit of the class portion of + * the object Id. + */ #define OBJECTS_CLASS_START_BIT 27 +/** + * This mask is used to extract the index portion of an object Id. + */ #define OBJECTS_INDEX_MASK (Objects_Id)0x0000ffff + +/** + * This mask is used to extract the node portion of an object Id. + */ #define OBJECTS_NODE_MASK (Objects_Id)0x00ff0000 + +/** + * This mask is used to extract the API portion of an object Id. + */ #define OBJECTS_API_MASK (Objects_Id)0x07000000 + +/** + * This mask is used to extract the class portion of an object Id. + */ #define OBJECTS_CLASS_MASK (Objects_Id)0xf8000000 +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the index portion of an object Id. + */ #define OBJECTS_INDEX_VALID_BITS (Objects_Id)0x0000ffff + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the node portion of an object Id. + */ #define OBJECTS_NODE_VALID_BITS (Objects_Id)0x000000ff + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the API portion of an object Id. + */ #define OBJECTS_API_VALID_BITS (Objects_Id)0x00000007 + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the class portion of an object Id. + */ #define OBJECTS_CLASS_VALID_BITS (Objects_Id)0x0000001f -/* +/** * Mask to enable unlimited objects. This is used in the configuration * table when specifying the number of configured objects. */ #define OBJECTS_UNLIMITED_OBJECTS 0x80000000 +/** + * This is the lowest value for the index portion of an object Id. + */ +#define OBJECTS_ID_INITIAL_INDEX (0) + +/** + * This is the highest value for the index portion of an object Id. + */ +#define OBJECTS_ID_FINAL_INDEX (0xff) #endif -/* +/** * This enumerated type is used in the class field of the object ID. */ - -#define OBJECTS_NO_CLASS 0 - typedef enum { OBJECTS_NO_API = 0, OBJECTS_INTERNAL_API = 1, @@ -132,16 +200,26 @@ typedef enum { OBJECTS_ITRON_API = 4 } Objects_APIs; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_APIS_LAST OBJECTS_ITRON_API +/** + * This enumerated type is used in the class field of the object ID + * for RTEMS internal object classes. + */ typedef enum { OBJECTS_INTERNAL_NO_CLASS = 0, OBJECTS_INTERNAL_THREADS = 1, OBJECTS_INTERNAL_MUTEXES = 2 } Objects_Internal_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES +/** + * This enumerated type is used in the class field of the object ID + * for the RTEMS Classic API. + */ typedef enum { OBJECTS_CLASSIC_NO_CLASS = 0, OBJECTS_RTEMS_TASKS = 1, @@ -155,8 +233,13 @@ typedef enum { OBJECTS_RTEMS_EXTENSIONS = 9 } Objects_Classic_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_EXTENSIONS +/** + * This enumerated type is used in the class field of the object ID + * for the POSIX API. + */ typedef enum { OBJECTS_POSIX_NO_CLASS = 0, OBJECTS_POSIX_THREADS = 1, @@ -169,8 +252,13 @@ typedef enum { OBJECTS_POSIX_CONDITION_VARIABLES = 8 } Objects_POSIX_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_CONDITION_VARIABLES +/** + * This enumerated type is used in the class field of the object ID + * for the ITRON API. + */ typedef enum { OBJECTS_ITRON_NO_CLASS = 0, OBJECTS_ITRON_TASKS = 1, @@ -183,161 +271,186 @@ typedef enum { OBJECTS_ITRON_FIXED_MEMORY_POOLS = 8 } Objects_ITRON_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS -/* +/** * This enumerated type lists the locations which may be returned * by _Objects_Get. These codes indicate the success of locating * an object with the specified ID. */ - typedef enum { OBJECTS_LOCAL = 0, /* object is local */ OBJECTS_REMOTE = 1, /* object is remote */ OBJECTS_ERROR = 2 /* id was invalid */ } Objects_Locations; -/* +/** * The following type defines the callout used when a local task * is extracted from a remote thread queue (i.e. it's proxy must * extracted from the remote queue). */ - typedef void ( *Objects_Thread_queue_Extract_callout )( void * ); -/* +/** * The following defines the Object Control Block used to manage * each object local to this node. */ - typedef struct { + /** This is the chain node portion of an object. */ Chain_Node Node; + /** This is the object's ID. */ Objects_Id id; + /** This is the object's name. */ Objects_Name name; } Objects_Control; -/* +/** * The following defines the structure for the information used to * manage each class of objects. */ - typedef struct { - Objects_APIs the_api; /* API of this object */ - uint16_t the_class; /* class of this object */ - Objects_Id minimum_id; /* minimum valid id of this type */ - Objects_Id maximum_id; /* maximum valid id of this type */ - Objects_Maximum maximum; /* maximum number of objects */ - boolean auto_extend; /* TRUE if unlimited objects */ - uint32_t allocation_size; /* number of objects in a block */ - uint32_t size; /* size of the objects */ + /** This field indicates the API of this object class. */ + Objects_APIs the_api; + /** This is the class of this object set. */ + uint16_t the_class; + /** This is the minimum valid id of this object class. */ + Objects_Id minimum_id; + /** This is the maximum valid id of this object class. */ + Objects_Id maximum_id; + /** This is the maximum number of objects in this class. */ + Objects_Maximum maximum; + /** This is the TRUE if unlimited objects in this class. */ + boolean auto_extend; + /** This is the number of objects in a block. */ + uint32_t allocation_size; + /** This is the size in bytes of each object instance. */ + uint32_t size; + /** This points to the table of local objects. */ Objects_Control **local_table; + /** This points to the table of local object names. */ Objects_Name *name_table; - Chain_Control Inactive; /* chain of inactive ctl blocks */ - Objects_Maximum inactive; /* number of objects on the InActive list */ - uint32_t *inactive_per_block; /* used to release a block */ - void **object_blocks; /* the object memory to remove */ - boolean is_string; /* TRUE if names are strings */ - uint16_t name_length; /* maximum length of names */ + /** This is the chain of inactive control blocks. */ + Chain_Control Inactive; + /** This is the number of objects on the Inactive list. */ + Objects_Maximum inactive; + /** This is the number of inactive objects per block. */ + uint32_t *inactive_per_block; + /** This is a table to the chain of inactive object memory blocks. */ + void **object_blocks; + /** This is the TRUE if names are strings. */ + boolean is_string; + /** This is the maximum length of names. */ + uint16_t name_length; + /** This is this object class' method called when extracting a thread. */ Objects_Thread_queue_Extract_callout extract; #if defined(RTEMS_MULTIPROCESSING) - Chain_Control *global_table; /* pointer to global table */ + /** This is this object class' pointer to the global name table */ + Chain_Control *global_table; #endif } Objects_Information; -/* - * The following defines the data storage which contains the - * node number of the local node. +/** + * The following is referenced to the node number of the local node. */ - #if defined(RTEMS_MULTIPROCESSING) SCORE_EXTERN uint16_t _Objects_Local_node; -SCORE_EXTERN uint16_t _Objects_Maximum_nodes; #else #define _Objects_Local_node 1 +#endif + +/** + * The following is referenced to the number of nodes in the system. + */ +#if defined(RTEMS_MULTIPROCESSING) +SCORE_EXTERN uint16_t _Objects_Maximum_nodes; +#else #define _Objects_Maximum_nodes 1 #endif -/* +/** * The following is the list of information blocks per API for each object * class. From the ID, we can go to one of these information blocks, * and obtain a pointer to the appropriate object control block. */ - SCORE_EXTERN Objects_Information **_Objects_Information_table[OBJECTS_APIS_LAST + 1]; -/* +/** * The following defines the constant which may be used * with _Objects_Get to manipulate the calling task. - * */ - #define OBJECTS_ID_OF_SELF ((Objects_Id) 0) -/* - * The following define the constants which may be used in name searches. +/** + * The following constant is used to specify that a name to ID search + * should search through all nodes. */ - #define OBJECTS_SEARCH_ALL_NODES 0 + +/** + * The following constant is used to specify that a name to ID search + * should search through all nodes except the current node. + */ #define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE -#define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF -#define OBJECTS_WHO_AM_I 0 -/* - * Parameters and return id's for _Objects_Get_next +/** + * The following constant is used to specify that a name to ID search + * should search only on this node. */ +#define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF -#define OBJECTS_ID_INITIAL_INDEX (0) -#define OBJECTS_ID_FINAL_INDEX (0xffff) +/** + * The following constant is used to specify that a name to ID search + * is being asked for the ID of the currently executing task. + */ +#define OBJECTS_WHO_AM_I 0 +/** + * This macros calculates the lowest ID for the specified api, class, + * and node. + */ #define OBJECTS_ID_INITIAL(_api, _class, _node) \ _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX ) + +/** + * This macro specifies the highest object ID value + */ #define OBJECTS_ID_FINAL ((Objects_Id)~0) -/* - * _Objects_Handler_initialization - * - * DESCRIPTION: - * +/** * This function performs the initialization necessary for this handler. * + * @param[in] node indicates the identifying number of this node. + * @param[in] maximum_nodes is the maximum number of nodes in this system. + * @param[in] maximum_global_objects is maximum number of global objects + * concurrently offered in the system. */ - void _Objects_Handler_initialization( uint32_t node, uint32_t maximum_nodes, uint32_t maximum_global_objects ); -/* - * _Objects_Extend_information - * - * DESCRIPTION: - * +/** * This function extends an object class information record. + * + * @param[in] information points to an object class information block. */ - void _Objects_Extend_information( Objects_Information *information ); -/* - * _Objects_Shrink_information - * - * DESCRIPTION: - * +/** * This function shrink an object class information record. + * + * @param[in] information points to an object class information block. */ - void _Objects_Shrink_information( Objects_Information *information ); -/* - * _Objects_Initialize_information - * - * DESCRIPTION: - * +/** * This function initializes an object class information record. * SUPPORTS_GLOBAL is TRUE if the object class supports global * objects, and FALSE otherwise. Maximum indicates the number @@ -345,8 +458,17 @@ void _Objects_Shrink_information( * in bytes of each control block for this object class. The * name length and string designator are also set. In addition, * the class may be a task, therefore this information is also included. + * + * @param[in] information points to an object class information block. + * @param[in] the_api indicates the API associated with this information block. + * @param[in] the_class indicates the class of object being managed + * by this information block. It is specific to @a the_api. + * @param[in] maximum is the maximum number of instances of this object + * class which may be concurrently active. + * @param[in] size is the size of the data structure for this class. + * @param[in] is_string is TRUE if this object uses string style names. + * @param[in] maximum_name_length is the maximum length of object names. */ - void _Objects_Initialize_information ( Objects_Information *information, Objects_APIs the_api, @@ -362,125 +484,108 @@ void _Objects_Initialize_information ( #endif ); -/*PAGE - * - * _Objects_Allocate - * - * DESCRIPTION: - * +/** * This function allocates a object control block from * the inactive chain of free object control blocks. + * + * @param[in] information points to an object class information block. */ - Objects_Control *_Objects_Allocate( Objects_Information *information ); -/* - * _Objects_Allocate_by_index - * - * DESCRIPTION: - * +/** * This function allocates the object control block * specified by the index from the inactive chain of * free object control blocks. + * + * @param[in] information points to an object class information block. + * @param[in] index is the index of the object to allocate. + * @param[in] sizeof_control is the size of the object control block. */ - Objects_Control *_Objects_Allocate_by_index( Objects_Information *information, uint16_t index, uint16_t sizeof_control ); -/*PAGE - * - * _Objects_Free - * - * DESCRIPTION: +/** * * This function frees a object control block to the * inactive chain of free object control blocks. + * + * @param[in] information points to an object class information block. + * @param[in] the_object points to the object to deallocate. */ - void _Objects_Free( Objects_Information *information, Objects_Control *the_object ); -/* - * _Objects_Clear_name - * - * DESCRIPTION: - * +/** * This method zeroes out the name. + * + * @param[in] name points to the name to be zeroed out. + * @param[in] length is the length of the object name field. */ - void _Objects_Clear_name( void *name, uint16_t length ); -/* - * _Objects_Copy_name_string - * - * DESCRIPTION: - * +/** * This method copies a string style object name from source to destination. + * + * @param[in] source is the source name to copy. + * @param[in] destination is the destination of the copy. + * @param[in] length is the number of bytes to copy. */ - void _Objects_Copy_name_string( void *source, void *destination, uint16_t length ); -/* - * _Objects_Copy_name_raw - * - * DESCRIPTION: - * +/** * This method copies a raw style object name from source to destination. + * + * @param[in] source is the source name to copy. + * @param[in] destination is the destination of the copy. + * @param[in] length is the number of bytes to copy. */ - void _Objects_Copy_name_raw( void *source, void *destination, uint16_t length ); -/* - * _Objects_Compare_name_string - * - * DESCRIPTION: - * +/** * This method compares two string style object names. + * + * @param[in] name_1 is the left hand name to compare. + * @param[in] name_2 is the right hand name to compare. + * @param[in] length is the length of the names to compare. */ - boolean _Objects_Compare_name_string( void *name_1, void *name_2, uint16_t length ); -/* - * _Objects_Compare_name_raw - * - * DESCRIPTION: - * +/** * This method compares two raw style object names. + * + * @param[in] name_1 is the left hand name to compare. + * @param[in] name_2 is the right hand name to compare. + * @param[in] length is the length of the names to compare. */ - boolean _Objects_Compare_name_raw( void *name_1, void *name_2, uint16_t length ); -/* - * _Objects_Name_to_id - * - * DESCRIPTION: - * +/** * This function implements the common portion of the object * identification directives. This directive returns the object * id associated with name. If more than one object of this class @@ -489,9 +594,7 @@ boolean _Objects_Compare_name_raw( * id of the object named name. If the object class supports global * objects, then the search can be limited to a particular node * or allowed to encompass all nodes. - * */ - typedef enum { OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL, OBJECTS_INVALID_NAME, @@ -500,9 +603,30 @@ typedef enum { OBJECTS_INVALID_NODE } Objects_Name_or_id_lookup_errors; +/** This macro defines the first entry in the + * @ref Objects_Name_or_id_lookup_errors enumerated list. + */ #define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL + +/** This macro defines the last entry in the + * @ref Objects_Name_or_id_lookup_errors enumerated list. + */ #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE +/** + * This method converts an object name to an Id. It performs a look up + * using the object information block for this object class. + * + * @param[in] information points to an object class information block. + * @param[in] name is the name of the object to find. + * @param[in] node is the set of nodes to search. + * @param[in] id will contain the Id if the search is successful. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the Id of + * the requested object. + */ Objects_Name_or_id_lookup_errors _Objects_Name_to_id( Objects_Information *information, Objects_Name name, @@ -510,30 +634,27 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id( Objects_Id *id ); -/* - * _Objects_Id_to_Name - * - * DESCRIPTION: - * +/** * This function implements the common portion of the object Id * to name directives. This function returns the name * associated with object id. * - * NOTE: + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] name will contain the name of the object, if found. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a name will contain the name of + * the requested object. * - * This function currently does not support string names. + * @note This function currently does not support string names. */ - Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( Objects_Id id, Objects_Name *name ); -/* - * _Objects_Get - * - * DESCRIPTION: - * +/** * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns * the_object control pointer which maps to id and location @@ -543,19 +664,51 @@ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( * is undefined. Otherwise, location is set to OBJECTS_ERROR * and the_object is undefined. * - * NOTE: _Objects_Get returns with dispatching disabled for - * local and remote objects. - * _Objects_Get_isr_disable returns with dispatching - * disabled for remote objects and interrupts for local - * objects. + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the Id of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. */ - Objects_Control *_Objects_Get ( Objects_Information *information, Objects_Id id, Objects_Locations *location ); +/** + * This function maps object ids to object control blocks. + * If id corresponds to a local object, then it returns + * the_object control pointer which maps to id and location + * is set to OBJECTS_LOCAL. If the object class supports global + * objects and the object id is global and resides on a remote + * node, then location is set to OBJECTS_REMOTE, and the_object + * is undefined. Otherwise, location is set to OBJECTS_ERROR + * and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * @param[in] level is the interrupt level being turned. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a name will contain the name of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_isr_disable( Objects_Information *information, Objects_Id id, @@ -563,27 +716,75 @@ Objects_Control *_Objects_Get_isr_disable( ISR_Level *level ); +/** + * This function maps object index to object control blocks which must. + * be local. The parameter the_object control pointer which maps to id + * and location is set to OBJECTS_LOCAL. Otherwise, location is set to + OBJECTS_ERROR and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * + * @return This method returns a pointer to the object associated with ID. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the id of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_by_index ( Objects_Information *information, Objects_Id id, Objects_Locations *location ); +/** + * This function maps object ids to object control blocks. + * If id corresponds to a local object, then it returns + * the_object control pointer which maps to id and location + * is set to OBJECTS_LOCAL. If the object class supports global + * objects and the object id is global and resides on a remote + * node, then location is set to OBJECTS_REMOTE, and the_object + * is undefined. Otherwise, location is set to OBJECTS_ERROR + * and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location will contain an indication of success or failure. + * + * @return This method returns one of the values from the + * @ref Objects_Name_or_id_lookup_errors enumeration to indicate + * successful or failure. On success @a id will contain the Id of + * the requested object. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_no_protection( Objects_Information *information, Objects_Id id, Objects_Locations *location ); -/* - * _Objects_Get_next - * - * DESCRIPTION: +/** + * Like @ref _Objects_Get, but is used to find "next" open object. * - * Like _Objects_Get, but is used to find "next" open object. + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @param[in] location_p will contain an indication of success or failure. + * @param[in] next_id_p is the Id of the next object we will look at. * + * @return This method returns the pointer to the object located or + * NULL on error. */ - Objects_Control *_Objects_Get_next( Objects_Information *information, Objects_Id id, diff --git a/cpukit/score/include/rtems/score/objectmp.h b/cpukit/score/include/rtems/score/objectmp.h index 7f9e25b707..6275304012 100644 --- a/cpukit/score/include/rtems/score/objectmp.h +++ b/cpukit/score/include/rtems/score/objectmp.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,9 @@ /** * @defgroup ScoreObjectMP Object Handler Multiprocessing Support * - * This group contains functionality which XXX + * This handler encapsulates functionality which is used to manage + * objects which have been declared to be globally visible. This handler + * knows objects from all of the nodes in the system. */ /**@{*/ @@ -30,20 +32,29 @@ extern "C" { #endif -/* +/** * This defines the Global Object Control Block used to manage - * objects resident on other nodes. + * objects resident on other nodes. It is derived from Object. */ typedef struct { + /** This is an object control structure. */ Objects_Control Object; - uint32_t name; /* XXX broken but works */ - /* XXX If any API is MP with variable length names .. BOOM!!!! */ + /** This is the name of the object. Using an unsigned thirty two + * bit value is broken but works. If any API is MP with variable + * length names .. BOOM!!!! + */ + uint32_t name; } Objects_MP_Control; /** @brief Objects MP Handler initialization * * This routine intializes the inactive global object chain * based on the maximum number of global objects configured. + * + * @param[in] node is this node's number. + * @param[in] maximum_nodes is the maximum number of nodes in the system. + * @param[in] maximum_global_objects is the maximum number of concurrently + * created global objects. */ void _Objects_MP_Handler_initialization ( uint32_t node, @@ -55,12 +66,20 @@ void _Objects_MP_Handler_initialization ( * * This routine place the specified global object in the * specified information table. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_global_object points to the object being opened. + * @param[in] the_name is the name of the object being opened. + * @param[in] the_id is the Id of the object being opened. + * + * @todo This method only works for object types with 4 byte object names. + * It does not support variable length object names. */ - void _Objects_MP_Open ( Objects_Information *information, Objects_MP_Control *the_global_object, - uint32_t the_name, /* XXX -- wrong for variable */ + uint32_t the_name, Objects_Id the_id ); @@ -70,10 +89,20 @@ void _Objects_MP_Open ( * and places it in the specified information table. If the * allocation fails, then is_fatal_error determines the * error processing actions taken. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_name is the name of the object being opened. + * @param[in] the_id is the Id of the object being opened. + * @param[in] is_fatal_error is TRUE if not being able to allocate the + * object is considered a fatal error. + * + * @todo This method only works for object types with 4 byte object names. + * It does not support variable length object names. */ boolean _Objects_MP_Allocate_and_open ( Objects_Information *information, - uint32_t the_name, /* XXX -- wrong for variable length */ + uint32_t the_name, Objects_Id the_id, boolean is_fatal_error ); @@ -93,6 +122,16 @@ void _Objects_MP_Close ( * This routine looks for the object with the_name in the global * object tables indicated by information. It returns the ID of the * object with that name if one is found. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_name is the name of the object being searched for. + * @param[in] nodes_to_search indicates the set of nodes to search. + * @param[in] the_id will contain the Id of the object if found. + * + * @return This method returns one of the + * @ref Objects_Name_or_id_lookup_errors. If successful, @a the_id + * will contain the Id of the object. */ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( Objects_Information *information, @@ -108,6 +147,16 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( * is found, then location is set to objects_remote, otherwise * location is set to objects_error. In both cases, the_object * is undefined. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_id is the Id of the object being opened. + * @param[in] location will contain the location of the object. + * @param[in] the_object will contain a pointer to the object. + * + * @return This method fills in @a location to indicate successful location + * of the object or error. On success, @a the_object will be + * filled in. */ void _Objects_MP_Is_remote ( Objects_Information *information, @@ -116,11 +165,15 @@ void _Objects_MP_Is_remote ( Objects_Control **the_object ); -/* +/** + * This is the maximum number of global objects configured. + */ +SCORE_EXTERN uint32_t _Objects_MP_Maximum_global_objects; + +/** * The following chain header is used to manage the set of * inactive global object control blocks. */ -SCORE_EXTERN uint32_t _Objects_MP_Maximum_global_objects; SCORE_EXTERN Chain_Control _Objects_MP_Inactive_global_objects; #ifndef __RTEMS_APPLICATION__ diff --git a/cpukit/score/include/rtems/score/priority.h b/cpukit/score/include/rtems/score/priority.h index 58b70add1b..bfe43e282d 100644 --- a/cpukit/score/include/rtems/score/priority.h +++ b/cpukit/score/include/rtems/score/priority.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,16 @@ /** * @defgroup ScorePriority Priority Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality which is used to manage + * thread priorities. At the SuperCore level 256 priority levels + * are supported with lower numbers representing logically more important + * threads. The priority level 0 is reserved for internal RTEMS use. + * Typically it is assigned to threads which defer internal RTEMS + * actions from an interrupt to thread level to improve interrupt response. + * Priority level 255 is assigned to the IDLE thread and really should not + * be used by application threads. The default IDLE thread implementation + * is an infinite "branch to self" loop which never yields to other threads + * at the same priority. */ /**@{*/ @@ -31,43 +40,48 @@ extern "C" { #endif -/* +/** * The following type defines the control block used to manage * thread priorities. * * @note Priority 0 is reserved for internal threads only. */ - typedef uint32_t Priority_Control; -#define PRIORITY_MINIMUM 0 /* highest thread priority */ -#define PRIORITY_MAXIMUM 255 /* lowest thread priority */ +/** This defines the highest (most important) thread priority. */ +#define PRIORITY_MINIMUM 0 +/** This defines the lowest (least important) thread priority. */ +#define PRIORITY_MAXIMUM 255 -/* +/** * The following record defines the information associated with * each thread to manage its interaction with the priority bit maps. */ - typedef struct { - Priority_Bit_map_control *minor; /* addr of minor bit map slot */ - Priority_Bit_map_control ready_major; /* priority bit map ready mask */ - Priority_Bit_map_control ready_minor; /* priority bit map ready mask */ - Priority_Bit_map_control block_major; /* priority bit map block mask */ - Priority_Bit_map_control block_minor; /* priority bit map block mask */ + /** This is the address of minor bit map slot. */ + Priority_Bit_map_control *minor; + /** This is the priority bit map ready mask. */ + Priority_Bit_map_control ready_major; + /** This is the priority bit map ready mask. */ + Priority_Bit_map_control ready_minor; + /** This is the priority bit map block mask. */ + Priority_Bit_map_control block_major; + /** This is the priority bit map block mask. */ + Priority_Bit_map_control block_minor; } Priority_Information; -/* - * The following data items are the priority bit map. - * Each of the sixteen bits used in the _Priority_Major_bit_map is - * associated with one of the sixteen entries in the _Priority_Bit_map. - * Each bit in the _Priority_Bit_map indicates whether or not there are +/** + * Each sixteen bit entry in this array is associated with one of + * the sixteen entries in the Priority Bit map. + */ +SCORE_EXTERN volatile Priority_Bit_map_control _Priority_Major_bit_map; + +/** Each bit in the Priority Bitmap indicates whether or not there are * threads ready at a particular priority. The mapping of * individual priority levels to particular bits is processor * dependent as is the value of each bit used to indicate that * threads are ready at that priority. */ - -SCORE_EXTERN volatile Priority_Bit_map_control _Priority_Major_bit_map; SCORE_EXTERN Priority_Bit_map_control _Priority_Bit_map[16] CPU_STRUCTURE_ALIGNMENT; @@ -76,22 +90,33 @@ SCORE_EXTERN Priority_Bit_map_control * */ -/* - * Priority Bitfield Manipulation Routines +#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) +/** + * This method returns the priority bit mask for the specified major + * or minor bit number. * - * @note + * @param[in] _bit_number is the bit number for which we need a mask * - * These may simply be pass throughs to CPU dependent routines. + * @return the priority bit mask + * + * @note This may simply be a pass through to a CPU dependent implementation. */ - -#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) - #define _Priority_Mask( _bit_number ) \ _CPU_Priority_Mask( _bit_number ) +#endif +#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) +/** + * This method returns the bit index position for the specified priority. + * + * @param[in] _priority is the priority for which we need the index. + * + * @return This method returns the array index into the priority bit map. + * + * @note This may simply be a pass through to a CPU dependent implementation. + */ #define _Priority_Bits_index( _priority ) \ _CPU_Priority_bits_index( _priority ) - #endif #ifndef __RTEMS_APPLICATION__ diff --git a/cpukit/score/include/rtems/score/stack.h b/cpukit/score/include/rtems/score/stack.h index d0f61ab8c6..f7e3456569 100644 --- a/cpukit/score/include/rtems/score/stack.h +++ b/cpukit/score/include/rtems/score/stack.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,8 @@ /** * @defgroup ScoreStack Stack Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality which is used in the management + * of thread stacks. */ /**@{*/ @@ -31,20 +32,20 @@ extern "C" { #endif -/* +/** * The following constant defines the minimum stack size which every * thread must exceed. */ - #define STACK_MINIMUM_SIZE CPU_STACK_MINIMUM_SIZE -/* +/** * The following defines the control block used to manage each stack. */ - typedef struct { - uint32_t size; /* stack size */ - void *area; /* low memory addr of stack */ + /** This is the stack size. */ + uint32_t size; + /** This is the low memory address of stack. */ + void *area; } Stack_Control; #ifndef __RTEMS_APPLICATION__ diff --git a/cpukit/score/include/rtems/score/states.h b/cpukit/score/include/rtems/score/states.h index 2b3cac9eb8..8e0b07f138 100644 --- a/cpukit/score/include/rtems/score/states.h +++ b/cpukit/score/include/rtems/score/states.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,8 @@ /** * @defgroup ScoreStates Thread States Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality which relates to the management of + * the state bitmap associated with each thread. */ /**@{*/ @@ -29,11 +30,10 @@ extern "C" { #endif -/* +/** * The following type defines the control block used to manage a * thread's state. */ - typedef uint32_t States_Control; /* @@ -41,26 +41,48 @@ typedef uint32_t States_Control; * be used to compose and manipulate a thread's state. */ +/** This macro corresponds to all states being set. */ #define STATES_ALL_SET 0xfffff /* all states */ +/** This macro corresponds to a task being ready. */ #define STATES_READY 0x00000 /* ready to run */ +/** This macro corresponds to a task being created but not yet started. */ #define STATES_DORMANT 0x00001 /* created not started */ +/** This macro corresponds to a task being suspended. */ #define STATES_SUSPENDED 0x00002 /* waiting for resume */ +/** This macro corresponds to a task being in an internal state transition. */ #define STATES_TRANSIENT 0x00004 /* in transition */ +/** This macro corresponds to a task which is waiting for a timeout. */ #define STATES_DELAYING 0x00008 /* wait for timeout */ +/** This macro corresponds to a task waiting until a specific TOD. */ #define STATES_WAITING_FOR_TIME 0x00010 /* wait for TOD */ +/** This macro corresponds to a task waiting for a variable length buffer. */ #define STATES_WAITING_FOR_BUFFER 0x00020 +/** This macro corresponds to a task waiting for a fixed size segment. */ #define STATES_WAITING_FOR_SEGMENT 0x00040 +/** This macro corresponds to a task waiting for a message. */ #define STATES_WAITING_FOR_MESSAGE 0x00080 +/** This macro corresponds to a task waiting for an event. */ #define STATES_WAITING_FOR_EVENT 0x00100 +/** This macro corresponds to a task waiting for a semaphore. */ #define STATES_WAITING_FOR_SEMAPHORE 0x00200 +/** This macro corresponds to a task waiting for a mutex. */ #define STATES_WAITING_FOR_MUTEX 0x00400 +/** This macro corresponds to a task waiting for a condition variable. */ #define STATES_WAITING_FOR_CONDITION_VARIABLE 0x00800 +/** This macro corresponds to a task waiting for a join while exiting. */ #define STATES_WAITING_FOR_JOIN_AT_EXIT 0x01000 +/** This macro corresponds to a task waiting for a reply to an MPCI request. */ #define STATES_WAITING_FOR_RPC_REPLY 0x02000 +/** This macro corresponds to a task waiting for a period. */ #define STATES_WAITING_FOR_PERIOD 0x04000 +/** This macro corresponds to a task waiting for a signal. */ #define STATES_WAITING_FOR_SIGNAL 0x08000 +/** This macro corresponds to a task which is in an interruptible + * blocking state. + */ #define STATES_INTERRUPTIBLE_BY_SIGNAL 0x10000 +/** This macro corresponds to a task waiting for a local object operation. */ #define STATES_LOCALLY_BLOCKED ( STATES_WAITING_FOR_BUFFER | \ STATES_WAITING_FOR_SEGMENT | \ STATES_WAITING_FOR_MESSAGE | \ @@ -70,10 +92,13 @@ typedef uint32_t States_Control; STATES_WAITING_FOR_JOIN_AT_EXIT | \ STATES_WAITING_FOR_SIGNAL ) +/** This macro corresponds to a task waiting which is blocked on + * a thread queue. */ #define STATES_WAITING_ON_THREAD_QUEUE \ ( STATES_LOCALLY_BLOCKED | \ STATES_WAITING_FOR_RPC_REPLY ) +/** This macro corresponds to a task waiting which is blocked. */ #define STATES_BLOCKED ( STATES_DELAYING | \ STATES_WAITING_FOR_TIME | \ STATES_WAITING_FOR_PERIOD | \ diff --git a/cpukit/score/include/rtems/score/sysstate.h b/cpukit/score/include/rtems/score/sysstate.h index 314c0bb2aa..fa53602688 100644 --- a/cpukit/score/include/rtems/score/sysstate.h +++ b/cpukit/score/include/rtems/score/sysstate.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,8 @@ /** * @defgroup ScoreSysState System State Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of the + * internal system state of RTEMS. */ /**@{*/ @@ -33,33 +34,45 @@ extern "C" { /* enumerated constants */ -/* +/** * The following type defines the possible system states. */ - typedef enum { - SYSTEM_STATE_BEFORE_INITIALIZATION, /* start -> end of 1st init part */ - SYSTEM_STATE_BEFORE_MULTITASKING, /* end of 1st -> beginning of 2nd */ - SYSTEM_STATE_BEGIN_MULTITASKING, /* just before multitasking starts */ - SYSTEM_STATE_UP, /* normal operation */ - SYSTEM_STATE_SHUTDOWN, /* shutdown */ - SYSTEM_STATE_FAILED /* fatal error occurred */ + /** This indicates that the system state is between the start + * of rtems_initialize_executive_early and the end of the first + * phase of initialization. + */ + SYSTEM_STATE_BEFORE_INITIALIZATION, + /** This indicates that the system state is between end of the first + * phase of initializatin but before multitasking is started. + */ + SYSTEM_STATE_BEFORE_MULTITASKING, + /** This indicates that the system state is attempting to initiate + * multitasking. + */ + SYSTEM_STATE_BEGIN_MULTITASKING, + /** This indicates that the system is up and operating normally. */ + SYSTEM_STATE_UP, + /** This indicates that the system is in the midst of a shutdown. */ + SYSTEM_STATE_SHUTDOWN, + /** This indicates that a fatal error has occurred. */ + SYSTEM_STATE_FAILED } System_state_Codes; +/** This defines the first system state. */ #define SYSTEM_STATE_CODES_FIRST SYSTEM_STATE_BEFORE_INITIALIZATION +/** This defines the highest value system state. */ #define SYSTEM_STATE_CODES_LAST SYSTEM_STATE_FAILED -/* +/** * The following variable indicates whether or not this is * an multiprocessing system. */ - SCORE_EXTERN boolean _System_state_Is_multiprocessing; -/* +/** * The following variable contains the current system state. */ - SCORE_EXTERN System_state_Codes _System_state_Current; /* diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index 02bf0cbd86..7fbae11397 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,8 @@ /** * @defgroup ScoreThread Thread Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * threads. This includes the creation, deletion, and scheduling of threads. */ /**@{*/ @@ -67,21 +68,27 @@ typedef enum { THREAD_START_BOTH_NUMERIC_FIRST } Thread_Start_types; -/** - */ +/** This type corresponds to a very simple style thread entry point. */ typedef Thread ( *Thread_Entry )(); /* basic type */ +/** This type corresponds to a thread entry point which takes a single + * unsigned thirty-two bit integer as an argument. + */ typedef Thread ( *Thread_Entry_numeric )( uint32_t ); -/** +/** This type corresponds to a thread entry point which takes a single + * untyped pointer as an argument. */ typedef Thread ( *Thread_Entry_pointer )( void * ); -/** +/** This type corresponds to a thread entry point which takes a single + * untyped pointer and an unsigned thirty-two bit integer as arguments. */ typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t ); -/** +/** This type corresponds to a thread entry point which takes a single + * unsigned thirty-two bit integer and an untyped pointer and an + * as arguments. */ typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t , void * ); @@ -99,11 +106,12 @@ typedef enum { THREAD_CPU_BUDGET_ALGORITHM_CALLOUT } Thread_CPU_budget_algorithms; -/** +/** This type defines the Thread Control Block structure. */ typedef struct Thread_Control_struct Thread_Control; -/** +/** This defines thes the entry point for the thread specific timeslice + * budget management algorithm. */ typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * ); @@ -117,7 +125,7 @@ struct rtems_task_variable_tt; * * This is the internal structure used to manager per Task Variables. */ -struct rtems_task_variable_tt { +typedef struct { /** 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 @@ -130,33 +138,46 @@ struct rtems_task_variable_tt { 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; +} 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_types prototype; /* how task is invoked */ - void *pointer_argument; /* pointer argument */ - uint32_t numeric_argument; /* numeric argument */ - /* initial execution modes */ + /** This field is the starting address for the thread. */ + Thread_Entry entry_point; + /** This field indicatres the how task is invoked. */ + Thread_Start_types prototype; + /** This field is the pointer argument passed at thread start. */ + void *pointer_argument; + /** This field is the numeric argument passed at thread start. */ + uint32_t numeric_argument; + /*-------------- initial execution modes ----------------- */ + /** This field indicates whether the thread was preemptible when + * it started. + */ boolean is_preemptible; + /** This field indicates the CPU budget algorith. */ Thread_CPU_budget_algorithms budget_algorithm; + /** This field is the routine to invoke when the CPU allotment is + * consumed. + */ Thread_CPU_budget_algorithm_callout budget_callout; + /** This field is the initial ISR disable level of this thread. */ uint32_t isr_level; - Priority_Control initial_priority; /* initial priority */ + /** This field is the initial priority. */ + Priority_Control initial_priority; + /** This field indicates whether the SuperCore allocated the stack. */ boolean core_allocated_stack; - Stack_Control Initial_stack; /* stack information */ + /** This field is the stack information. */ + Stack_Control Initial_stack; #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) - void *fp_context; /* initial FP context area address */ + /** This field is the initial FP context area address. */ + void *fp_context; #endif - void *stack; /* initial stack area address */ + /** This field is the initial stack area address. */ + void *stack; } Thread_Start_information; /** @@ -204,17 +225,26 @@ typedef struct { * memory images for the shared part. */ typedef struct { + /** This field is the object management structure for each proxy. */ Objects_Control Object; + /** This field is the current execution state of this proxy. */ States_Control current_state; + /** This field is the current priority state of this proxy. */ Priority_Control current_priority; + /** This field is the base priority of this proxy. */ Priority_Control real_priority; + /** This field is the number of mutexes currently held by this proxy. */ uint32_t resource_count; + /** This field is the blocking information for this proxy. */ Thread_Wait_information Wait; + /** This field is the Watchdog used to manage proxy delays and timeouts. */ Watchdog_Control Timer; #if defined(RTEMS_MULTIPROCESSING) + /** This field is the received response packet in an MP system. */ MP_packet_Prefix *receive_packet; #endif /****************** end of common block ********************/ + /** This field is used to manage the set of proxies in the system. */ Chain_Node Active; } Thread_Proxy_control; @@ -226,54 +256,95 @@ typedef struct { * memory images for the shared part. */ typedef enum { + /** This value is for the Classic RTEMS API. */ THREAD_API_RTEMS, + /** This value is for the POSIX API. */ THREAD_API_POSIX, + /** This value is for the ITRON API. */ THREAD_API_ITRON } Thread_APIs; -/** - */ +/** This macro defines the first API which has threads. */ #define THREAD_API_FIRST THREAD_API_RTEMS -/** - */ +/** This macro defines the last API which has threads. */ #define THREAD_API_LAST THREAD_API_ITRON /** + * This structure defines the Thread Control Block (TCB). */ struct Thread_Control_struct { - Objects_Control Object; - States_Control current_state; - Priority_Control current_priority; - Priority_Control real_priority; - uint32_t resource_count; - Thread_Wait_information Wait; - Watchdog_Control Timer; + /** This field is the object management structure for each thread. */ + Objects_Control Object; + /** This field is the current execution state of this thread. */ + States_Control current_state; + /** This field is the current priority state of this thread. */ + Priority_Control current_priority; + /** This field is the base priority of this thread. */ + Priority_Control real_priority; + /** This field is the number of mutexes currently held by this thread. */ + uint32_t resource_count; + /** This field is the blocking information for this thread. */ + Thread_Wait_information Wait; + /** This field is the Watchdog used to manage thread delays and timeouts. */ + Watchdog_Control Timer; #if defined(RTEMS_MULTIPROCESSING) - MP_packet_Prefix *receive_packet; + /** This field is the received response packet in an MP system. */ + MP_packet_Prefix *receive_packet; #endif - /****************** end of common block ********************/ + /*================= end of common block =================*/ + /** This field is the number of nested suspend calls. */ uint32_t suspend_count; + /** This field is true if the thread is offered globally */ boolean is_global; + /** This field is is true if the post task context switch should be + * executed for this thread at the next context switch. + */ boolean do_post_task_switch_extension; - + /** This field is true if the thread is preemptible. */ boolean is_preemptible; + /** This field is the GNAT self context pointer. */ void *rtems_ada_self; + /** This field is the length of the time quantum that this thread is + * allowed to consume. The algorithm used to manage limits on CPU usage + * is specified by budget_algorithm. + */ uint32_t cpu_time_budget; + /** This field is the algorithm used to manage this thread's time + * quantum. The algorithm may be specified as none which case, + * no limit is in place. + */ Thread_CPU_budget_algorithms budget_algorithm; + /** This field is the method invoked with the budgeted time is consumed. */ Thread_CPU_budget_algorithm_callout budget_callout; + /** This field is the number of clock ticks executed by this thread + * since it was created. + */ uint32_t ticks_executed; + /** This field points to the Ready FIFO for this priority. */ Chain_Control *ready; + /** This field contains precalculated priority map indices. */ Priority_Information Priority_map; + /** This field contains information about the starting state of + * this thread. + */ Thread_Start_information Start; + /** This field contains the context of this thread. */ Context_Control Registers; #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) + /** This field points to the floating point context for this thread. + * If NULL, the thread is integer only. + */ void *fp_context; #endif + /** This field points to the newlib reentrancy structure for this thread. */ struct _reent *libc_reent; + /** This array contains the API extension area pointers. */ void *API_Extensions[ THREAD_API_LAST + 1 ]; + /** This field points to the user extension pointers. */ void **extensions; + /** This field points to the set of per task variables. */ rtems_task_variable_t *task_variables; }; @@ -303,7 +374,7 @@ SCORE_EXTERN Thread_Control *_Thread_Idle; */ 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. @@ -651,7 +722,7 @@ Thread _Thread_Idle_body( ); #endif -/** +/** This defines the type for a method which operates on a single thread. */ typedef void (*rtems_per_thread_routine)( Thread_Control * ); diff --git a/cpukit/score/include/rtems/score/threadmp.h b/cpukit/score/include/rtems/score/threadmp.h index b3ecea6199..6b0ced7307 100644 --- a/cpukit/score/include/rtems/score/threadmp.h +++ b/cpukit/score/include/rtems/score/threadmp.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,10 @@ /** * @defgroup ScoreThreadMP Thread Handler Multiprocessing Support * - * This group contains functionality which XXX + * This handler encapsulates functionality which is related to managing + * threads in a multiprocessor system configuration. This handler must + * manage proxies which represent remote threads blocking on local + * operations. */ /**@{*/ @@ -37,6 +40,7 @@ extern "C" { void _Thread_MP_Handler_initialization ( uint32_t maximum_proxies ); + /** @brief _Thread_MP_Allocate_proxy * * This allocates a proxy control block from @@ -66,7 +70,7 @@ Thread_Control *_Thread_MP_Find_proxy ( */ SCORE_EXTERN Thread_Control *_Thread_MP_Receive; -/* @brief Active Proxy Set +/** @brief Active Proxy Set * * The following chain is used to manage the active set proxies. */ diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index 572993e72a..86dcbac39b 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,8 @@ /** * @defgroup ScoreThreadQ Thread Queue Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to managing sets of threads + * blocked waiting for resources. */ /**@{*/ diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h index 904541f311..af416a529d 100644 --- a/cpukit/score/include/rtems/score/tod.h +++ b/cpukit/score/include/rtems/score/tod.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,7 @@ /** * @defgroup ScoreTOD Time Of Day (TOD) Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality used to manage time of day. */ /**@{*/ @@ -39,62 +39,62 @@ extern "C" { /**@{*/ /** - * XXX + * This constant represents the number of seconds in a minute. */ -#define TOD_SECONDS_PER_MINUTE (uint32_t )60 +#define TOD_SECONDS_PER_MINUTE (uint32_t)60 /** - * XXX + * This constant represents the number of minutes per hour. */ -#define TOD_MINUTES_PER_HOUR (uint32_t )60 +#define TOD_MINUTES_PER_HOUR (uint32_t)60 /** - * XXX + * This constant represents the number of months in a year. */ -#define TOD_MONTHS_PER_YEAR (uint32_t )12 +#define TOD_MONTHS_PER_YEAR (uint32_t)12 /** - * XXX + * This constant represents the number of days in a non-leap year. */ -#define TOD_DAYS_PER_YEAR (uint32_t )365 +#define TOD_DAYS_PER_YEAR (uint32_t)365 /** - * XXX + * This constant represents the number of hours per day. */ -#define TOD_HOURS_PER_DAY (uint32_t )24 +#define TOD_HOURS_PER_DAY (uint32_t)24 /** - * XXX + * This constant represents the number of seconds in a day which does + * not include a leap second. */ -#define TOD_SECONDS_PER_DAY (uint32_t ) (TOD_SECONDS_PER_MINUTE * \ +#define TOD_SECONDS_PER_DAY (uint32_t) (TOD_SECONDS_PER_MINUTE * \ TOD_MINUTES_PER_HOUR * \ TOD_HOURS_PER_DAY) - /** - * XXX + * This constant represents the number of seconds in a non-leap year. */ #define TOD_SECONDS_PER_NON_LEAP_YEAR (365 * TOD_SECONDS_PER_DAY) /** - * XXX + * This constant represents the number of seconds in a millisecond. */ -#define TOD_MILLISECONDS_PER_SECOND (uint32_t )1000 +#define TOD_MILLISECONDS_PER_SECOND (uint32_t)1000 /** - * XXX + * This constant represents the number of microseconds in a second. */ -#define TOD_MICROSECONDS_PER_SECOND (uint32_t )1000000 +#define TOD_MICROSECONDS_PER_SECOND (uint32_t)1000000 /** - * XXX + * This constant represents the number of nanoseconds in a second. */ -#define TOD_NANOSECONDS_PER_SECOND (uint32_t )1000000000 +#define TOD_NANOSECONDS_PER_SECOND (uint32_t)1000000000 /** - * XXX + * This constant represents the number of nanoseconds in a second. */ -#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t )1000 +#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t)1000 /**@}*/ @@ -204,18 +204,24 @@ const uint16_t _TOD_Days_since_last_leap_year[4] = { 0, 366, 731, 1096 }; #else -/** @brief +/** @brief Convert Month to Julian Days * + * This is a prototype for a table which assists in converting the + * current day into the Julian days since the first of the year. */ extern const uint16_t _TOD_Days_to_date[2][13]; /* Julian days */ -/** @brief +/** @brief Days since Beginning of Last Leap Year * + * This is a prototype for a table which assists in calculating the + * number of days since the beginning of the last leap year. */ extern const uint16_t _TOD_Days_since_last_leap_year[4]; -/** @brief +/** @brief Days Per Month Table * + * This is a prototype for a table which holds the number of days + * per month for a leap year and non-leap year. */ extern const uint32_t _TOD_Days_per_month[2][13]; diff --git a/cpukit/score/include/rtems/score/tqdata.h b/cpukit/score/include/rtems/score/tqdata.h index 4b72aed609..b70124ff9e 100644 --- a/cpukit/score/include/rtems/score/tqdata.h +++ b/cpukit/score/include/rtems/score/tqdata.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,9 @@ /** * @defgroup ScoreThreadQData Thread Queue Handler Data Definition * - * This group contains functionality which XXX + * This handler defines the data shared between the thread and thread + * queue handlers. Having this handler define these data structure + * avoids potentially circular references. */ /**@{*/ @@ -34,21 +36,19 @@ extern "C" { #include #include -/* +/** * The following enumerated type details all of the disciplines * supported by the Thread Queue Handler. */ - typedef enum { THREAD_QUEUE_DISCIPLINE_FIFO, /* FIFO queue discipline */ THREAD_QUEUE_DISCIPLINE_PRIORITY /* PRIORITY queue discipline */ } Thread_queue_Disciplines; -/* +/** * The following enumerated types indicate what happened while the thread * queue was in the synchronization window. */ - typedef enum { THREAD_QUEUE_SYNCHRONIZED, THREAD_QUEUE_NOTHING_HAPPENED, @@ -56,8 +56,8 @@ typedef enum { THREAD_QUEUE_SATISFIED } Thread_queue_States; -/* - * The following constants are used to manage the priority queues. +/** + * This is one of the constants used to manage the priority queues. * * There are four chains used to maintain a priority -- each chain * manages a distinct set of task priorities. The number of chains @@ -70,20 +70,45 @@ typedef enum { * is in, then the search is performed from the rear of the chain. * This halves the search time to find the insertion point. */ - #define TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS 4 + +/** + * This is one of the constants used to manage the priority queues. + * @ref TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS for more details. + */ #define TASK_QUEUE_DATA_PRIORITIES_PER_HEADER 64 + +/** + * This is one of the constants used to manage the priority queues. + * @ref TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS for more details. + */ #define TASK_QUEUE_DATA_REVERSE_SEARCH_MASK 0x20 +/** + * This is the structure used to manage sets of tasks which are blocked + * waiting to acquire a resource. + */ typedef struct { + /** This union contains the data structures used to manage the blocked + * set of tasks which varies based upon the discipline. + */ union { - Chain_Control Fifo; /* FIFO discipline list */ + /** This is the FIFO discipline list. */ + Chain_Control Fifo; + /** This is the set of lists for priority discipline waiting. */ Chain_Control Priority[TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS]; - /* priority discipline list */ } Queues; - Thread_queue_States sync_state; /* alloc/dealloc critical section */ - Thread_queue_Disciplines discipline; /* queue discipline */ - States_Control state; /* state of threads on Thread_q */ + /** This field is used to manage the critical section. */ + Thread_queue_States sync_state; + /** This field indicates the thread queue's blocking discipline. */ + Thread_queue_Disciplines discipline; + /** This indicates the blocking state for threads waiting on this + * thread queue. + */ + States_Control state; + /** This is the status value returned to threads which timeout while + * waiting on this thread queue. + */ uint32_t timeout_status; } Thread_queue_Control; diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h index bb443ce2f6..dcc8c80031 100644 --- a/cpukit/score/include/rtems/score/userext.h +++ b/cpukit/score/include/rtems/score/userext.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,8 @@ /** * @defgroup ScoreUserExt User Extension Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * the user extensions to the SuperCore that are available to the user. */ /**@{*/ @@ -35,6 +36,8 @@ extern "C" { #include #include +/*@}*/ + /** @defgroup ScoreUserExtStruct User Extension Handler Structures * * The following records defines the User Extension Table. @@ -45,12 +48,13 @@ extern "C" { /*@{*/ /** - * XXX + * This type indicates the return type of a user extension method. */ typedef void User_extensions_routine; /** - * XXX + * This type defines the prototype of a thread creation extension handler. + * The handler is passed the thread executing and the thread being created. */ typedef boolean ( *User_extensions_thread_create_extension )( Thread_Control *, @@ -58,7 +62,8 @@ typedef boolean ( *User_extensions_thread_create_extension )( ); /** - * XXX + * This type defines the prototype of a thread deletion extension handler. + * The handler is passed the thread executing and the thread being deleted. */ typedef User_extensions_routine ( *User_extensions_thread_delete_extension )( Thread_Control *, @@ -66,7 +71,8 @@ typedef User_extensions_routine ( *User_extensions_thread_delete_extension )( ); /** - * XXX + * This type defines the prototype of thread starting extension handler. + * The handler is passed the thread executing and the thread being started. */ typedef User_extensions_routine ( *User_extensions_thread_start_extension )( Thread_Control *, @@ -74,7 +80,8 @@ typedef User_extensions_routine ( *User_extensions_thread_start_extension )( ); /** - * XXX + * This type defines the prototype of a thread restarting extension handler. + * The handler is passed the thread executing and the thread being restarted. */ typedef User_extensions_routine ( *User_extensions_thread_restart_extension )( Thread_Control *, @@ -82,7 +89,9 @@ typedef User_extensions_routine ( *User_extensions_thread_restart_extension )( ); /** - * XXX + * This type defines the prototype of thread context switch extension handler. + * The handler is passed the thread currently executing and the thread being + * switched to. */ typedef User_extensions_routine ( *User_extensions_thread_switch_extension )( Thread_Control *, @@ -90,29 +99,34 @@ typedef User_extensions_routine ( *User_extensions_thread_switch_extension )( ); /** - * XXX + * This type defines the prototype of a post context switch extension handler. + * The handler is passed the thread thread being switched to. */ -typedef User_extensions_routine ( - *User_extensions_thread_post_switch_extension )( +typedef User_extensions_routine (*User_extensions_thread_post_switch_extension)( Thread_Control * ); /** - * XXX + * This type defines the prototype of a thread beginning to execute + * extension handler. The handler is passed the thread executing. This + * extension is executed in the context of the beginning thread. */ typedef User_extensions_routine ( *User_extensions_thread_begin_extension )( Thread_Control * ); /** - * XXX + * This type defines the prototype of a thread exiting extension handler. + * The handler is passed the thread exiting. */ typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )( Thread_Control * ); /** - * XXX + * This type defines the prototype of the fatal error extension handler. + * The handler is passed an indicator of the source of the fatal error, + * whether it is internal to RTEMS and an error code. */ typedef User_extensions_routine ( *User_extensions_fatal_extension )( Internal_errors_Source /* the_source */, @@ -121,36 +135,37 @@ typedef User_extensions_routine ( *User_extensions_fatal_extension )( ); /** - * XXX + * This type defines a set of user extensions. */ typedef struct { - /** This field is XXX */ + /** This field is the thread creation handler. */ User_extensions_thread_create_extension thread_create; - /** This field is XXX */ + /** This field is the thread starting handler. */ User_extensions_thread_start_extension thread_start; - /** This field is XXX */ + /** This field is the thread restarting handler. */ User_extensions_thread_restart_extension thread_restart; - /** This field is XXX */ + /** This field is the thread deleting handler */ User_extensions_thread_delete_extension thread_delete; - /** This field is XXX */ + /** This field is thread context switch handler. */ User_extensions_thread_switch_extension thread_switch; - /** This field is XXX */ + /** This field is the thread beginning handler. */ User_extensions_thread_begin_extension thread_begin; - /** This field is XXX */ + /** This field is thread exiting handler. */ User_extensions_thread_exitted_extension thread_exitted; - /** This field is XXX */ + /** This field is the fatal error extension. */ User_extensions_fatal_extension fatal; } User_extensions_Table; -/*@}*/ - /** - * This is used to manage the list of switch handlers. + * This is used to manage the list of switch handlers. They are managed + * separately from other extensions for performance reasons. */ typedef struct { - /** This field is XXX */ + /** This field is a Chain Node structure and allows this to be placed on + * chains for set management. + */ Chain_Node Node; - /** This field is XXX */ + /** This field is the thread switch extension. */ User_extensions_thread_switch_extension thread_switch; } User_extensions_Switch_control; @@ -161,11 +176,13 @@ typedef struct { * handler. */ typedef struct { - /** This field is XXX */ + /** This field is a Chain Node structure and allows this to be placed on + * chains for set management. + */ Chain_Node Node; - /** This field is XXX */ + /** This field is the thread switch user extension. */ User_extensions_Switch_control Switch; - /** This field is XXX */ + /** This field is the rest of this user extension's entry points. */ User_extensions_Table Callouts; } User_extensions_Control; @@ -180,10 +197,20 @@ SCORE_EXTERN Chain_Control _User_extensions_List; */ SCORE_EXTERN Chain_Control _User_extensions_Switches_list; +/*@}*/ +/** @addtogroup ScoreUserExt */ + +/*@{*/ + /** @brief User extensions Thread create * * This routine is used to invoke the user extension for * the thread creation operate. + * + * @param[in] the_thread is the thread being created. + * + * @return This method returns TRUE if the user extension executed + * successfully. */ boolean _User_extensions_Thread_create ( Thread_Control *the_thread @@ -193,6 +220,8 @@ boolean _User_extensions_Thread_create ( * * This routine is used to invoke the user extension for * the thread deletion operation. + * + * @param[in] the_thread is the thread being deleted. */ void _User_extensions_Thread_delete ( Thread_Control *the_thread @@ -202,6 +231,8 @@ void _User_extensions_Thread_delete ( * * This routine is used to invoke the user extension for * the thread start operation. + * + * @param[in] the_thread is the thread being started. */ void _User_extensions_Thread_start ( Thread_Control *the_thread @@ -211,6 +242,8 @@ void _User_extensions_Thread_start ( * * This routine is used to invoke the user extension for * the thread restart operation. + * + * @param[in] the_thread is the thread being restarted. */ void _User_extensions_Thread_restart ( Thread_Control *the_thread @@ -220,6 +253,8 @@ void _User_extensions_Thread_restart ( * * This routine is used to invoke the user extension which * is invoked when a thread begins. + * + * @param[in] executing is the thread beginning to execute. */ void _User_extensions_Thread_begin ( Thread_Control *executing @@ -229,6 +264,8 @@ void _User_extensions_Thread_begin ( * * This routine is used to invoke the user extension which * is invoked when a thread exits. + * + * @param[in] executing is the thread voluntarily exiting. */ void _User_extensions_Thread_exitted ( Thread_Control *executing @@ -238,6 +275,10 @@ void _User_extensions_Thread_exitted ( * * This routine is used to invoke the user extension invoked * when a fatal error occurs. + * + * @param[in] the_source is the source of the fatal error. + * @param[in] is_internal is TRUE if the error originated inside RTEMS. + * @param[in] the_error is an indication of the actual error. */ void _User_extensions_Fatal ( Internal_errors_Source the_source, diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h index 124187c899..fc902ad8c7 100644 --- a/cpukit/score/include/rtems/score/watchdog.h +++ b/cpukit/score/include/rtems/score/watchdog.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,11 @@ /** * @defgroup ScoreWatchdog Watchdog Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the scheduling of + * watchdog functions to be called at specific times in the future. + * + * @note This handler does not have anything to do with hardware watchdog + * timers. */ /**@{*/ @@ -109,14 +113,27 @@ typedef enum { * to manage each watchdog timer. */ typedef struct { + /** This field is a Chain Node structure and allows this to be placed on + * chains for set management. + */ Chain_Node Node; + /** This field is the state of the watchdog. */ Watchdog_States state; + /** This field is the initially requested interval. */ Watchdog_Interval initial; + /** This field is the remaining portion of the interval. */ Watchdog_Interval delta_interval; + /** This field is the number of system clock ticks when this was scheduled. */ Watchdog_Interval start_time; + /** This field is the number of system clock ticks when this was suspended. */ Watchdog_Interval stop_time; + /** This field is the function to invoke. */ Watchdog_Service_routine_entry routine; + /** This field is the Id to pass as an argument to the routine. */ Objects_Id id; + /** This field is an untyped pointer to user data that is passed to the + * watchdog handler routine. + */ void *user_data; } Watchdog_Control; @@ -166,7 +183,7 @@ void _Watchdog_Handler_initialization( void ); * This routine removes @a the_watchdog from the watchdog chain on which * it resides and returns the state @a the_watchdog timer was in. * - * @param the_watchdog (in) will be removed + * @param[in] the_watchdog will be removed * @return the state in which @a the_watchdog was in when removed */ Watchdog_States _Watchdog_Remove ( @@ -178,9 +195,9 @@ Watchdog_States _Watchdog_Remove ( * This routine adjusts the @a header watchdog chain in the forward * or backward @a direction for @a units ticks. * - * @param header (in) is the watchdog chain to adjust - * @param direction (in) is the direction to adjust @a header - * @param units (in) is the number of units to adjust @a header + * @param[in] header is the watchdog chain to adjust + * @param[in] direction is the direction to adjust @a header + * @param[in] units is the number of units to adjust @a header */ void _Watchdog_Adjust ( Chain_Control *header, @@ -193,8 +210,8 @@ void _Watchdog_Adjust ( * This routine inserts @a the_watchdog into the @a header watchdog chain * for a time of @a units. * - * @param header (in) is @a the_watchdog list to insert @a the_watchdog on - * @param the_watchdog (in) is the watchdog to insert + * @param[in] header is @a the_watchdog list to insert @a the_watchdog on + * @param[in] the_watchdog is the watchdog to insert */ void _Watchdog_Insert ( Chain_Control *header, @@ -206,7 +223,7 @@ void _Watchdog_Insert ( * This routine is invoked at appropriate intervals to update * the @a header watchdog chain. * - * @param header (in) is the watchdog chain to tickle + * @param[in] header is the watchdog chain to tickle */ void _Watchdog_Tickle ( diff --git a/cpukit/score/include/rtems/score/wkspace.h b/cpukit/score/include/rtems/score/wkspace.h index f438c39e1e..2fcc22a0aa 100644 --- a/cpukit/score/include/rtems/score/wkspace.h +++ b/cpukit/score/include/rtems/score/wkspace.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,8 @@ /** * @defgroup ScoreWorkspace Workspace Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * the RTEMS Executive Workspace. */ /**@{*/ @@ -45,9 +46,9 @@ SCORE_EXTERN Heap_Control _Workspace_Area; /* executive heap header */ * * This routine performs the initialization necessary for this handler. * - * @param starting_address (in) is the base address of the RTEMS Executive + * @param[in] starting_address is the base address of the RTEMS Executive * Workspace - * @param size (in) is the number of bytes in the RTEMS Executive Workspace + * @param[in] size is the number of bytes in the RTEMS Executive Workspace */ void _Workspace_Handler_initialization( void *starting_address, @@ -60,7 +61,7 @@ void _Workspace_Handler_initialization( * bytes. If a block of the appropriate size cannot be allocated * from the workspace, then the internal error handler is invoked. * - * @param size (in) is the desired number of bytes to allocate + * @param[in] size is the desired number of bytes to allocate * @return If successful, the starting address of the allocated memory */ void *_Workspace_Allocate_or_fatal_error( diff --git a/cpukit/score/include/rtems/seterr.h b/cpukit/score/include/rtems/seterr.h index 9e5ebe931e..2548258d87 100644 --- a/cpukit/score/include/rtems/seterr.h +++ b/cpukit/score/include/rtems/seterr.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -19,9 +19,25 @@ #ifndef _RTEMS_SETERR_H #define _RTEMS_SETERR_H +/** + * This is a helper macro which will set the variable errno and return + * -1 to the caller. This pattern is common to many POSIX methods. + * + * @param[in] _error is the error code + */ #define rtems_set_errno_and_return_minus_one( _error ) \ do { errno = (_error); return -1; } while(0) +/** + * This is a helper macro which will set the variable errno and return + * -1 to the caller. This pattern is common to many POSIX methods. + * + * @param[in] _error is the error code + * @param[in] _cast is the type to which -1 must be cast + * + * @note It is similar to @ref rtems_set_errno_and_return_minus_one but + * this -1 value is cast to something other than an int. + */ #define rtems_set_errno_and_return_minus_one_cast( _error, _cast ) \ do { errno = (_error); return (_cast) -1; } while(0) diff --git a/cpukit/score/include/rtems/system.h b/cpukit/score/include/rtems/system.h index 27b6ecd432..59d5b293af 100644 --- a/cpukit/score/include/rtems/system.h +++ b/cpukit/score/include/rtems/system.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,12 +24,22 @@ extern "C" { #endif -/* - * Major, minor, revision version numbers of RTEMS. - * Use these macros to test for features in specific releases. +/** This macro defines the major version portion of an RTEMS release. + * + * @note Use this macros to test for features in specific releases. */ #define __RTEMS_MAJOR__ 4 + +/** This macro defines the minor version portion of an RTEMS release. + * + * @note Use this macros to test for features in specific releases. + */ #define __RTEMS_MINOR__ 6 + +/** This macro defines the revision version portion of an RTEMS release. + * + * @note Use this macros to test for features in specific releases. + */ #define __RTEMS_REVISION__ 99 /* @@ -37,16 +47,14 @@ extern "C" { * parameters for this build of RTEMS. It must be included * first so the basic macro definitions are in place. */ - #include -/* +/** * The following ensures that all data is declared in the space * of the initialization routine for either the Initialization Manager * or the initialization file for the appropriate API. It is * referenced as "external" in every other file. */ - #ifdef SCORE_INIT #undef SCORE_EXTERN #define SCORE_EXTERN @@ -55,6 +63,12 @@ extern "C" { #define SCORE_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef SAPI_INIT #undef SAPI_EXTERN #define SAPI_EXTERN @@ -63,6 +77,12 @@ extern "C" { #define SAPI_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef RTEMS_API_INIT #undef RTEMS_EXTERN #define RTEMS_EXTERN @@ -71,6 +91,12 @@ extern "C" { #define RTEMS_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef POSIX_API_INIT #undef POSIX_EXTERN #define POSIX_EXTERN @@ -79,6 +105,12 @@ extern "C" { #define POSIX_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef ITRON_API_INIT #undef ITRON_EXTERN #define ITRON_EXTERN @@ -87,13 +119,12 @@ extern "C" { #define ITRON_EXTERN extern #endif -/* +/** * The following (in conjunction with compiler arguments) are used * to choose between the use of static inline functions and macro * functions. The static inline implementation allows better * type checking with no cost in code size or execution speed. */ - #ifdef RTEMS_INLINES # ifdef __GNUC__ # define RTEMS_INLINE_ROUTINE static __inline__ @@ -104,13 +135,14 @@ extern "C" { # define RTEMS_INLINE_ROUTINE #endif -/* - * The following are used by the POSIX implementation to catch bad paths. - */ - #ifdef RTEMS_POSIX_API +/** The following is used by the POSIX implementation to catch bad paths. */ int POSIX_MP_NOT_IMPLEMENTED( void ); + +/** The following is used by the POSIX implementation to catch bad paths. */ int POSIX_NOT_IMPLEMENTED( void ); + +/** The following is used by the POSIX implementation to catch bad paths. */ int POSIX_BOTTOM_REACHED( void ); #endif @@ -118,24 +150,21 @@ int POSIX_BOTTOM_REACHED( void ); * Include a base set of files. */ -/* +/** * XXX: Eventually proc_ptr needs to disappear!!! */ - typedef void * proc_ptr; #include -/* - * Boolean constants - */ - #if !defined( TRUE ) || (TRUE != 1) +/** Boolean constant TRUE */ #undef TRUE #define TRUE (1) #endif #if !defined( FALSE ) || (FALSE != 0) +/** Boolean constant TRUE */ #undef FALSE #define FALSE (0) #endif @@ -143,67 +172,81 @@ typedef void * proc_ptr; #include #include /* processor specific information */ +/** + * This macro is used to obtain the offset of a field in a structure. + */ #define RTEMS_offsetof(type, field) \ - ((uint32_t ) &(((type *) 0)->field)) + ((uint32_t ) &(((type *) 0)->field)) -/* +/** * The following is the extern for the RTEMS version string. - * The contents of this string are CPU specific. + * + * @note The contents of this string are CPU specific. */ +extern const char _RTEMS_version[]; -extern const char _RTEMS_version[]; /* RTEMS version string */ -extern const char _Copyright_Notice[]; /* RTEMS copyright string */ +/** + * The following is the extern for the RTEMS copyright string. + */ +extern const char _Copyright_Notice[]; -/* +/** * The following defines the CPU dependent information table. */ - -SCORE_EXTERN rtems_cpu_table _CPU_Table; /* CPU dependent info */ +SCORE_EXTERN rtems_cpu_table _CPU_Table; /* * Macros to access CPU Table fields required by ALL ports. - * - * @note Similar macros to access port specific fields in in the - * appropriate cpu.h file. */ -#define rtems_cpu_configuration_get_table() \ - (&_CPU_Table) +/** This macro assists in accessing the CPU Specific Configuration Table. */ +#define rtems_cpu_configuration_get_table() (&_CPU_Table) + +/** This macro assists in accessing the pretasking BSP hook. */ #define rtems_cpu_configuration_get_pretasking_hook() \ (_CPU_Table.pretasking_hook) +/** This macro assists in accessing the predriver BSP hook. */ #define rtems_cpu_configuration_get_predriver_hook() \ (_CPU_Table.predriver_hook) +/** This macro assists in accessing the postdriver BSP hook. */ #define rtems_cpu_configuration_get_postdriver_hook() \ (_CPU_Table.postdriver_hook) +/** This macro assists in accessing the BSP specific IDLE task entry point. */ #define rtems_cpu_configuration_get_idle_task() \ (_CPU_Table.idle_task) +/** + * This macro assists in accessing the field which indicates whether + * RTEMS is responsible for zeroing the Executive Workspace. + */ #define rtems_cpu_configuration_get_do_zero_of_workspace() \ (_CPU_Table.do_zero_of_workspace) +/** This macro assists in accessing the IDLE task stack point size. */ #define rtems_cpu_configuration_get_idle_task_stack_size() \ (_CPU_Table.idle_task_stack_size) +/** This macro assists in accessing the interrupt stack size. */ #define rtems_cpu_configuration_get_interrupt_stack_size() \ (_CPU_Table.interrupt_stack_size) +/** This macro assists in accessing the size of the MPCI receiver server. */ #define rtems_cpu_configuration_get_extra_mpci_receive_server_stack() \ (_CPU_Table.extra_mpci_receive_server_stack) +/** This macro assists in accessing the BSP stack allocation hook. */ #define rtems_cpu_configuration_get_stack_allocate_hook() \ (_CPU_Table.stack_allocate_hook) +/** This macro assists in accessing the BSP stack allocation free hook. */ #define rtems_cpu_configuration_get_stack_free_hook() \ (_CPU_Table.stack_free_hook) -/* - * XXX weird RTEMS stuff that probably should be somewhere else. - */ - +/** This macro defines the maximum length of a Classic API name. */ #define RTEMS_MAXIMUM_NAME_LENGTH sizeof(rtems_name) #ifdef __cplusplus diff --git a/cpukit/score/inline/rtems/score/address.inl b/cpukit/score/inline/rtems/score/address.inl index e8e260910f..19cf03699c 100644 --- a/cpukit/score/inline/rtems/score/address.inl +++ b/cpukit/score/inline/rtems/score/address.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,12 +24,17 @@ * @{ */ -/** - * This function is used to add an offset to a base address. +/** @brief Add Offset to Address + * + * This function is used to add an @a offset to a @a base address. * It returns the resulting address. This address is typically * converted to an access type before being used further. + * + * @param[in] base is the base address. + * @param[in] offset is the offset to add to @a base. + * + * @return This method returns the resulting address. */ - RTEMS_INLINE_ROUTINE void *_Addresses_Add_offset ( void *base, uint32_t offset @@ -38,10 +43,16 @@ RTEMS_INLINE_ROUTINE void *_Addresses_Add_offset ( return (void *)((char *)base + offset); } -/** - * This function is used to subtract an offset from a base +/** @brief Subtract Offset from Offset + * + * This function is used to subtract an @a offset from a @a base * address. It returns the resulting address. This address is * typically converted to an access type before being used further. + * + * @param[in] base is the base address. + * @param[in] offset is the offset to subtract to @a base. + * + * @return This method returns the resulting address. */ RTEMS_INLINE_ROUTINE void *_Addresses_Subtract_offset ( @@ -52,14 +63,19 @@ RTEMS_INLINE_ROUTINE void *_Addresses_Subtract_offset ( return (void *)((char *)base - offset); } -/** +/** @brief Subtract Two Offsets + * * This function is used to subtract two addresses. It returns the * resulting offset. * - * @note The cast of an address to an uint32_t makes this code + * @param[in] left is the address on the left hand side of the subtraction. + * @param[in] right is the address on the right hand side of the subtraction. + * + * @return This method returns the resulting address. + * + * @note The cast of an address to an uint32_t makes this code * dependent on an addresses being thirty two bits. */ - RTEMS_INLINE_ROUTINE uint32_t _Addresses_Subtract ( void *left, void *right @@ -68,12 +84,17 @@ RTEMS_INLINE_ROUTINE uint32_t _Addresses_Subtract ( return ((char *) left - (char *) right); } -/** +/** @brief Is Address Aligned + * * This function returns TRUE if the given address is correctly * aligned for this processor and FALSE otherwise. Proper alignment * is based on correctness and efficiency. + * + * @param[in] address is the address being checked for alignment. + * + * @return This method returns TRUE if the address is aligned and + * FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Addresses_Is_aligned ( void *address ) @@ -81,25 +102,32 @@ RTEMS_INLINE_ROUTINE boolean _Addresses_Is_aligned ( #if (CPU_ALIGNMENT == 0) return TRUE; #else - return ( ( (uintptr_t)address % CPU_ALIGNMENT ) == 0 ); + return (((uintptr_t)address % CPU_ALIGNMENT) == 0); #endif } -/** +/** @brief Is Address In Range + * * This function returns TRUE if the given address is within the * memory range specified and FALSE otherwise. base is the address * of the first byte in the memory range and limit is the address * of the last byte in the memory range. The base address is * assumed to be lower than the limit address. + * + * @param[in] address is the address to check. + * @param[in] base is the lowest address of the range to check against. + * @param[in] limit is the highest address of the range to check against. + * + * @return This method returns TRUE if the given @a address is within the + * memory range specified and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Addresses_Is_in_range ( void *address, void *base, void *limit ) { - return ( address >= base && address <= limit ); + return (address >= base && address <= limit); } /**@}*/ diff --git a/cpukit/score/inline/rtems/score/chain.inl b/cpukit/score/inline/rtems/score/chain.inl index 3a6f10e2e6..d394ec93e1 100644 --- a/cpukit/score/inline/rtems/score/chain.inl +++ b/cpukit/score/inline/rtems/score/chain.inl @@ -10,7 +10,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,9 +28,16 @@ * @{ */ -/** - * This function returns TRUE if \a left and \a right are equal, +/** @brief Are Two Nodes Equal + * + * This function returns TRUE if @a left and @a right are equal, * and FALSE otherwise. + * + * @param[in] left is the node on the left hand side of the comparison. + * @param[in] right is the node on the left hand side of the comparison. + * + * @return This function returns TRUE if @a left and @a right are equal, + * and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal( Chain_Node *left, @@ -40,28 +47,43 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal( return left == right; } -/** +/** @brief Is this Chain Control Pointer Null + * * This function returns TRUE if the_chain is NULL and FALSE otherwise. + * + * @param[in] the_chain is the chain to be checked for empty status. + * + * @return This method returns TRUE if the_chain is NULL and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_null( Chain_Control *the_chain ) { - return ( the_chain == NULL ); + return (the_chain == NULL); } -/** + +/** @brief Is the Chain Node Pointer NULL + * * This function returns TRUE if the_node is NULL and FALSE otherwise. + * + * @param[in] the_node is the node pointer to check. + * + * @return This method returns TRUE if the_node is NULL and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Chain_Is_null_node( Chain_Node *the_node ) { - return ( the_node == NULL ); + return (the_node == NULL); } -/** +/** @brief Return pointer to Chain Head + * * This function returns a pointer to the first node on the chain. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This method returns the permanent head node of the chain. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head( Chain_Control *the_chain @@ -70,8 +92,13 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head( return (Chain_Node *) the_chain; } -/** +/** @brief Return pointer to Chain Tail + * * This function returns a pointer to the last node on the chain. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This method returns the permanent tail node of the chain. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail( Chain_Control *the_chain @@ -80,92 +107,132 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail( return (Chain_Node *) &the_chain->permanent_null; } -/** - * This function returns TRUE if there a no nodes on the_chain and +/** @brief Is the Chain Empty + * + * This function returns TRUE if there a no nodes on @a the_chain and + * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This function returns TRUE if there a no nodes on @a the_chain and * FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty( Chain_Control *the_chain ) { - return ( the_chain->first == _Chain_Tail( the_chain ) ); + return (the_chain->first == _Chain_Tail(the_chain)); } -/** +/** @brief Is this the First Node on the Chain + * * This function returns TRUE if the_node is the first node on a chain and * FALSE otherwise. + * + * @param[in] the_node is the node the caller wants to know if it is + * the first node on a chain. + * + * @return This function returns TRUE if @a the_node is the first node on + * a chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_first( Chain_Node *the_node ) { - return ( the_node->previous == NULL ); + return (the_node->previous == NULL); } -/** - * This function returns TRUE if \a the_node is the last node on a chain and +/** @brief Is this the Last Node on the Chain + * + * This function returns TRUE if @a the_node is the last node on a chain and * FALSE otherwise. + * + * @param[in] the_node is the node to check as the last node. + * + * @return This function returns TRUE if @a the_node is the last node on + * a chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_last( Chain_Node *the_node ) { - return ( the_node->next == NULL ); + return (the_node->next == NULL); } -/** - * This function returns TRUE if there is only one node on \a the_chain and +/** @brief Does this Chain have only One Node + * + * This function returns TRUE if there is only one node on @a the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This function returns TRUE if there is only one node on + * @a the_chain and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Chain_Has_only_one_node( Chain_Control *the_chain ) { - return ( the_chain->first == the_chain->last ); + return (the_chain->first == the_chain->last); } -/** - * This function returns TRUE if the_node is the head of the_chain and +/** @brief Is this Node the Chain Head + * + * This function returns TRUE if @a the_node is the head of the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to check for being the Chain Head. + * + * @return This function returns TRUE if @a the_node is the head of + * @a the_chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_head( Chain_Control *the_chain, Chain_Node *the_node ) { - return ( the_node == _Chain_Head( the_chain ) ); + return (the_node == _Chain_Head(the_chain)); } -/** +/** @brief Is this Node the Chail Tail + * * This function returns TRUE if the_node is the tail of the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to check for being the Chain Tail. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail( Chain_Control *the_chain, Chain_Node *the_node ) { - return ( the_node == _Chain_Tail( the_chain ) ); + return (the_node == _Chain_Tail(the_chain)); } -/** +/** @brief Initialize this Chain as Empty + * * This routine initializes the specified chain to contain zero nodes. + * + * @param[in] the_chain is the chain to be initialized. */ - RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty( Chain_Control *the_chain ) { - the_chain->first = _Chain_Tail( the_chain ); + the_chain->first = _Chain_Tail(the_chain); the_chain->permanent_null = NULL; - the_chain->last = _Chain_Head( the_chain ); + the_chain->last = _Chain_Head(the_chain); } -/** +/** @brief Extract this Node (unprotected) + * * This routine extracts the_node from the chain on which it resides. - * It does NOT disable interrupts to insure the atomicity of the + * It does NOT disable interrupts to ensure the atomicity of the * extract operation. + * + * @param[in] the_node is the node to be extracted. */ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected( Chain_Node *the_node @@ -180,10 +247,19 @@ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected( previous->next = next; } -/** +/** @brief Get the First Node (unprotected) + * * This function removes the first node from the_chain and returns - * a pointer to that node. It does NOT disable interrupts to insure + * a pointer to that node. It does NOT disable interrupts to ensure * the atomicity of the get operation. + * + * @param[in] the_chain is the chain to attempt to get the first node from. + * + * @return This method returns the first node on the chain even if it is + * the Chain Tail. + * + * @note This routine assumes that there is at least one node on the chain + * and always returns a node even if it is the Chain Tail. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected( Chain_Control *the_chain @@ -195,33 +271,46 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected( return_node = the_chain->first; new_first = return_node->next; the_chain->first = new_first; - new_first->previous = _Chain_Head( the_chain ); + new_first->previous = _Chain_Head(the_chain); return return_node; } -/** +/** @brief Get the First Node (unprotected) + * * 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 does NOT disable interrupts to insure the atomicity of the - * get operation. + * + * @param[in] the_chain is the chain to attempt to get the first node from. + * + * @return This method returns the first node on the chain or NULL if the + * chain is empty. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * get operation. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_unprotected( Chain_Control *the_chain ) { - if ( !_Chain_Is_empty( the_chain ) ) - return _Chain_Get_first_unprotected( the_chain ); + if ( !_Chain_Is_empty(the_chain)) + return _Chain_Get_first_unprotected(the_chain); else return NULL; } -/** +/** @brief Insert a Node (unprotected) + * * This routine inserts the_node on a chain immediately following - * after_node. It does NOT disable interrupts to insure the atomicity - * of the extract operation. + * after_node. + * + * @param[in] after_node is the node which will precede @a the_node on the + * chain. + * @param[in] the_node is the node to be inserted. + * + * @note It does NOT disable interrupts to ensure the atomicity + * of the extract operation. */ - RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected( Chain_Node *after_node, Chain_Node *the_node @@ -236,10 +325,15 @@ RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected( before_node->previous = the_node; } -/** +/** @brief Append a Node (unprotected) + * * This routine appends the_node onto the end of the_chain. - * It does NOT disable interrupts to insure the atomicity of the - * append operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be appended. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * append operation. */ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected( Chain_Control *the_chain, @@ -248,37 +342,47 @@ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected( { Chain_Node *old_last_node; - the_node->next = _Chain_Tail( the_chain ); + the_node->next = _Chain_Tail(the_chain); old_last_node = the_chain->last; the_chain->last = the_node; old_last_node->next = the_node; the_node->previous = old_last_node; } -/** +/** @brief Prepend a Node (unprotected) + * * This routine prepends the_node onto the front of the_chain. - * It does NOT disable interrupts to insure the atomicity of the - * prepend operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be prepended. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void _Chain_Prepend_unprotected( Chain_Control *the_chain, Chain_Node *the_node ) { - _Chain_Insert_unprotected( _Chain_Head( the_chain ), the_node ); + _Chain_Insert_unprotected(_Chain_Head(the_chain), the_node); } -/** +/** @brief Prepend a Node (protected) + * * This routine prepends the_node onto the front of the_chain. - * It disables interrupts to insure the atomicity of the - * prepend operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be prepended. + * + * @note It disables interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void _Chain_Prepend( Chain_Control *the_chain, Chain_Node *the_node ) { - _Chain_Insert( _Chain_Head( the_chain ), the_node ); + _Chain_Insert(_Chain_Head(the_chain), the_node); } /**@}*/ diff --git a/cpukit/score/inline/rtems/score/coremutex.inl b/cpukit/score/inline/rtems/score/coremutex.inl index e186b197cd..2bde4a888f 100644 --- a/cpukit/score/inline/rtems/score/coremutex.inl +++ b/cpukit/score/inline/rtems/score/coremutex.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -25,10 +25,15 @@ */ /** + * @brief Is Mutex Locked + * * This routine returns TRUE if the mutex specified is locked and FALSE * otherwise. + * + * @param[in] the_mutex is the mutex to check + * + * @return This method returns TRUE if the mutex is locked. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_locked( CORE_mutex_Control *the_mutex ) @@ -37,10 +42,15 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_locked( } /** + * @brief Does Core Mutex Use FIFO Blocking + * * This routine returns TRUE if the mutex's wait discipline is FIFO and FALSE * otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using FIFO blocking order. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_fifo( CORE_mutex_Attributes *the_attribute ) @@ -49,10 +59,16 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_fifo( } /** + * @brief Doex Core Mutex Use Priority Blocking + * * This routine returns TRUE if the mutex's wait discipline is PRIORITY and * FALSE otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using + * priority blocking order. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority( CORE_mutex_Attributes *the_attribute ) @@ -61,10 +77,16 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority( } /** + * @brief Does Mutex Use Priority Inheritance + * * This routine returns TRUE if the mutex's wait discipline is * INHERIT_PRIORITY and FALSE otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using priority + * inheritance. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_inherit_priority( CORE_mutex_Attributes *the_attribute ) @@ -73,10 +95,16 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_inherit_priority( } /** + * @brief Does Mutex Use Priority Ceiling + * * This routine returns TRUE if the mutex's wait discipline is * PRIORITY_CEILING and FALSE otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using priority + * ceiling. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority_ceiling( CORE_mutex_Attributes *the_attribute ) @@ -85,14 +113,10 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority_ceiling( } /* - * This routine returns 0 if "trylock" can resolve whether or not the - * mutex is immediately obtained or there was an error attempting to - * get it. It returns 1 to indicate that the caller cannot obtain - * the mutex and will have to block to do so. - * - * NOTE: There is no MACRO version of this routine. - * A body is in coremutexseize.c that is duplicated - * from the .inl by hand. + * Seize Mutex with Quick Success Path + * + * NOTE: There is no MACRO version of this routine. A body is in + * coremutexseize.c that is duplicated from the .inl by hand. * * NOTE: The Doxygen for this routine is in the .h file. */ diff --git a/cpukit/score/inline/rtems/score/coresem.inl b/cpukit/score/inline/rtems/score/coresem.inl index 944c73190b..c7e6b69605 100644 --- a/cpukit/score/inline/rtems/score/coresem.inl +++ b/cpukit/score/inline/rtems/score/coresem.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -31,7 +31,7 @@ * This function returns TRUE if the priority attribute is * enabled in the attribute_set and FALSE otherwise. * - * @param the_attribute (in) is the attribute set to test + * @param[in] the_attribute is the attribute set to test * @return TRUE if the priority attribute is enabled */ RTEMS_INLINE_ROUTINE boolean _CORE_semaphore_Is_priority( @@ -44,7 +44,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_semaphore_Is_priority( /** * This routine returns the current count associated with the semaphore. * - * @param the_semaphore (in) is the semaphore to obtain the count of + * @param[in] the_semaphore is the semaphore to obtain the count of * @return the current count of this semaphore */ RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count( @@ -60,11 +60,11 @@ RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count( * returns. Otherwise, the calling task is blocked until a unit becomes * available. * - * @param the_semaphore (in) is the semaphore to obtain - * @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_p (in) is a temporary variable used to contain the ISR + * @param[in] the_semaphore is the semaphore to obtain + * @param[in] id is the Id of the owning API level Semaphore object + * @param[in] wait is TRUE if the thread is willing to wait + * @param[in] timeout is the maximum number of ticks to block + * @param[in] level_p is a temporary variable used to contain the ISR * disable level cookie * * @note There is currently no MACRO version of this routine. diff --git a/cpukit/score/inline/rtems/score/heap.inl b/cpukit/score/inline/rtems/score/heap.inl index 645551e153..d34ce759ee 100644 --- a/cpukit/score/inline/rtems/score/heap.inl +++ b/cpukit/score/inline/rtems/score/heap.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,8 +28,12 @@ /** * This function returns the head of the specified heap. + * + * @param[in] the_heap points to the heap being operated upon + * + * @return This method returns a pointer to the dummy head of the free + * block list. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head ( Heap_Control *the_heap ) @@ -39,8 +43,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head ( /** * This function returns the tail of the specified heap. + * + * @param[in] the_heap points to the heap being operated upon + * + * @return This method returns a pointer to the dummy tail of the heap + * free list. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail ( Heap_Control *the_heap ) @@ -50,8 +58,11 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail ( /** * Return the first free block of the specified heap. + * + * @param[in] the_heap points to the heap being operated upon + * + * @return This method returns a pointer to the first free block. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_First ( Heap_Control *the_heap ) @@ -59,15 +70,13 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_First ( return _Heap_Head(the_heap)->next; } -/*PAGE - * - * _Heap_Last +/** + * Return the last free block of the specified heap. * - * DESCRIPTION: + * @param[in] the_heap points to the heap being operated upon * - * Return the last free block of the specified heap. + * @return This method returns a pointer to the last block on the free list. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Last ( Heap_Control *the_heap ) @@ -75,15 +84,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Last ( return _Heap_Tail(the_heap)->prev; } -/*PAGE - * - * _Heap_Block_remove - * - * DESCRIPTION: - * +/** * This function removes 'the_block' from doubly-linked list. + * + * @param[in] the_block is the block to remove from the heap used block + * list. */ - RTEMS_INLINE_ROUTINE void _Heap_Block_remove ( Heap_Block *the_block ) @@ -98,6 +104,14 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_remove ( /** * This function replaces @a old_block by @a new_block in doubly-linked list. + * When a block is allocated, the memory is allocated from the low memory + * address range of the block. This means that the upper address range of + * the memory block must be added to the free block list in place of the + * lower address portion being allocated. This method is also used as part + * of resizing a block. + * + * @param[in] old_block is the block which is currently on the list. + * @param[in] new_block is the new block which will replace it on the list. */ RTEMS_INLINE_ROUTINE void _Heap_Block_replace ( @@ -117,7 +131,10 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_replace ( /** * This function inserts @a the_block after @a prev_block - * in doubly-linked list. + * in the doubly-linked free block list. + * + * @param[in] prev_block is the previous block in the free list. + * @param[in] the_block is the block being freed. */ RTEMS_INLINE_ROUTINE void _Heap_Block_insert_after ( Heap_Block *prev_block, @@ -135,8 +152,13 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_insert_after ( /** * Return TRUE if @a value is a multiple of @a alignment, FALSE otherwise + * + * @param[in] value is the address to verify alignment of. + * @param[in] alignment is the alignment factor to verify. + * + * @return This method returns TRUE if the address is aligned and false + * otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned ( uint32_t value, uint32_t alignment @@ -147,8 +169,12 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned ( /** * Align @a *value up to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_up ( uint32_t *value, uint32_t alignment @@ -162,8 +188,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_up ( /** * Align @a *value down to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_down ( uint32_t *value, uint32_t alignment @@ -175,11 +205,16 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_down ( /** * Return TRUE if @a ptr is aligned at @a alignment boundary, - * FALSE otherwise + * FALSE otherwise. + * + * @param[in] ptr is the pointer to verify alignment of. + * @param[in] alignment is the alignment factor. + * + * @return This method returns TRUE if @a ptr is aligned at @a alignment + * boundary, and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned_ptr ( - void *ptr, + void *ptr, uint32_t alignment ) { @@ -188,8 +223,12 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned_ptr ( /** * Align @a *value up to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_up_uptr ( _H_uptr_t *value, uint32_t alignment @@ -203,8 +242,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_up_uptr ( /** * Align @a *value down to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_down_uptr ( _H_uptr_t *value, uint32_t alignment @@ -217,10 +260,14 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_down_uptr ( /** * This function calculates and returns a block's location (address) * in the heap based upon a base address @a base and an @a offset. + * + * @param[in] base is the base address of the memory area. + * @param[in] offset is the byte offset into @a base. + * + * @return This method returns a pointer to the block's address. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at( - void *base, + void *base, uint32_t offset ) { @@ -230,8 +277,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at( /** * This function returns the starting address of the portion of @a the_block * which the user may access. + * + * @param[in] the_block is the heap block to find the user area of. + * + * @return This method returns a pointer to the start of the user area in + * the block. */ - RTEMS_INLINE_ROUTINE void *_Heap_User_area ( Heap_Block *the_block ) @@ -242,8 +293,14 @@ RTEMS_INLINE_ROUTINE void *_Heap_User_area ( /** * Fill @a *the_block with the address of the beginning of the block given * pointer to the user accessible area @a base. + * + * @param[in] the_heap points to the heap being operated upon + * @param[in] base points to the user area in the block. + * @param[in] the_block will be the address of the heap block. + * + * @return This method returns a pointer to the heap block based upon the + * given heap and user pointer. */ - RTEMS_INLINE_ROUTINE void _Heap_Start_of_block ( Heap_Control *the_heap, void *base, @@ -262,8 +319,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Start_of_block ( /** * This function returns TRUE if the previous block of @a the_block * is in use, and FALSE otherwise. + * + * @param[in] the_block is the block to operate upon. + * + * @return This method returns TRUE if the previous block is used and FALSE + * if the previous block is free. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_prev_used ( Heap_Block *the_block ) @@ -273,8 +334,11 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_prev_used ( /** * This function returns the size of @a the_block in bytes. + * + * @param[in] the_block is the block to operate upon. + * + * @return This method returns the size of the specified heap block in bytes. */ - RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size ( Heap_Block *the_block ) @@ -285,8 +349,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size ( /** * This function returns TRUE if @a the_block is within the memory area * managed by @a the_heap, and FALSE otherwise. + * + * @param[in] the_heap points to the heap being operated upon + * @param[in] the_block is the block address to check. + * + * @return This method returns TRUE if @a the_block appears to have been + * allocated from @a the_heap, and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_block_in ( Heap_Control *the_heap, Heap_Block *the_block diff --git a/cpukit/score/inline/rtems/score/object.inl b/cpukit/score/inline/rtems/score/object.inl index ac6d873fc8..e3e17bdb69 100644 --- a/cpukit/score/inline/rtems/score/object.inl +++ b/cpukit/score/inline/rtems/score/object.inl @@ -7,7 +7,7 @@ * This include file contains the static inline implementation of all * of the inlined routines in the Object Handler. * - * COPYRIGHT (c) 1989-2002. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -20,16 +20,18 @@ #ifndef _RTEMS_SCORE_OBJECT_INL #define _RTEMS_SCORE_OBJECT_INL -/*PAGE - * - * _Objects_Build_id - * - * DESCRIPTION: - * +/** * This function builds an object's id from the processor node and index * values specified. + * + * @param[in] the_api indicates the API associated with this Id. + * @param[in] the_class indicates the class of object. + * It is specific to @a the_api. + * @param[in] node is the node where this object resides. + * @param[in] index is the instance number of this object. + * + * @return This method returns an object Id constructed from the arguments. */ - RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id( Objects_APIs the_api, uint32_t the_class, @@ -43,15 +45,13 @@ RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id( (( (Objects_Id) index ) << OBJECTS_INDEX_START_BIT); } -/*PAGE - * - * _Objects_Get_API +/** + * This function returns the API portion of the ID. * - * DESCRIPTION: + * @param[in] id is the object Id to be processed. * - * This function returns the API portion of the ID. + * @return This method returns an object Id constructed from the arguments. */ - RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API( Objects_Id id ) @@ -59,15 +59,11 @@ RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API( return (Objects_APIs) ((id >> OBJECTS_API_START_BIT) & OBJECTS_API_VALID_BITS); } -/*PAGE - * - * _Objects_Get_class - * - * DESCRIPTION: - * +/** * This function returns the class portion of the ID. + * + * @param[in] id is the object Id to be processed */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class( Objects_Id id ) @@ -76,15 +72,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class( ((id >> OBJECTS_CLASS_START_BIT) & OBJECTS_CLASS_VALID_BITS); } -/*PAGE - * - * _Objects_Get_node +/** + * This function returns the node portion of the ID. * - * DESCRIPTION: + * @param[in] id is the object Id to be processed * - * This function returns the node portion of the ID. + * @return This method returns the node portion of an object ID. */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node( Objects_Id id ) @@ -92,15 +86,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node( return (id >> OBJECTS_NODE_START_BIT) & OBJECTS_NODE_VALID_BITS; } -/*PAGE - * - * _Objects_Get_index +/** + * This function returns the index portion of the ID. * - * DESCRIPTION: + * @param[in] id is the Id to be processed * - * This function returns the index portion of the ID. + * @return This method returns the class portion of the specified object ID. */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_index( Objects_Id id ) @@ -108,15 +100,14 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_index( return (id >> OBJECTS_INDEX_START_BIT) & OBJECTS_INDEX_VALID_BITS; } -/*PAGE - * - * _Objects_Is_class_valid +/** + * This function returns TRUE if the class is valid. * - * DESCRIPTION: + * @param[in] the_class is the class portion of an object ID. * - * This function returns TRUE if the class is valid. + * @return This method returns TRUE if the specified class value is valid + * and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Is_class_valid( uint32_t the_class ) @@ -125,17 +116,17 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_class_valid( return TRUE; /* the_class && the_class <= OBJECTS_CLASSES_LAST; */ } -/*PAGE - * - * _Objects_Is_local_node - * - * DESCRIPTION: - * +#if defined(RTEMS_MULTIPROCESSING) +/** * This function returns TRUE if the node is of the local object, and * FALSE otherwise. + * + * @param[in] node is the node number and corresponds to the node number + * portion of an object ID. + * + * @return This method returns TRUE if the specified node is the local node + * and FALSE otherwise. */ - -#if defined(RTEMS_MULTIPROCESSING) RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_node( uint32_t node ) @@ -144,16 +135,17 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_node( } #endif -/*PAGE +/** + * This function returns TRUE if the id is of a local object, and + * FALSE otherwise. * - * _Objects_Is_local_id + * @param[in] id is an object ID * - * DESCRIPTION: + * @return This method returns TRUE if the specified object Id is local + * and FALSE otherwise. * - * This function returns TRUE if the id is of a local object, and - * FALSE otherwise. + * @note On a single processor configuration, this always returns TRUE. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_id( Objects_Id id ) @@ -165,17 +157,16 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_id( #endif } - -/*PAGE - * - * _Objects_Are_ids_equal - * - * DESCRIPTION: - * +/** * This function returns TRUE if left and right are equal, * and FALSE otherwise. + * + * @param[in] left is the Id on the left hand side of the comparison + * @param[in] right is the Id on the right hand side of the comparison + * + * @return This method returns TRUE if the specified object IDs are equal + * and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Are_ids_equal( Objects_Id left, Objects_Id right @@ -184,16 +175,16 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Are_ids_equal( return ( left == right ); } -/*PAGE - * - * _Objects_Get_local_object - * - * DESCRIPTION: - * +/** * This function returns a pointer to the local_table object * referenced by the index. + * + * @param[in] information points to an Object Information Table + * @param[in] index is the index of the object the caller wants to access + * + * @return This method returns a pointer to a local object or NULL if the + * index is invalid. */ - RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object( Objects_Information *information, uint16_t index @@ -204,14 +195,13 @@ RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object( return information->local_table[ index ]; } -/*PAGE - * - * _Objects_Set_local_object - * - * DESCRIPTION: - * +/** * This function sets the pointer to the local_table object * referenced by the index. + * + * @param[in] information points to an Object Information Table + * @param[in] index is the index of the object the caller wants to access + * @param[in] the_object is the local object pointer */ RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( @@ -224,17 +214,16 @@ RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( information->local_table[ index ] = the_object; } - -/*PAGE +/** + * This function return the information structure given + * an id of an object. * - * _Objects_Get_information + * @param[in] id is an object ID * - * DESCRIPTION: * - * This function return the information structure given - * an id of an object. + * @return This method returns a pointer to the Object Information Table + * for the class of objects which corresponds to this object ID. */ - RTEMS_INLINE_ROUTINE Objects_Information *_Objects_Get_information( Objects_Id id ) @@ -252,16 +241,14 @@ RTEMS_INLINE_ROUTINE Objects_Information *_Objects_Get_information( return _Objects_Information_table[ the_api ][ the_class ]; } -/*PAGE - * - * _Objects_Open - * - * DESCRIPTION: - * +/** * This function places the_object control pointer and object name * in the Local Pointer and Local Name Tables, respectively. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object + * @param[in] name is the name of the object to make accessible */ - RTEMS_INLINE_ROUTINE void _Objects_Open( Objects_Information *information, Objects_Control *the_object, @@ -281,16 +268,13 @@ RTEMS_INLINE_ROUTINE void _Objects_Open( the_object->name = name; } -/*PAGE - * - * _Objects_Close - * - * DESCRIPTION: - * +/** * This function removes the_object control pointer and object name * in the Local Pointer and Local Name Tables. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object */ - RTEMS_INLINE_ROUTINE void _Objects_Close( Objects_Information *information, Objects_Control *the_object @@ -304,15 +288,12 @@ RTEMS_INLINE_ROUTINE void _Objects_Close( the_object->name = 0; } -/*PAGE - * - * _Objects_Namespace_remove - * - * DESCRIPTION: - * +/** * This function removes the_object from the namespace. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object */ - RTEMS_INLINE_ROUTINE void _Objects_Namespace_remove( Objects_Information *information, Objects_Control *the_object diff --git a/cpukit/score/inline/rtems/score/stack.inl b/cpukit/score/inline/rtems/score/stack.inl index 83df22fd2a..863d703aa3 100644 --- a/cpukit/score/inline/rtems/score/stack.inl +++ b/cpukit/score/inline/rtems/score/stack.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -53,7 +53,7 @@ RTEMS_INLINE_ROUTINE boolean _Stack_Is_enough ( } /** - * This function increases the stack size to insure that the thread + * This function increases the stack size to ensure that the thread * has the desired amount of stack space after the initial stack * pointer is determined based on alignment restrictions. * diff --git a/cpukit/score/inline/rtems/score/thread.inl b/cpukit/score/inline/rtems/score/thread.inl index 0ac5887588..1599883d70 100644 --- a/cpukit/score/inline/rtems/score/thread.inl +++ b/cpukit/score/inline/rtems/score/thread.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -224,7 +224,11 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_null ( * Otherwise, location is set to OBJECTS_ERROR and * the_thread is undefined. * - * @note XXX... This routine may be able to be optimized. + * @note The performance of many RTEMS services depends upon + * the quick execution of the "good object" path in this + * routine. If there is a possibility of saving a few + * cycles off the execution time, this routine is worth + * further optimization attention. */ RTEMS_INLINE_ROUTINE Thread_Control *_Thread_Get ( diff --git a/cpukit/score/inline/rtems/score/tqdata.inl b/cpukit/score/inline/rtems/score/tqdata.inl index c7f878baea..d1248f4b74 100644 --- a/cpukit/score/inline/rtems/score/tqdata.inl +++ b/cpukit/score/inline/rtems/score/tqdata.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -61,5 +61,9 @@ RTEMS_INLINE_ROUTINE void _Thread_queue_Enter_critical_section ( the_thread_queue->sync_state = THREAD_QUEUE_NOTHING_HAPPENED; } +/** + * @} + */ + #endif /* end of include file */ diff --git a/cpukit/score/macros/README b/cpukit/score/macros/README index b2f0c4d481..c2d2e607d6 100644 --- a/cpukit/score/macros/README +++ b/cpukit/score/macros/README @@ -9,10 +9,6 @@ tested. In general, an effort is made to keep the contents of this directory up to date but testing is only performed irregularly and even then it is usually with a single target processor and BSP. -The primary purpose of the code in this directory is to insure +The primary purpose of the code in this directory is to ensure that RTEMS can be compiled using a C compiler which does not support static inline routines. - -These were last successfully tested on 2/1/95 on a prerelease version -of 3.2.0. The testing was done only on the Force CPU386 i386 target board. -No testing was done on version of the code in the final release. diff --git a/cpukit/score/src/heap.c b/cpukit/score/src/heap.c index 5a38d3f449..5e7a8804d2 100644 --- a/cpukit/score/src/heap.c +++ b/cpukit/score/src/heap.c @@ -1,7 +1,7 @@ /* * Heap Handler * - * COPYRIGHT (c) 1989-1999. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -198,8 +198,7 @@ uint32_t _Heap_Initialize( * Internal routines shared by _Heap_Allocate() and _Heap_Allocate_aligned(). * * Note: there is no reason to put them into a separate file(s) as they are - * always required for heap to be usefull. - * + * always required for heap to be useful. */ /* @@ -213,7 +212,7 @@ uint32_t _Heap_Calc_block_size( { uint32_t block_size = size + HEAP_BLOCK_USED_OVERHEAD; _Heap_Align_up(&block_size, page_size); - if(block_size < min_size) block_size = min_size; + if (block_size < min_size) block_size = min_size; /* 'block_size' becomes <= 'size' if and only if overflow occured. */ return (block_size > size) ? block_size : 0; } @@ -226,8 +225,9 @@ uint32_t _Heap_Calc_block_size( */ uint32_t _Heap_Block_allocate( Heap_Control* the_heap, - Heap_Block* the_block, - uint32_t alloc_size) + Heap_Block* the_block, + uint32_t alloc_size +) { Heap_Statistics *const stats = &the_heap->stats; uint32_t const block_size = _Heap_Block_size(the_block); diff --git a/cpukit/score/src/threadmp.c b/cpukit/score/src/threadmp.c index 9a421a36a5..8b860bef2d 100644 --- a/cpukit/score/src/threadmp.c +++ b/cpukit/score/src/threadmp.c @@ -2,7 +2,7 @@ * Multiprocessing Support for the Thread Handler * * - * COPYRIGHT (c) 1989-1999. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -96,7 +96,7 @@ Thread_Control *_Thread_MP_Allocate_proxy ( ); /* - * NOTE: The following return insures that the compiler will + * NOTE: The following return ensures that the compiler will * think that all paths return a value. */ diff --git a/cpukit/score/src/threadready.c b/cpukit/score/src/threadready.c index 159924492c..c7f035fec0 100644 --- a/cpukit/score/src/threadready.c +++ b/cpukit/score/src/threadready.c @@ -2,7 +2,7 @@ * Thread Handler * * - * COPYRIGHT (c) 1989-1999. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -43,7 +43,7 @@ * Output parameters: NONE * * NOTE: This routine uses the "blocking" heir selection mechanism. - * This insures the correct heir after a thread restart. + * This ensures the correct heir after a thread restart. * * INTERRUPT LATENCY: * ready chain diff --git a/cpukit/score/src/threadstartmultitasking.c b/cpukit/score/src/threadstartmultitasking.c index 4e12d9a806..9422c54cba 100644 --- a/cpukit/score/src/threadstartmultitasking.c +++ b/cpukit/score/src/threadstartmultitasking.c @@ -2,7 +2,7 @@ * Thread Handler * * - * COPYRIGHT (c) 1989-1999. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -44,7 +44,7 @@ * Output parameters: NONE * * NOTE: This routine uses the "blocking" heir selection mechanism. - * This insures the correct heir after a thread restart. + * This ensures the correct heir after a thread restart. * * INTERRUPT LATENCY: * ready chain -- cgit v1.2.3