diff options
author | Alex Ivanov <alexivanov97@gmail.com> | 2013-01-08 07:13:41 -0600 |
---|---|---|
committer | Jennifer Averett <jennifer.averett@oarcorp.com> | 2013-01-08 07:13:41 -0600 |
commit | 27f071cd88134b995f562e7080ba9820f93d48df (patch) | |
tree | 1975c04f0412b6c400eb5ce26154080af7569d0a /cpukit/sapi | |
parent | libcsupport: Doxygen Clean Up Task #1 (diff) | |
download | rtems-27f071cd88134b995f562e7080ba9820f93d48df.tar.bz2 |
sapi: Doxygen Clean Up Task #1
Diffstat (limited to 'cpukit/sapi')
-rw-r--r-- | cpukit/sapi/include/confdefs.h | 408 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/cbs.h | 2 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/chain.h | 8 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/config.h | 83 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/extension.h | 6 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/fatal.h | 28 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/init.h | 74 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/io.h | 94 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/mptables.h | 2 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/rbheap.h | 31 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/rbtree.h | 19 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/sptables.h | 8 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/timespec.h | 7 | ||||
-rw-r--r-- | cpukit/sapi/inline/rtems/cbs.inl | 86 | ||||
-rw-r--r-- | cpukit/sapi/inline/rtems/chain.inl | 343 | ||||
-rw-r--r-- | cpukit/sapi/inline/rtems/extension.inl | 2 | ||||
-rw-r--r-- | cpukit/sapi/inline/rtems/rbtree.inl | 195 | ||||
-rw-r--r-- | cpukit/sapi/inline/rtems/timespec.inl | 165 |
18 files changed, 791 insertions, 770 deletions
diff --git a/cpukit/sapi/include/confdefs.h b/cpukit/sapi/include/confdefs.h index 2c0be5364f..a5b7b7a4fe 100644 --- a/cpukit/sapi/include/confdefs.h +++ b/cpukit/sapi/include/confdefs.h @@ -1,31 +1,31 @@ /** - * @file rtems/confdefs.h + * @file * * @brief Configuration Table Template that will be Instantiated * by an Application * - * This include file contains the configuration table template that will - * be instantiated by an application based on the setting of a number - * of macros. The macros are documented in the Configuring a System - * chapter of the Classic API User's Guide + * This include file contains the configuration table template that will + * be instantiated by an application based on the setting of a number + * of macros. The macros are documented in the Configuring a System + * chapter of the Classic API User's Guide * - * The model is to estimate the memory required for each configured item - * and sum those estimates. The estimate can be too high or too low for - * a variety of reasons: + * The model is to estimate the memory required for each configured item + * and sum those estimates. The estimate can be too high or too low for + * a variety of reasons: * - * Reasons estimate is too high: - * + FP contexts (not all tasks are FP) + * Reasons estimate is too high: + * + FP contexts (not all tasks are FP) * - * Reasons estimate is too low: - * + stacks greater than minimum size - * + messages - * + application must account for device driver resources - * + application must account for add-on library resource requirements + * Reasons estimate is too low: + * + stacks greater than minimum size + * + messages + * + application must account for device driver resources + * + application must account for add-on library resource requirements * - * NOTE: Eventually this may be able to take into account some of - * the above. This procedure has evolved from just enough to - * support the RTEMS Test Suites into something that can be - * used remarkably reliably by most applications. + * NOTE: Eventually this may be able to take into account some of + * the above. This procedure has evolved from just enough to + * support the RTEMS Test Suites into something that can be + * used remarkably reliably by most applications. */ /* @@ -61,8 +61,8 @@ extern rtems_driver_address_table Device_drivers[]; #endif /** - * This macro determines whether the RTEMS reentrancy support for - * the Newlib C Library is enabled. + * This macro determines whether the RTEMS reentrancy support for + * the Newlib C Library is enabled. */ #ifdef RTEMS_SCHEDSIM #undef RTEMS_NEWLIB @@ -110,62 +110,62 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This macro defines the number of POSIX file descriptors allocated - * and managed by libio. These are the "integer" file descriptors that - * are used by calls like open(2) and read(2). + * This macro defines the number of POSIX file descriptors allocated + * and managed by libio. These are the "integer" file descriptors that + * are used by calls like open(2) and read(2). */ #ifndef CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS #define CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS 3 #endif /** - * Semaphore count used by the IO library. + * Semaphore count used by the IO library. */ #define CONFIGURE_LIBIO_SEMAPHORES 1 #ifdef CONFIGURE_INIT /** - * When instantiating the configuration tables, this variable is - * initialized to specify the maximum number of file descriptors. + * When instantiating the configuration tables, this variable is + * initialized to specify the maximum number of file descriptors. */ uint32_t rtems_libio_number_iops = CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS; #endif /** - * This macro determines if termios is disabled by this application. - * This only means that resources will not be reserved. If you end - * up using termios, it will fail. + * This macro determines if termios is disabled by this application. + * This only means that resources will not be reserved. If you end + * up using termios, it will fail. */ #ifdef CONFIGURE_TERMIOS_DISABLED #define CONFIGURE_TERMIOS_SEMAPHORES 0 #else /** - * This macro specifies the number of serial or PTY ports that will - * use termios. + * This macro specifies the number of serial or PTY ports that will + * use termios. */ #ifndef CONFIGURE_NUMBER_OF_TERMIOS_PORTS #define CONFIGURE_NUMBER_OF_TERMIOS_PORTS 1 #endif /** - * This macro reserves the number of semaphores required by termios - * based upon the number of communication ports that will use it. + * This macro reserves the number of semaphores required by termios + * based upon the number of communication ports that will use it. */ #define CONFIGURE_TERMIOS_SEMAPHORES \ ((CONFIGURE_NUMBER_OF_TERMIOS_PORTS * 4) + 1) #endif /** - * This macro specifies the number of PTYs that can be concurrently - * active. + * This macro specifies the number of PTYs that can be concurrently + * active. */ #ifndef CONFIGURE_MAXIMUM_PTYS #define CONFIGURE_MAXIMUM_PTYS 0 #endif /** - * This variable contains the maximum number of PTYs that can be - * concurrently active. + * This variable contains the maximum number of PTYs that can be + * concurrently active. */ #ifdef CONFIGURE_INIT int rtems_telnetd_maximum_ptys = CONFIGURE_MAXIMUM_PTYS; @@ -288,10 +288,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #include <rtems/imfs.h> /** - * This specifies the number of bytes per block for files within the IMFS. - * There are a maximum number of blocks per file so this dictates the maximum - * size of a file. This has to be balanced with the unused portion of each - * block that might be wasted. + * This specifies the number of bytes per block for files within the IMFS. + * There are a maximum number of blocks per file so this dictates the maximum + * size of a file. This has to be balanced with the unused portion of each + * block that might be wasted. */ #ifndef CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK #define CONFIGURE_IMFS_MEMFILE_BYTES_PER_BLOCK \ @@ -299,7 +299,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This defines the miniIMFS file system table entry. + * This defines the miniIMFS file system table entry. */ #if !defined(CONFIGURE_FILESYSTEM_ENTRY_miniIMFS) && \ defined(CONFIGURE_FILESYSTEM_MINIIMFS) @@ -309,7 +309,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * Internall it is called FIFOs not pipes + * Internall it is called FIFOs not pipes */ #if defined(CONFIGURE_PIPES_ENABLED) #define CONFIGURE_FIFOS_ENABLED @@ -317,7 +317,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifndef RTEMS_SCHEDSIM /** - * This defines the IMFS file system table entry. + * This defines the IMFS file system table entry. */ #if !defined(CONFIGURE_FILESYSTEM_ENTRY_IMFS) && \ defined(CONFIGURE_FILESYSTEM_IMFS) @@ -332,7 +332,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This sets up the resources for the PIPES/FIFOs + * This sets up the resources for the PIPES/FIFOs */ #if defined(CONFIGURE_FIFOS_ENABLED) #if !defined(CONFIGURE_MAXIMUM_FIFOS) && !defined(CONFIGURE_MAXIMUM_PIPES) @@ -418,13 +418,13 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_INIT /** - * DEVFS variables. + * DEVFS variables. * - * The number of individual devices that may be registered - * in the system or the CONFIGURE_MAXIMUM_DEVICES variable - * is defaulted to 4 when a filesystem is enabled, unless - * the bsp overwrides this. In which case the value is set - * to BSP_MAXIMUM_DEVICES. + * The number of individual devices that may be registered + * in the system or the CONFIGURE_MAXIMUM_DEVICES variable + * is defaulted to 4 when a filesystem is enabled, unless + * the bsp overwrides this. In which case the value is set + * to BSP_MAXIMUM_DEVICES. */ #ifdef CONFIGURE_FILESYSTEM_DEVFS #ifndef CONFIGURE_MAXIMUM_DEVICES @@ -532,7 +532,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This configures the stack checker user extension. + * This configures the stack checker user extension. */ #ifdef CONFIGURE_STACK_CHECKER_ENABLED #define CONFIGURE_STACK_CHECKER_EXTENSION 1 @@ -541,34 +541,34 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * @brief Maximum Priority configuration + * @brief Maximum priority configuration. * - * This configures the maximum priority value that - * a task may have. + * This configures the maximum priority value that + * a task may have. * - * The following applies to the data space requirements - * of the Priority Scheduler. + * The following applies to the data space requirements + * of the Priority Scheduler. * - * By reducing the number of priorities in a system, - * the amount of RAM required by RTEMS can be significantly - * reduced. RTEMS allocates a Chain_Control structure per - * priority and this structure contains 3 pointers. So - * the default is (256 * 12) = 3K on 32-bit architectures. + * By reducing the number of priorities in a system, + * the amount of RAM required by RTEMS can be significantly + * reduced. RTEMS allocates a Chain_Control structure per + * priority and this structure contains 3 pointers. So + * the default is (256 * 12) = 3K on 32-bit architectures. * - * This must be one less than a power of 2 between - * 4 and 256. Valid values along with the application - * priority levels and memory saved when pointers are - * 32-bits in size are: + * This must be one less than a power of 2 between + * 4 and 256. Valid values along with the application + * priority levels and memory saved when pointers are + * 32-bits in size are: * - * + 3, 2 application priorities, 3024 bytes saved - * + 7, 5 application priorities, 2976 bytes saved - * + 15, 13 application priorities, 2880 bytes saved - * + 31, 29 application priorities, 2688 bytes saved - * + 63, 61 application priorities, 2304 bytes saved - * + 127, 125 application priorities, 1536 bytes saved - * + 255, 253 application priorities, 0 bytes saved + * + 3, 2 application priorities, 3024 bytes saved + * + 7, 5 application priorities, 2976 bytes saved + * + 15, 13 application priorities, 2880 bytes saved + * + 31, 29 application priorities, 2688 bytes saved + * + 63, 61 application priorities, 2304 bytes saved + * + 127, 125 application priorities, 1536 bytes saved + * + 255, 253 application priorities, 0 bytes saved * - * It is specified in terms of Classic API priority values. + * It is specified in terms of Classic API priority values. */ #ifndef CONFIGURE_MAXIMUM_PRIORITY #define CONFIGURE_MAXIMUM_PRIORITY PRIORITY_DEFAULT_MAXIMUM @@ -729,12 +729,12 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * @brief Idle task body configuration + * @brief Idle task body configuration. * - * There is a default IDLE thread body provided by RTEMS which - * has the possibility of being CPU specific. There may be a - * BSP specific override of the RTEMS default body and in turn, - * the application may override and provide its own. + * There is a default IDLE thread body provided by RTEMS which + * has the possibility of being CPU specific. There may be a + * BSP specific override of the RTEMS default body and in turn, + * the application may override and provide its own. */ #ifndef CONFIGURE_IDLE_TASK_BODY #if defined(BSP_IDLE_TASK_BODY) @@ -755,7 +755,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * By default, use the minimum stack size requested by this port. + * By default, use the minimum stack size requested by this port. */ #ifndef CONFIGURE_MINIMUM_TASK_STACK_SIZE #define CONFIGURE_MINIMUM_TASK_STACK_SIZE CPU_STACK_MINIMUM_SIZE @@ -765,10 +765,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = (2 * CONFIGURE_MINIMUM_TASK_STACK_SIZE) /** - * @brief Idle task stack size configuration + * @brief Idle task stack size configuration. * - * By default, the IDLE task will have a stack of minimum size. - * The BSP or application may override this value. + * By default, the IDLE task will have a stack of minimum size. + * The BSP or application may override this value. */ #ifndef CONFIGURE_IDLE_TASK_STACK_SIZE #ifdef BSP_IDLE_TASK_STACK_SIZE @@ -782,10 +782,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * @brief Interrupt stack size configuration + * @brief Interrupt stack size configuration. * - * By default, the interrupt stack will be of minimum size. - * The BSP or application may override this value. + * By default, the interrupt stack will be of minimum size. + * The BSP or application may override this value. */ #ifndef CONFIGURE_INTERRUPT_STACK_SIZE #ifdef BSP_INTERRUPT_STACK_SIZE @@ -796,11 +796,11 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This reserves memory for the interrupt stack if it is to be allocated - * by RTEMS rather than the BSP. + * This reserves memory for the interrupt stack if it is to be allocated + * by RTEMS rather than the BSP. * - * @todo Try to get to the point where all BSPs support allocating the - * memory from the Workspace. + * @todo Try to get to the point where all BSPs support allocating the + * memory from the Workspace. */ #if (CPU_ALLOCATE_INTERRUPT_STACK == 0) #define CONFIGURE_INTERRUPT_STACK_MEMORY 0 @@ -810,7 +810,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * Configure the very much optional task stack allocator initialization + * Configure the very much optional task stack allocator initialization */ #ifndef CONFIGURE_TASK_STACK_ALLOCATOR_INIT #define CONFIGURE_TASK_STACK_ALLOCATOR_INIT NULL @@ -831,8 +831,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * Should the RTEMS Workspace and C Program Heap be cleared automatically - * at system start up? + * Should the RTEMS Workspace and C Program Heap be cleared automatically + * at system start up? */ #ifndef CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY #ifdef BSP_ZERO_WORKSPACE_AUTOMATICALLY @@ -851,10 +851,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_INIT /** - * By default, RTEMS uses separate heaps for the RTEMS Workspace and - * the C Program Heap. On many BSPs, these can be optionally - * combined provided one larger memory pool. This is particularly - * useful in combination with the unlimited objects configuration. + * By default, RTEMS uses separate heaps for the RTEMS Workspace and + * the C Program Heap. On many BSPs, these can be optionally + * combined provided one larger memory pool. This is particularly + * useful in combination with the unlimited objects configuration. */ #ifdef BSP_DEFAULT_UNIFIED_WORK_AREAS #ifndef CONFIGURE_UNIFIED_WORK_AREAS @@ -872,8 +872,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_INIT /** - * This configures the malloc family statistics to be available. - * By default only function call counts are kept. + * This configures the malloc family statistics to be available. + * By default only function call counts are kept. */ rtems_malloc_statistics_functions_t *rtems_malloc_statistics_helpers = #ifndef CONFIGURE_MALLOC_STATISTICS @@ -885,10 +885,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_INIT /** - * This configures the sbrk() support for the malloc family. - * By default it is assumed that the BSP provides all available - * RAM to the malloc family implementation so sbrk()'ing to get - * more memory would always fail anyway. + * This configures the sbrk() support for the malloc family. + * By default it is assumed that the BSP provides all available + * RAM to the malloc family implementation so sbrk()'ing to get + * more memory would always fail anyway. */ const rtems_heap_extend_handler rtems_malloc_extend_handler = #ifdef CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK @@ -900,9 +900,9 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_INIT /** - * This configures the malloc family plugin which dirties memory - * allocated. This is helpful for finding unitialized data structure - * problems. + * This configures the malloc family plugin which dirties memory + * allocated. This is helpful for finding unitialized data structure + * problems. */ rtems_malloc_dirtier_t rtems_malloc_dirty_helper = #if defined(CONFIGURE_MALLOC_DIRTY) @@ -913,18 +913,18 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This is a helper macro used in calculations in this file. It is used - * to noted when an element is allocated from the RTEMS Workspace and adds - * a factor to account for heap overhead plus an alignment factor that - * may be applied. + * This is a helper macro used in calculations in this file. It is used + * to noted when an element is allocated from the RTEMS Workspace and adds + * a factor to account for heap overhead plus an alignment factor that + * may be applied. */ #define _Configure_From_workspace(_size) \ (ssize_t)((_size) + HEAP_BLOCK_HEADER_SIZE + CPU_HEAP_ALIGNMENT - 1) /** - * This is a helper macro used in stack space calculations in this file. It - * may be provided by the application in case a special task stack allocator - * is used. The default is allocation from the RTEMS Workspace. + * This is a helper macro used in stack space calculations in this file. It + * may be provided by the application in case a special task stack allocator + * is used. The default is allocation from the RTEMS Workspace. */ #ifdef CONFIGURE_TASK_STACK_FROM_ALLOCATOR #define _Configure_From_stackspace(_stack_size) \ @@ -935,18 +935,18 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * Do not use the unlimited bit as part of the multiplication - * for memory usage. + * Do not use the unlimited bit as part of the multiplication + * for memory usage. */ #define _Configure_Max_Objects(_max) \ rtems_resource_maximum_per_allocation(_max) /** - * This macro accounts for how memory for a set of configured objects is - * allocated from the Executive Workspace. + * This macro accounts for how memory for a set of configured objects is + * allocated from the Executive Workspace. * - * NOTE: It does NOT attempt to address the more complex case of unlimited - * objects. + * NOTE: It does NOT attempt to address the more complex case of unlimited + * objects. */ #define _Configure_Object_RAM(_number, _size) \ ( _Configure_From_workspace(_Configure_Max_Objects(_number) * (_size)) + \ @@ -1156,9 +1156,9 @@ rtems_fs_init_functions_t rtems_fs_init_helper = RTEMS_ARRAY_SIZE(Device_drivers) /** - * This specifies the maximum number of device drivers that - * can be installed in the system at one time. It must account - * for both the statically and dynamically installed drivers. + * This specifies the maximum number of device drivers that + * can be installed in the system at one time. It must account + * for both the statically and dynamically installed drivers. */ #ifndef CONFIGURE_MAXIMUM_DRIVERS #define CONFIGURE_MAXIMUM_DRIVERS CONFIGURE_NUMBER_OF_DRIVERS @@ -1485,10 +1485,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This macro calculates the memory required for task variables. + * This macro calculates the memory required for task variables. * - * @note Each task variable is individually allocated from the Workspace. - * Hence, we do the multiplication on the configured size. + * NOTE: Each task variable is individually allocated from the Workspace. + * Hence, we do the multiplication on the configured size. */ #ifndef CONFIGURE_MAXIMUM_TASK_VARIABLES #define CONFIGURE_MAXIMUM_TASK_VARIABLES 0 @@ -1662,8 +1662,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #include <rtems/posix/timer.h> /** - * Account for the object control structures plus the name - * of the object to be duplicated. + * Account for the object control structures plus the name + * of the object to be duplicated. */ #define _Configure_POSIX_Named_Object_RAM(_number, _size) \ _Configure_Object_RAM( (_number), _size ) + \ @@ -1856,15 +1856,15 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_GNAT_RTEMS /** - * The GNAT run-time needs something less than (10) POSIX mutexes. - * We may be able to get by with less but why bother. + * The GNAT run-time needs something less than (10) POSIX mutexes. + * We may be able to get by with less but why bother. */ #define CONFIGURE_GNAT_MUTEXES 10 /** - * This is the maximum number of Ada tasks which can be concurrently - * in existence. Twenty (20) are required to run all tests in the - * ACATS (formerly ACVC). + * This is the maximum number of Ada tasks which can be concurrently + * in existence. Twenty (20) are required to run all tests in the + * ACATS (formerly ACVC). */ #ifndef CONFIGURE_MAXIMUM_ADA_TASKS #define CONFIGURE_MAXIMUM_ADA_TASKS 20 @@ -1919,8 +1919,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifndef RTEMS_SCHEDSIM /** - * This macro specifies the amount of memory to be reserved for the - * Newlib C Library reentrancy structure -- if we are using newlib. + * This macro specifies the amount of memory to be reserved for the + * Newlib C Library reentrancy structure -- if we are using newlib. */ #if (defined(RTEMS_NEWLIB) && !defined(CONFIGURE_DISABLE_NEWLIB_REENTRANCY)) @@ -1937,8 +1937,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This is so we can account for tasks with stacks greater than minimum - * size. This is in bytes. + * This is so we can account for tasks with stacks greater than minimum + * size. This is in bytes. */ #ifndef CONFIGURE_EXTRA_TASK_STACKS #define CONFIGURE_EXTRA_TASK_STACKS 0 @@ -1951,10 +1951,10 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifndef CONFIGURE_EXECUTIVE_RAM_SIZE /** - * Account for allocating the following per object - * + array of object control structures - * + local pointer table -- pointer per object plus a zero'th - * entry in the local pointer table. + * Account for allocating the following per object + * + array of object control structures + * + local pointer table -- pointer per object plus a zero'th + * entry in the local pointer table. */ #define CONFIGURE_MEMORY_FOR_TASKS(_tasks, _number_FP_tasks) \ @@ -1976,8 +1976,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = ) /** - * This defines the amount of memory configured for the multiprocessing - * support required by this application. + * This defines the amount of memory configured for the multiprocessing + * support required by this application. */ #ifdef CONFIGURE_MP_APPLICATION #define CONFIGURE_MEMORY_FOR_MP \ @@ -1991,44 +1991,44 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * The following macro is used to calculate the memory allocated by RTEMS - * for the message buffers associated with a particular message queue. - * There is a fixed amount of overhead per message. + * The following macro is used to calculate the memory allocated by RTEMS + * for the message buffers associated with a particular message queue. + * There is a fixed amount of overhead per message. */ #define CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(_messages, _size) \ _Configure_From_workspace( \ (_messages) * ((_size) + sizeof(CORE_message_queue_Buffer_control))) /** - * This macros is set to the amount of memory required for pending message - * buffers in bytes. It should be constructed by adding together a - * set of values determined by CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE. + * This macros is set to the amount of memory required for pending message + * buffers in bytes. It should be constructed by adding together a + * set of values determined by CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE. */ #ifndef CONFIGURE_MESSAGE_BUFFER_MEMORY #define CONFIGURE_MESSAGE_BUFFER_MEMORY 0 #endif /** - * This macro is available just in case the confdefs.h file underallocates - * memory for a particular application. This lets the user add some extra - * memory in case something broken and underestimates. + * This macro is available just in case the confdefs.h file underallocates + * memory for a particular application. This lets the user add some extra + * memory in case something broken and underestimates. * - * It is also possible for cases where confdefs.h overallocates memory, - * you could substract memory from the allocated. The estimate is just - * that, an estimate, and assumes worst case alignment and padding on - * each allocated element. So in some cases it could be too conservative. + * It is also possible for cases where confdefs.h overallocates memory, + * you could substract memory from the allocated. The estimate is just + * that, an estimate, and assumes worst case alignment and padding on + * each allocated element. So in some cases it could be too conservative. * - * @note Historically this was used for message buffers. + * NOTE: Historically this was used for message buffers. */ #ifndef CONFIGURE_MEMORY_OVERHEAD #define CONFIGURE_MEMORY_OVERHEAD 0 #endif /** - * On architectures that use Simple Vectored Interrupts, it is RTEMS - * responsibility to allocate the vector table. This avoids reserving - * the memory on architectures that use the Programmable Interrupt - * Controller Vectored Interrupts. + * On architectures that use Simple Vectored Interrupts, it is RTEMS + * responsibility to allocate the vector table. This avoids reserving + * the memory on architectures that use the Programmable Interrupt + * Controller Vectored Interrupts. */ #if (CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE) /* @@ -2050,15 +2050,15 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * RTEMS uses one instance of an internal mutex class. This accounts - * for that mutex + * RTEMS uses one instance of an internal mutex class. This accounts + * for that mutex */ #define CONFIGURE_API_MUTEX_MEMORY \ _Configure_Object_RAM(1, sizeof(API_Mutex_Control)) /** - * This calculates the amount of memory reserved for the IDLE tasks. - * In an SMP system, each CPU core has its own idle task. + * This calculates the amount of memory reserved for the IDLE tasks. + * In an SMP system, each CPU core has its own idle task. */ #if defined(RTEMS_SMP) #define CONFIGURE_IDLE_TASKS_COUNT CONFIGURE_SMP_MAXIMUM_PROCESSORS @@ -2067,14 +2067,14 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This defines the formula used to compute the amount of memory - * reserved for IDLE task control structures. + * This defines the formula used to compute the amount of memory + * reserved for IDLE task control structures. */ #define CONFIGURE_MEMORY_FOR_IDLE_TASK \ CONFIGURE_MEMORY_FOR_TASKS(CONFIGURE_IDLE_TASKS_COUNT, 0) /** - * This macro accounts for general RTEMS system overhead. + * This macro accounts for general RTEMS system overhead. */ #define CONFIGURE_MEMORY_FOR_SYSTEM_OVERHEAD \ ( CONFIGURE_MEMORY_FOR_IDLE_TASK + /* IDLE and stack */ \ @@ -2085,8 +2085,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = ) /** - * This macro provides a summation of the various task and thread - * requirements. + * This macro provides a summation of the various task and thread + * requirements. */ #define CONFIGURE_TOTAL_TASKS_AND_THREADS \ (CONFIGURE_TASKS + \ @@ -2094,8 +2094,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = CONFIGURE_MAXIMUM_GOROUTINES) /** - * This macro reserves the memory required by the statically configured - * user extensions. + * This macro reserves the memory required by the statically configured + * user extensions. */ #define CONFIGURE_MEMORY_FOR_STATIC_EXTENSIONS \ (CONFIGURE_NUMBER_OF_INITIAL_EXTENSIONS == 0 ? 0 : \ @@ -2105,8 +2105,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = )) /** - * This macro provides a summation of the memory required by the - * Classic API as configured. + * This macro provides a summation of the memory required by the + * Classic API as configured. */ #define CONFIGURE_MEMORY_FOR_CLASSIC \ (CONFIGURE_MEMORY_FOR_TASK_VARIABLES(CONFIGURE_MAXIMUM_TASK_VARIABLES + \ @@ -2133,7 +2133,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This calculates the memory required for the executive workspace. + * This calculates the memory required for the executive workspace. */ #define CONFIGURE_EXECUTIVE_RAM_SIZE \ (( \ @@ -2155,8 +2155,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = */ /** - * This accounts for any extra memory required by the Classic API - * Initialization Task. + * This accounts for any extra memory required by the Classic API + * Initialization Task. */ #if (CONFIGURE_INIT_TASK_STACK_SIZE > CONFIGURE_MINIMUM_TASK_STACK_SIZE) #define CONFIGURE_INITIALIZATION_THREADS_STACKS_CLASSIC_PART \ @@ -2166,8 +2166,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This accounts for any extra memory required by the POSIX API - * Initialization Thread. + * This accounts for any extra memory required by the POSIX API + * Initialization Thread. */ #if defined(RTEMS_POSIX_API) && \ (CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE > \ @@ -2180,8 +2180,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #endif /** - * This macro provides a summation of the various initialization task - * and thread stack requirements. + * This macro provides a summation of the various initialization task + * and thread stack requirements. */ #define CONFIGURE_INITIALIZATION_THREADS_EXTRA_STACKS \ (CONFIGURE_INITIALIZATION_THREADS_STACKS_CLASSIC_PART + \ @@ -2241,7 +2241,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef CONFIGURE_INIT /** - * This is the Classic API Configuration Table. + * This is the Classic API Configuration Table. */ rtems_api_configuration_table Configuration_RTEMS_API = { CONFIGURE_TASKS, @@ -2260,7 +2260,7 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #ifdef RTEMS_POSIX_API /** - * This is the POSIX API Configuration Table. + * This is the POSIX API Configuration Table. */ posix_api_configuration_table Configuration_POSIX_API = { CONFIGURE_MAXIMUM_POSIX_THREADS + CONFIGURE_MAXIMUM_ADA_TASKS + @@ -2285,29 +2285,31 @@ rtems_fs_init_functions_t rtems_fs_init_helper = }; #endif - /** This variable specifies the minimum stack size for tasks in an RTEMS - * application. + /** + * This variable specifies the minimum stack size for tasks in an RTEMS + * application. * - * @note This is left as a simple uint32_t so it can be externed as - * needed without requring being high enough logical to - * include the full configuration table. + * NOTE: This is left as a simple uint32_t so it can be externed as + * needed without requring being high enough logical to + * include the full configuration table. */ uint32_t rtems_minimum_stack_size = CONFIGURE_MINIMUM_TASK_STACK_SIZE; - /** This variable specifies the maximum priority value that - * a task may have. This must be a power of 2 between 4 - * and 256 and is specified in terms of Classic API - * priority values. + /** + * This variable specifies the maximum priority value that + * a task may have. This must be a power of 2 between 4 + * and 256 and is specified in terms of Classic API + * priority values. * - * @note This is left as a simple uint8_t so it can be externed as - * needed without requring being high enough logical to - * include the full configuration table. + * NOTE: This is left as a simple uint8_t so it can be externed as + * needed without requring being high enough logical to + * include the full configuration table. */ uint8_t rtems_maximum_priority = CONFIGURE_MAXIMUM_PRIORITY; /** - * This is the primary Configuration Table for this application. + * This is the primary Configuration Table for this application. */ const rtems_configuration_table Configuration = { CONFIGURE_EXECUTIVE_RAM_SIZE, /* required RTEMS workspace */ @@ -2350,8 +2352,8 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #if defined(RTEMS_SMP) /** - * Instantiate the variable which specifies the number of CPUs - * in an SMP configuration. + * Instantiate the variable which specifies the number of CPUs + * in an SMP configuration. */ #if defined(CONFIGURE_INIT) uint32_t rtems_configuration_smp_maximum_processors = \ @@ -2414,11 +2416,11 @@ rtems_fs_init_functions_t rtems_fs_init_helper = #if defined(CONFIGURE_CONFDEFS_DEBUG) && defined(CONFIGURE_INIT) /** - * This is a debug mechanism, so if you need to, the executable will - * have a structure with various partial values. Add to this as you - * need to. Viewing this structure in gdb combined with dumping - * the Configuration structures generated should help a lot in tracing - * down errors and analyzing where over and under allocations are. + * This is a debug mechanism, so if you need to, the executable will + * have a structure with various partial values. Add to this as you + * need to. Viewing this structure in gdb combined with dumping + * the Configuration structures generated should help a lot in tracing + * down errors and analyzing where over and under allocations are. */ typedef struct { uint32_t SYSTEM_OVERHEAD; diff --git a/cpukit/sapi/include/rtems/cbs.h b/cpukit/sapi/include/rtems/cbs.h index dda56e27b0..e0e619cdeb 100644 --- a/cpukit/sapi/include/rtems/cbs.h +++ b/cpukit/sapi/include/rtems/cbs.h @@ -1,5 +1,5 @@ /** - * @file rtems/cbs.h + * @file * * @brief Constants and Structures Associated * with the CBS library in RTEMS diff --git a/cpukit/sapi/include/rtems/chain.h b/cpukit/sapi/include/rtems/chain.h index 12d6e3b536..e1644acd14 100644 --- a/cpukit/sapi/include/rtems/chain.h +++ b/cpukit/sapi/include/rtems/chain.h @@ -1,9 +1,7 @@ /** * @file - * - * @ingroup ClassicChains - * - * @brief Chain API. + * + * @brief Chain API */ /* @@ -33,7 +31,7 @@ extern "C" { * * @ingroup ClassicRTEMS * - * @brief Chain API. + * @brief Chain API * * @{ */ diff --git a/cpukit/sapi/include/rtems/config.h b/cpukit/sapi/include/rtems/config.h index 9a35437b4f..58d2d92fb5 100644 --- a/cpukit/sapi/include/rtems/config.h +++ b/cpukit/sapi/include/rtems/config.h @@ -1,5 +1,5 @@ /** - * @file rtems/config.h + * @file * * @brief Table of User Defined Configuration Parameters * @@ -79,9 +79,10 @@ typedef struct { /** This is the maximum number of proxies. */ uint32_t maximum_proxies; - /** The MPCI Receive server is assumed to have a stack of at least - * minimum stack size. This field specifies the amount of extra - * stack this task will be given in bytes. + /** + * The MPCI Receive server is assumed to have a stack of at least + * minimum stack size. This field specifies the amount of extra + * stack this task will be given in bytes. */ uint32_t extra_mpci_receive_server_stack; @@ -93,14 +94,14 @@ typedef struct { /** * @brief Task stack allocator initialization hook. * - * @param[in] stack_space_size Size of the stack space in bytes. + * @param[in] stack_space_size is the size of the stack space in bytes. */ typedef void (*rtems_stack_allocate_init_hook)( size_t stack_space_size ); /** * @brief Task stack allocator hook. * - * @param[in] stack_size Size of the task stack in bytes. + * @param[in] stack_size is the Size of the task stack in bytes. * * @retval NULL Not enough memory. * @retval other Pointer to task stack. @@ -110,7 +111,7 @@ typedef void *(*rtems_stack_allocate_hook)( size_t stack_size ); /** * @brief Task stack deallocator hook. * - * @param[in] addr Pointer to previously allocated task stack. + * @param[in] addr is a pointer to previously allocated task stack. */ typedef void (*rtems_stack_free_hook)( void *addr ); @@ -126,49 +127,58 @@ typedef void (*rtems_stack_free_hook)( void *addr ); * + required number of each object type for each API configured */ typedef struct { - /** This field specifies the size in bytes of the RTEMS Workspace. + /** + * This field specifies the size in bytes of the RTEMS Workspace. */ uintptr_t work_space_size; - /** This field specifies the size in bytes of the RTEMS thread stack space. + /** + * This field specifies the size in bytes of the RTEMS thread stack space. */ uintptr_t stack_space_size; - /** This field specifies the maximum number of dynamically installed - * used extensions. + /** + * This field specifies the maximum number of dynamically installed + * used extensions. */ uint32_t maximum_extensions; - /** This field specifies the number of microseconds which elapse - * between clock ticks. This is the basis for RTEMS timing. + /** + * This field specifies the number of microseconds which elapse + * between clock ticks. This is the basis for RTEMS timing. */ uint32_t microseconds_per_tick; - /** This field specifies the number of nanoseconds which elapse - * between clock ticks. This value is derived from the - * microseconds_per_tick field and provided to avoid calculation at - * run-time. + /** + * This field specifies the number of nanoseconds which elapse + * between clock ticks. This value is derived from the + * microseconds_per_tick field and provided to avoid calculation at + * run-time. */ uint32_t nanoseconds_per_tick; - /** This field specifies the number of ticks in each task's timeslice. + /** + * This field specifies the number of ticks in each task's timeslice. */ uint32_t ticks_per_timeslice; - /** This element points to the BSP's optional idle task which may override - * the default one provided with RTEMS. + /** + * This element points to the BSP's optional idle task which may override + * the default one provided with RTEMS. */ Thread (*idle_task)( uintptr_t ); - /** This field specifies the size of the IDLE task's stack. If less than or - * equal to the minimum stack size, then the IDLE task will have the minimum - * stack size. + /** + * This field specifies the size of the IDLE task's stack. If less than or + * equal to the minimum stack size, then the IDLE task will have the minimum + * stack size. */ uint32_t idle_task_stack_size; - /** This field specifies the size of the interrupt stack. If less than or - * equal to the minimum stack size, then the interrupt stack will be of - * minimum stack size. + /** + * This field specifies the size of the interrupt stack. If less than or + * equal to the minimum stack size, then the interrupt stack will be of + * minimum stack size. */ uint32_t interrupt_stack_size; @@ -187,10 +197,11 @@ typedef struct { */ rtems_stack_free_hook stack_free_hook; - /** If this element is TRUE, then RTEMS will zero the Executive Workspace. - * When this element is FALSE, it is assumed that the BSP or invoking - * environment has ensured that memory was cleared before RTEMS was - * invoked. + /** + * If this element is TRUE, then RTEMS will zero the Executive Workspace. + * When this element is FALSE, it is assumed that the BSP or invoking + * environment has ensured that memory was cleared before RTEMS was + * invoked. */ bool do_zero_of_workspace; @@ -222,23 +233,23 @@ typedef struct { } rtems_configuration_table; /** - * This is the configuration table generated by confdefs.h. + * This is the configuration table generated by confdefs.h. */ extern const rtems_configuration_table Configuration; #if defined(RTEMS_MULTIPROCESSING) /** - * This points to the multiprocessing configuration table. + * This points to the multiprocessing configuration table. */ SAPI_EXTERN rtems_multiprocessing_table *_Configuration_MP_table; #endif #if defined(RTEMS_MULTIPROCESSING) /** - * @brief RTEMS Multiprocessing Configuration Table + * @brief RTEMS multiprocessing configuration table. * - * This is the RTEMS Multiprocessing Configuration Table expected to - * be generated by confdefs.h. + * This is the RTEMS Multiprocessing Configuration Table expected to + * be generated by confdefs.h. */ extern rtems_multiprocessing_table Multiprocessing_configuration; #endif @@ -294,7 +305,7 @@ extern const rtems_configuration_table Configuration; #define rtems_configuration_get_stack_free_hook() \ (Configuration.stack_free_hook) -/** + /** * This macro assists in accessing the field which indicates whether * RTEMS is responsible for zeroing the Executive Workspace. */ diff --git a/cpukit/sapi/include/rtems/extension.h b/cpukit/sapi/include/rtems/extension.h index 3d54092a8c..d57646ca9e 100644 --- a/cpukit/sapi/include/rtems/extension.h +++ b/cpukit/sapi/include/rtems/extension.h @@ -1,8 +1,6 @@ /** * @file - * - * @ingroup ClassicUserExtensions - * + * * @brief User Extensions API. */ @@ -39,7 +37,7 @@ typedef struct { } Extension_Control; /** - * @brief Initialize Extension Manager + * @brief Initialize extension manager. * * This routine initializes all extension manager related data structures. */ diff --git a/cpukit/sapi/include/rtems/fatal.h b/cpukit/sapi/include/rtems/fatal.h index 46a7ab9574..7ef9f71ba6 100644 --- a/cpukit/sapi/include/rtems/fatal.h +++ b/cpukit/sapi/include/rtems/fatal.h @@ -1,8 +1,6 @@ /** * @file * - * @ingroup ClassicFatal - * * @brief Fatal API. */ @@ -42,9 +40,9 @@ extern "C" { typedef CPU_Exception_frame rtems_exception_frame; /** - * @brief Prints the exception frame via printk(). + * @brief Prints the exception frame via printk(). * - * @see rtems_fatal() and RTEMS_FATAL_SOURCE_EXCEPTION. + * @see rtems_fatal() and RTEMS_FATAL_SOURCE_EXCEPTION. */ static inline void rtems_exception_frame_print( const rtems_exception_frame *frame @@ -57,9 +55,7 @@ static inline void rtems_exception_frame_print( * @brief Invokes the internal error handler with a source of * INTERNAL_ERROR_RTEMS_API and is internal set to false. * - * @param[in] the_error A 32-bit fatal error code. - * - * @return This function will not return. + * @param[in] the_error is a 32-bit fatal error code. * * @see _Internal_error_Occurred(). */ @@ -70,10 +66,8 @@ void rtems_fatal_error_occurred( /** * @brief Invokes the internal error handler with is internal set to false. * - * @param[in] source The fatal source. - * @param[in] error The fatal code. - * - * @return This function will not return. + * @param[in] source is the fatal source. + * @param[in] error is the fatal code. * * @see _Internal_error_Occurred(). */ @@ -85,20 +79,20 @@ void rtems_fatal( /** * @brief Returns a description for a fatal source. * - * @param[in] source The fatal source. + * @param[in] source is the fatal source. * - * @return The fatal source description or "?" in case the passed fatal source - * is invalid. + * @retval description The fatal source description. + * @retval ? The passed fatal source is invalid. */ const char *rtems_fatal_source_description( rtems_fatal_source source ); /** * @brief Returns a description for an internal error code. * - * @param[in] error The error code. + * @param[in] error is the error code. * - * @return The error code description or "?" in case the passed error code is - * invalid. + * @retval description The error code description. + * @retval ? The passed error code is invalid. */ const char *rtems_internal_error_description( rtems_fatal_code error ); diff --git a/cpukit/sapi/include/rtems/init.h b/cpukit/sapi/include/rtems/init.h index d357c113df..ad9a144910 100644 --- a/cpukit/sapi/include/rtems/init.h +++ b/cpukit/sapi/include/rtems/init.h @@ -1,19 +1,19 @@ /** - * @file rtems/init.h + * @file * * @brief Constants and Structures Associated * with the Initialization Manager * - * This include file contains all the constants and structures associated - * with the Initialization Manager. This manager is responsible for - * initializing RTEMS, creating and starting all configured initialization - * tasks, invoking the initialization routine for each user-supplied device - * driver, and initializing the optional multiprocessor layer. + * This include file contains all the constants and structures associated + * with the Initialization Manager. This manager is responsible for + * initializing RTEMS, creating and starting all configured initialization + * tasks, invoking the initialization routine for each user-supplied device + * driver, and initializing the optional multiprocessor layer. * - * This manager provides directives to: + * This manager provides directives to: * - * + initialize the RTEMS executive - * + shutdown the RTEMS executive + * + initialize the RTEMS executive + * + shutdown the RTEMS executive */ /* @@ -38,64 +38,64 @@ extern "C" { #if defined(RTEMS_MULTIPROCESSING) /** - * The following defines the default Multiprocessing Configuration - * Table. This table is used in a single processor system. + * The following defines the default Multiprocessing Configuration + * Table. This table is used in a single processor system. */ extern const rtems_multiprocessing_table _Initialization_Default_multiprocessing_table; #endif /** - * @brief rtems_initialize_data_structures + * @brief RTEMS data structures initialization. * - * This routine implements the portion of the RTEMS initializatin process - * that involves initializing data structures to a state that scheduling - * can occur in a consistent manner. + * This routine implements the portion of the RTEMS initializatin process + * that involves initializing data structures to a state that scheduling + * can occur in a consistent manner. */ void rtems_initialize_data_structures(void); /** - * @brief rtems_initialize_before_drivers + * @brief RTEMS initialization before the device drivers are initialized. * - * This routine implements the portion of RTEMS initialization that - * is done immediately before device drivers are initialized. + * This routine implements the portion of RTEMS initialization that + * is done immediately before device drivers are initialized. */ void rtems_initialize_before_drivers(void); /** - * @brief rtems_initialize_device_drivers + * @brief RTEMS initialization that initializes all device drivers. * - * This routine implements the portion of RTEMS initialization that - * initializes all device drivers. + * This routine implements the portion of RTEMS initialization that + * initializes all device drivers. */ void rtems_initialize_device_drivers(void); /** - * @brief Starts the multitasking. + * @brief Starts the multitasking. * - * This directive initiates multitasking and performs a context switch to the - * first user application task and may enable interrupts as a side-effect of - * that context switch. The context switch saves the executing context. The - * application runs now. The directive rtems_shutdown_executive() will return - * to the saved context. The exit() function will use this directive. + * This directive initiates multitasking and performs a context switch to the + * first user application task and may enable interrupts as a side-effect of + * that context switch. The context switch saves the executing context. The + * application runs now. The directive rtems_shutdown_executive() will return + * to the saved context. The exit() function will use this directive. * - * After a return to the saved context a fatal system state is reached. The - * fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value - * passed to rtems_shutdown_executive(). + * After a return to the saved context a fatal system state is reached. The + * fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value + * passed to rtems_shutdown_executive(). * - * This directive does not return. + * This directive does not return. */ void rtems_initialize_start_multitasking(void) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE; /** - * @brief Shutdown the RTEMS environment + * @brief Shutdown the RTEMS environment. * - * This routine implements the rtems_shutdown_executive directive. The - * invocation of this directive results in the RTEMS environment being - * shutdown and multitasking halted. From the application's perspective, - * invocation of this directive results in the rtems_initialize_executive - * directive exitting to the startup code which invoked it. + * This routine implements the rtems_shutdown_executive directive. The + * invocation of this directive results in the RTEMS environment being + * shutdown and multitasking halted. From the application's perspective, + * invocation of this directive results in the rtems_initialize_executive + * directive exitting to the startup code which invoked it. */ void rtems_shutdown_executive( uint32_t result diff --git a/cpukit/sapi/include/rtems/io.h b/cpukit/sapi/include/rtems/io.h index 8f02a34e2c..6901d84039 100644 --- a/cpukit/sapi/include/rtems/io.h +++ b/cpukit/sapi/include/rtems/io.h @@ -101,13 +101,13 @@ rtems_status_code rtems_io_register_driver( ); /** - * @brief Unregister a Driver from the Device Driver Table. + * @brief Unregister a driver from the device driver table. * - * @param[in] major is the device major number. + * @param[in] major is the device major number. * - * @retval RTEMS_SUCCESSFUL Device driver successfully unregistered. - * @retval RTEMS_UNSATISFIED Invalid major number. - * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context. + * @retval RTEMS_SUCCESSFUL Device driver successfully unregistered. + * @retval RTEMS_UNSATISFIED Invalid major number. + * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context. */ rtems_status_code rtems_io_unregister_driver( rtems_device_major_number major @@ -131,15 +131,15 @@ rtems_status_code rtems_io_register_name( /** @} */ /** - * @brief IO Driver Initialization + * @brief IO driver initialization. * - * This routine is the initialization directive of the IO manager. + * This routine is the initialization directive of the IO manager. * - * @param[in] major is the device drive number - * @param[in] minor is the device number - * @param[in] argument is the pointer to the argument(s) + * @param[in] major is the device drive number + * @param[in] minor is the device number + * @param[in] argument is the pointer to the argument(s) * - * @return status code + * @return status code */ rtems_status_code rtems_io_initialize( rtems_device_major_number major, @@ -148,15 +148,15 @@ rtems_status_code rtems_io_initialize( ); /** - * @brief Opening for The IO Manager + * @brief Opening for the IO manager. * - * Opens a device driver with the number @a major. + * Opens a device driver with the number @a major. * - * @param[in] major is the device driver number. - * @param[in] minor is the device number. - * @param[in] argument is the pointer to the argument(s). + * @param[in] major is the device driver number. + * @param[in] minor is the device number. + * @param[in] argument is the pointer to the argument(s). * - * @return Status code. + * @return Status code. */ rtems_status_code rtems_io_open( rtems_device_major_number major, @@ -165,15 +165,15 @@ rtems_status_code rtems_io_open( ); /** - * @brief Closing for The IO Manager + * @brief Closing for the IO manager. * - * This routine is the close directive of the IO manager. + * This routine is the close directive of the IO manager. * - * @param[in] major is the device driver number. - * @param[in] minor is the device number. - * @param[in] argument is the pointer to the argument(s). + * @param[in] major is the device driver number. + * @param[in] minor is the device number. + * @param[in] argument is the pointer to the argument(s). * - * @return Status code. + * @return Status code. */ rtems_status_code rtems_io_close( rtems_device_major_number major, @@ -182,15 +182,15 @@ rtems_status_code rtems_io_close( ); /** - * @brief Reading for The IO Manager + * @brief Reading for the IO manager. * - * This routine is the read directive of the IO manager. + * This routine is the read directive of the IO manager. * - * @param[in] major is the device driver number. - * @param[in] minor is the device number. - * @param[in] argument is the pointer to the argument(s). + * @param[in] major is the device driver number. + * @param[in] minor is the device number. + * @param[in] argument is the pointer to the argument(s). * - * @return Status code. + * @return Status code. */ rtems_status_code rtems_io_read( rtems_device_major_number major, @@ -199,15 +199,15 @@ rtems_status_code rtems_io_read( ); /** - * @brief Writing for The IO Manager + * @brief Writing for the IO manager. * - * This routine is the write directive of the IO manager. + * This routine is the write directive of the IO manager. * - * @param[in] major is the device driver number. - * @param[in] minor is the device number. - * @param[in] argument is the pointer to the argument(s). + * @param[in] major is the device driver number. + * @param[in] minor is the device number. + * @param[in] argument is the pointer to the argument(s). * - * @return Status code. + * @return Status code. */ rtems_status_code rtems_io_write( rtems_device_major_number major, @@ -216,15 +216,15 @@ rtems_status_code rtems_io_write( ); /** - * @brief Control for The IO Manager + * @brief Control for the IO manager. * - * This routine is the control directive of the IO manager. + * This routine is the control directive of the IO manager. * - * @param[in] major is the device driver number. - * @param[in] minor is the device number. - * @param[in] argument is the pointer to the argument(s). + * @param[in] major is the device driver number. + * @param[in] minor is the device number. + * @param[in] argument is the pointer to the argument(s). * - * @return Status code. + * @return Status code. */ rtems_status_code rtems_io_control( rtems_device_major_number major, @@ -256,18 +256,18 @@ SAPI_IO_EXTERN uint32_t _IO_Number_of_drivers; SAPI_IO_EXTERN rtems_driver_address_table *_IO_Driver_address_table; /** - * @brief Initialization of Device Drivers + * @brief Initialization of device drivers. * - * @note The IO manager has been extended to support runtime driver - * registration. The driver table is now allocated in the - * workspace. + * NOTE: The IO manager has been extended to support runtime driver + * registration. The driver table is now allocated in the + * workspace. */ void _IO_Manager_initialization( void ); /** - * @brief Initialization of All Device Drivers + * @brief Initialization of all device drivers. * - * Initializes all device drivers. + * Initializes all device drivers. */ void _IO_Initialize_all_drivers( void ); diff --git a/cpukit/sapi/include/rtems/mptables.h b/cpukit/sapi/include/rtems/mptables.h index 52db445833..fcef585461 100644 --- a/cpukit/sapi/include/rtems/mptables.h +++ b/cpukit/sapi/include/rtems/mptables.h @@ -1,5 +1,5 @@ /** - * @file rtems/mptables.h + * @file * * @brief Executive's Pre-Initialized Tables used in a * Multiprocessor Configuration diff --git a/cpukit/sapi/include/rtems/rbheap.h b/cpukit/sapi/include/rtems/rbheap.h index 39bbc69a3f..fb830be2d7 100644 --- a/cpukit/sapi/include/rtems/rbheap.h +++ b/cpukit/sapi/include/rtems/rbheap.h @@ -2,8 +2,6 @@ * @file * * @brief Red-Black Tree Heap API - * - * @ingroup RBHeap */ /* @@ -34,7 +32,7 @@ extern "C" { /** * @defgroup RBHeap Red-Black Tree Heap * - * @brief Red-Black Tree Heap API. + * @brief Red-Black Tree Heap API * * The red-black tree heap provides a memory allocator suitable to implement * the malloc() and free() interface. It uses a first-fit allocation strategy. @@ -146,13 +144,13 @@ struct rtems_rbheap_control { /** * @brief Initializes the red-black tree heap @a control. * - * @param[in, out] control The red-black tree heap. - * @param[in] area_begin The managed memory area begin. - * @param[in] area_size The managed memory area size. - * @param[in] alignment The minimum chunk alignment. - * @param[in] extend_descriptors The handler to extend the available chunk + * @param[in, out] control is the red-black tree heap. + * @param[in] area_begin is the managed memory area begin. + * @param[in] area_size is the managed memory area size. + * @param[in] alignment is the minimum chunk alignment. + * @param[in] extend_descriptors is the handler to extend the available chunk * descriptors. - * @param[in] handler_arg The handler argument. + * @param[in] handler_arg is the handler argument. * * @retval RTEMS_SUCCESSFUL Successful operation. * @retval RTEMS_INVALID_NUMBER The alignment is not positive. @@ -175,8 +173,8 @@ rtems_status_code rtems_rbheap_initialize( * The chunk begin is aligned by the value specified in * rtems_rbheap_initialize(). * - * @param[in, out] control The red-black tree heap. - * @param[in] size The requested chunk size in bytes. + * @param[in, out] control is the red-black tree heap. + * @param[in] size is the requested chunk size in bytes. * * @retval NULL Not enough free space in the heap. * @retval otherwise Pointer to allocated chunk of memory. @@ -184,16 +182,17 @@ rtems_status_code rtems_rbheap_initialize( void *rtems_rbheap_allocate(rtems_rbheap_control *control, size_t size); /** - * @brief Frees a chunk of memory @a ptr allocated from the red-black tree heap - * @a control. + * @brief Frees a chunk of memory @a ptr allocated from the red-black + * tree heap @a control. * - * @param[in, out] control The red-black tree heap. - * @param[in] ptr The pointer to the chunk of memory. + * @param[in, out] control is the red-black tree heap. + * @param[in] ptr is a pointer to the chunk of memory. * * @retval RTEMS_SUCCESSFUL Successful operation. * @retval RTEMS_INVALID_ID The chunk of memory is not a valid chunk in the * red-black tree heap. - * @retval RTEMS_INCORRECT_STATE The chunk of memory is not in the right state. + * @retval RTEMS_INCORRECT_STATE The chunk of memory is not in the + * right state. */ rtems_status_code rtems_rbheap_free(rtems_rbheap_control *control, void *ptr); diff --git a/cpukit/sapi/include/rtems/rbtree.h b/cpukit/sapi/include/rtems/rbtree.h index 4d150deee7..03a55eb992 100644 --- a/cpukit/sapi/include/rtems/rbtree.h +++ b/cpukit/sapi/include/rtems/rbtree.h @@ -1,11 +1,12 @@ /** - * @file rtems/rbtree.h - * - * This include file contains all the constants and structures associated - * with the RBTree API in RTEMS. The rbtree is a Red Black Tree that - * is part of the Super Core. This is the published interface to that - * code. - * + * @file + * + * @brief Constants and Structures Associated with the RBTree API in RTEMS + * + * This include file contains all the constants and structures associated + * with the RBTree API in RTEMS. The rbtree is a Red Black Tree that + * is part of the Super Core. This is the published interface to that + * code. */ /* @@ -50,13 +51,13 @@ typedef RBTree_Control rtems_rbtree_control; typedef RBTree_Compare_function rtems_rbtree_compare_function; /** - * @brief RBTree initializer for an empty rbtree with designator @a name. + * @brief RBTree initializer for an empty rbtree with designator @a name. */ #define RTEMS_RBTREE_INITIALIZER_EMPTY(name) \ RBTREE_INITIALIZER_EMPTY(name) /** - * @brief RBTree definition for an empty rbtree with designator @a name. + * @brief RBTree definition for an empty rbtree with designator @a name. */ #define RTEMS_RBTREE_DEFINE_EMPTY(name) \ RBTREE_DEFINE_EMPTY(name) diff --git a/cpukit/sapi/include/rtems/sptables.h b/cpukit/sapi/include/rtems/sptables.h index d6480acdfe..f32729c7eb 100644 --- a/cpukit/sapi/include/rtems/sptables.h +++ b/cpukit/sapi/include/rtems/sptables.h @@ -1,8 +1,10 @@ /** - * @file rtems/sptables.h + * @file + * + * @brief Pre-Initialized Tables Used when in a Single Processor Configuration * - * This include file contains the executive's pre-initialized tables - * used when in a single processor configuration. + * This include file contains the executive's pre-initialized tables + * used when in a single processor configuration. */ /* diff --git a/cpukit/sapi/include/rtems/timespec.h b/cpukit/sapi/include/rtems/timespec.h index fcea746445..b67e95c2d3 100644 --- a/cpukit/sapi/include/rtems/timespec.h +++ b/cpukit/sapi/include/rtems/timespec.h @@ -26,9 +26,10 @@ * @ingroup ClassicRTEMS * * @brief Timespec API + * + * @{ * */ -/**@{*/ #include <stdbool.h> /* bool */ #include <stdint.h> /* uint32_t */ @@ -40,11 +41,11 @@ extern "C" { #include <rtems/timespec.inl> +/** @} */ + #ifdef __cplusplus } #endif -/**@}*/ - #endif /* end of include file */ diff --git a/cpukit/sapi/inline/rtems/cbs.inl b/cpukit/sapi/inline/rtems/cbs.inl index d4fb6a8d9d..01d7779318 100644 --- a/cpukit/sapi/inline/rtems/cbs.inl +++ b/cpukit/sapi/inline/rtems/cbs.inl @@ -1,8 +1,10 @@ /** - * @file cbs.inl - * - * This include file contains all the constants and structures associated - * with the CBS library. + * @file + * + * @brief Constants and Structures Associated with the CBS Library + * + * This include file contains all the constants and structures associated + * with the CBS library. * */ @@ -22,11 +24,11 @@ #include <rtems/score/schedulercbs.h> /** - * @brief rtems cbs init + * @brief Initialize the CBS library. * - * Initializes the CBS library. + * Initializes the CBS library. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_initialize ( void ) { @@ -34,11 +36,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_initialize ( void ) } /** - * @brief rtems cbs cleanup + * @brief Cleanup resources associated to the CBS Library * - * Cleanup resources associated to the CBS Library. + * Cleanup resources associated to the CBS Library. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_cleanup ( void ) { @@ -46,11 +48,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_cleanup ( void ) } /** - * @brief rtems cbs create server + * @brief Create a new server with specified parameters. * - * Create a new server with specified parameters. + * Create a new server with specified parameters. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_create_server ( rtems_cbs_parameters *params, @@ -66,11 +68,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_create_server ( } /** - * @brief rtems cbs attach thread + * @brief Attach a task to an already existing server. * - * Attach a task to an already existing server. + * Attach a task to an already existing server. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_attach_thread ( rtems_cbs_server_id server_id, @@ -81,11 +83,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_attach_thread ( } /** - * @brief rtems cbs detach thread + * @brief Detach from the CBS server. * - * Detach from the CBS Server. + * Detach from the CBS Server. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_detach_thread ( rtems_cbs_server_id server_id, @@ -96,11 +98,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_detach_thread ( } /** - * @brief rtems cbs destroy server + * @brief Detach all tasks from a server and destroy it. * - * Detach all tasks from a server and destroy it. + * Detach all tasks from a server and destroy it. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_destroy_server ( rtems_cbs_server_id server_id @@ -110,12 +112,12 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_destroy_server ( } /** - * @brief rtems cbs get server id + * @brief Get CBS server id. * - * Get a thread server id, or RTEMS_CBS_E_NOT_FOUND if it is not - * attached to any server. + * Get a thread server id, or RTEMS_CBS_E_NOT_FOUND if it is not + * attached to any server. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_get_server_id ( rtems_id task_id, @@ -126,11 +128,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_get_server_id ( } /** - * @brief rtems cbs get parameters + * @brief Get CBS parameters. * - * Retrieve CBS scheduling parameters. + * Retrieve CBS scheduling parameters. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_get_parameters ( rtems_cbs_server_id server_id, @@ -141,11 +143,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_get_parameters ( } /** - * @brief rtems cbs set parameters + * @brief Set CBS parameters. * - * Change CBS scheduling parameters. + * Change CBS scheduling parameters. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_set_parameters ( rtems_cbs_server_id server_id, @@ -156,11 +158,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_set_parameters ( } /** - * @brief rtems cbs get execution time + * @brief Get the CBS get execution time. * - * Retrieve time info relative to the current server. + * Retrieve time info relative to the current server. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_get_execution_time ( rtems_cbs_server_id server_id, @@ -172,11 +174,11 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_get_execution_time ( } /** - * @brief rtems cbs get remaining budget + * @brief Get the remaining CBS budget. * - * Retrieve remaining budget for the current server instance. + * Retrieve remaining budget for the current server instance. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_get_remaining_budget ( rtems_cbs_server_id server_id, @@ -187,12 +189,12 @@ RTEMS_INLINE_ROUTINE int rtems_cbs_get_remaining_budget ( } /** - * @brief rtems cbs get approved budget + * @brief Get the approved CBS budget. * - * Retrieve the budget that has been approved for the subsequent - * server instances. + * Retrieve the budget that has been approved for the subsequent + * server instances. * - * @return status code. + * @return status code. */ RTEMS_INLINE_ROUTINE int rtems_cbs_get_approved_budget ( rtems_cbs_server_id server_id, diff --git a/cpukit/sapi/inline/rtems/chain.inl b/cpukit/sapi/inline/rtems/chain.inl index a1bfc2f32e..bf98f98777 100644 --- a/cpukit/sapi/inline/rtems/chain.inl +++ b/cpukit/sapi/inline/rtems/chain.inl @@ -1,9 +1,7 @@ /** * @file * - * @ingroup ClassicChains - * - * @brief Chain API. + * @brief Chain API */ /* @@ -33,17 +31,17 @@ */ /** - * @brief Initialize a Chain Header + * @brief Initialize a chain Header. * - * This routine initializes @a the_chain structure to manage the - * contiguous array of @a number_nodes nodes which starts at - * @a starting_address. Each node is of @a node_size bytes. + * This routine initializes @a the_chain structure to manage the + * contiguous array of @a number_nodes nodes which starts at + * @a starting_address. Each node is of @a node_size bytes. * - * @param[in] the_chain specifies the chain to initialize - * @param[in] starting_address is the starting address of the array - * of elements - * @param[in] number_nodes is the number of nodes that will be in the chain - * @param[in] node_size is the size of each node + * @param[in] the_chain specifies the chain to initialize + * @param[in] starting_address is the starting address of the array + * of elements + * @param[in] number_nodes is the number of nodes that will be in the chain + * @param[in] node_size is the size of each node */ RTEMS_INLINE_ROUTINE void rtems_chain_initialize( rtems_chain_control *the_chain, @@ -56,11 +54,11 @@ RTEMS_INLINE_ROUTINE void rtems_chain_initialize( } /** - * @brief Initialize this Chain as Empty + * @brief Initialize this chain as empty. * - * This routine initializes the specified chain to contain zero nodes. + * This routine initializes the specified chain to contain zero nodes. * - * @param[in] the_chain is the chain to be initialized. + * @param[in] the_chain is the chain to be initialized. */ RTEMS_INLINE_ROUTINE void rtems_chain_initialize_empty( rtems_chain_control *the_chain @@ -70,12 +68,12 @@ RTEMS_INLINE_ROUTINE void rtems_chain_initialize_empty( } /** - * @brief Set off chain + * @brief Set off chain. * - * This function sets the next and previous fields of the @a node to NULL - * indicating the @a node is not part of a chain. + * This function sets the next and previous fields of the @a node to NULL + * indicating the @a node is not part of a chain. * - * @param[in] node the node set to off chain. + * @param[in] node the node set to off chain. */ RTEMS_INLINE_ROUTINE void rtems_chain_set_off_chain( rtems_chain_node *node @@ -85,14 +83,15 @@ RTEMS_INLINE_ROUTINE void rtems_chain_set_off_chain( } /** - * @brief Is the Node off Chain + * @brief Is the node off chain. * - * This function returns true if the @a node is not on a chain. A @a node is - * off chain if the next and previous fields are set to NULL. + * This function returns true if the @a node is not on a chain. A @a node is + * off chain if the next and previous fields are set to NULL. * - * @param[in] node is the node off chain. + * @param[in] node is the node off chain. * - * @return This function returns true if the @a node is off chain. + * @retval true The node is off chain. + * @retval false The node is not off chain. */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_node_off_chain( const rtems_chain_node *node @@ -102,13 +101,14 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_node_off_chain( } /** - * @brief Is the Chain Node Pointer NULL - * - * This function returns true if the_node is NULL and false otherwise. + * @brief Is the chain node pointer NULL. * - * @param[in] the_node is the node pointer to check. + * This function returns true if the_node is NULL and false otherwise. * - * @return This method returns true if the_node is NULL and false otherwise. + * @param[in] the_node is the node pointer to check. + * + * @retval true The chain node pointer is NULL. + * @retval false The chain node pointer is not NULL. */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_null_node( const rtems_chain_node *the_node @@ -118,13 +118,13 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_null_node( } /** - * @brief Return pointer to Chain Head + * @brief Return pointer to Chain Head * - * This function returns a pointer to the first node on the chain. + * This function returns a pointer to the first node on the chain. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the permanent node of the chain. + * @return This method returns the permanent node of the chain. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_head( rtems_chain_control *the_chain @@ -133,13 +133,14 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_head( return _Chain_Head( the_chain ); } -/** @brief Return pointer to immutable Chain Head +/** + * @brief Return pointer to immutable Chain Head * - * This function returns a pointer to the head node on the chain. + * This function returns a pointer to the head node on the chain. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the permanent head node of the chain. + * @return This method returns the permanent head node of the chain. */ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_head( const rtems_chain_control *the_chain @@ -149,13 +150,13 @@ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_head( } /** - * @brief Return pointer to Chain Tail + * @brief Return pointer to Chain Tail * - * This function returns a pointer to the tail node on the chain. + * This function returns a pointer to the tail node on the chain. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the permanent tail node of the chain. + * @return This method returns the permanent tail node of the chain. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_tail( rtems_chain_control *the_chain @@ -164,13 +165,14 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_tail( return _Chain_Tail( the_chain ); } -/** @brief Return pointer to immutable Chain Tail +/** + * @brief Return pointer to immutable Chain Tail * - * This function returns a pointer to the tail node on the chain. + * This function returns a pointer to the tail node on the chain. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the permanent tail node of the chain. + * @return This method returns the permanent tail node of the chain. */ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_tail( const rtems_chain_control *the_chain @@ -180,14 +182,14 @@ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_tail( } /** - * @brief Return pointer to Chain's First node after the permanent head. + * @brief Return pointer to Chain's First node after the permanent head. * - * This function returns a pointer to the first node on the chain after the - * head. + * This function returns a pointer to the first node on the chain after the + * head. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the first node of the chain. + * @return This method returns the first node of the chain. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_first( rtems_chain_control *the_chain @@ -196,14 +198,15 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_first( return _Chain_First( the_chain ); } -/** @brief Return pointer to immutable Chain's First node +/** + * @brief Return pointer to immutable Chain's First node * - * This function returns a pointer to the first node on the chain after the - * head. + * This function returns a pointer to the first node on the chain after the + * head. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the first node of the chain. + * @return This method returns the first node of the chain. */ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_first( const rtems_chain_control *the_chain @@ -213,14 +216,14 @@ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_first( } /** - * @brief Return pointer to Chain's Last node before the permanent tail. + * @brief Return pointer to Chain's Last node before the permanent tail. * - * This function returns a pointer to the last node on the chain just before - * the tail. + * This function returns a pointer to the last node on the chain just before + * the tail. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the last node of the chain. + * @return This method returns the last node of the chain. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_last( rtems_chain_control *the_chain @@ -229,14 +232,15 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_last( return _Chain_Last( the_chain ); } -/** @brief Return pointer to immutable Chain's Last node +/** + * @brief Return pointer to immutable Chain's Last node * - * This function returns a pointer to the last node on the chain just before - * the tail. + * This function returns a pointer to the last node on the chain just before + * the tail. * - * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_chain is the chain to be operated upon. * - * @return This method returns the last node of the chain. + * @return This method returns the last node of the chain. */ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_last( const rtems_chain_control *the_chain @@ -246,13 +250,13 @@ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_last( } /** - * @brief Return pointer the next node from this node + * @brief Return pointer the next node from this node * - * This function returns a pointer to the next node after this node. + * This function returns a pointer to the next node after this node. * - * @param[in] the_node is the node to be operated upon. + * @param[in] the_node is the node to be operated upon. * - * @return This method returns the next node on the chain. + * @return This method returns the next node on the chain. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_next( rtems_chain_node *the_node @@ -261,13 +265,14 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_next( return _Chain_Next( the_node ); } -/** @brief Return pointer the immutable next node from this node +/** + * @brief Return pointer the immutable next node from this node * - * This function returns a pointer to the next node after this node. + * This function returns a pointer to the next node after this node. * - * @param[in] the_node is the node to be operated upon. + * @param[in] the_node is the node to be operated upon. * - * @return This method returns the next node on the chain. + * @return This method returns the next node on the chain. */ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_next( const rtems_chain_node *the_node @@ -277,13 +282,13 @@ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_next( } /** - * @brief Return pointer the previous node from this node + * @brief Return pointer the previous node from this node * - * This function returns a pointer to the previous node on this chain. + * This function returns a pointer to the previous node on this chain. * - * @param[in] the_node is the node to be operated upon. + * @param[in] the_node is the node to be operated upon. * - * @return This method returns the previous node on the chain. + * @return This method returns the previous node on the chain. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_previous( rtems_chain_node *the_node @@ -292,13 +297,14 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_previous( return _Chain_Previous( the_node ); } -/** @brief Return pointer the immutable previous node from this node +/** + * @brief Return pointer the immutable previous node from this node. * - * This function returns a pointer to the previous node on this chain. + * This function returns a pointer to the previous node on this chain. * - * @param[in] the_node is the node to be operated upon. + * @param[in] the_node is the node to be operated upon. * - * @return This method returns the previous node on the chain. + * @return This method returns the previous node on the chain. */ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_previous( const rtems_chain_node *the_node @@ -308,16 +314,16 @@ RTEMS_INLINE_ROUTINE const rtems_chain_node *rtems_chain_immutable_previous( } /** - * @brief Are Two Nodes Equal + * @brief Are Two nodes equal. * - * This function returns true if @a left and @a right are equal, - * and false otherwise. + * 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. + * @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. + * @retval true @a left is equal to @a right. + * @retval false @a left is not equal to @a right */ RTEMS_INLINE_ROUTINE bool rtems_chain_are_nodes_equal( const rtems_chain_node *left, @@ -328,15 +334,15 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_are_nodes_equal( } /** - * @brief Is the Chain Empty + * @brief Is the chain empty * - * This function returns true if there a no nodes on @a the_chain and - * false otherwise. + * 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. + * @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. + * @retval true The chain is empty. + * @retval false The chain is not empty. */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_empty( const rtems_chain_control *the_chain @@ -346,16 +352,16 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_empty( } /** - * @brief Is this the First Node on 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. + * 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. + * @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. + * @retval true @a the_node is the first node on a chain. + * @retval false @a the_node is not the first node on a chain. */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_first( const rtems_chain_node *the_node @@ -365,15 +371,15 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_first( } /** - * @brief Is this the Last Node on the Chain + * @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. + * 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. + * @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. + * @retval true @a the_node is the last node on a chain. + * @retval false @a the_node is not the last node on a chain */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_last( const rtems_chain_node *the_node @@ -383,15 +389,15 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_last( } /** - * @brief Does this Chain have only One Node + * @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. + * 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. + * @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. + * @retval true The chain has only one node. + * @retval false The chain has more than one nodes. */ RTEMS_INLINE_ROUTINE bool rtems_chain_has_only_one_node( const rtems_chain_control *the_chain @@ -401,16 +407,16 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_has_only_one_node( } /** - * @brief Is this Node the Chain Head + * @brief Is this node the chain head. * - * This function returns true if @a the_node is the head of the_chain and - * false otherwise. + * 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. + * @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. + * @retval true @a the_node is the head of @a the_chain. + * @retval false @a the_node is not the head of @a the_chain. */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_head( const rtems_chain_control *the_chain, @@ -421,13 +427,16 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_head( } /** - * @brief Is this Node the Chail Tail + * @brief Is this node the chain tail. * - * This function returns true if the_node is the tail of the_chain and - * false otherwise. + * 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. + * @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. + * + * @retval true @a the_node is the tail of @a the_chain. + * @retval false @a the_node is not the tail of @a the_chain. */ RTEMS_INLINE_ROUTINE bool rtems_chain_is_tail( const rtems_chain_control *the_chain, @@ -438,13 +447,13 @@ RTEMS_INLINE_ROUTINE bool rtems_chain_is_tail( } /** - * @brief Extract the specified node from a chain + * @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 ensure the atomicity of the - * extract operation. + * 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 + * @arg the_node specifies the node to extract */ RTEMS_INLINE_ROUTINE void rtems_chain_extract( rtems_chain_node *the_node @@ -454,12 +463,12 @@ RTEMS_INLINE_ROUTINE void rtems_chain_extract( } /** - * @brief Extract the specified node from a chain (unprotected). + * @brief Extract the specified node from a chain (unprotected). * - * This routine extracts @a the_node from the chain on which it resides. + * This routine extracts @a the_node from the chain on which it resides. * - * @note It does NOT disable interrupts to ensure the atomicity of the - * append operation. + * NOTE: It does NOT disable interrupts to ensure the atomicity of the + * append operation. */ RTEMS_INLINE_ROUTINE void rtems_chain_extract_unprotected( rtems_chain_node *the_node @@ -469,16 +478,16 @@ RTEMS_INLINE_ROUTINE void rtems_chain_extract_unprotected( } /** - * @brief Obtain the first node on a chain + * @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. * - * @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. + * @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. + * NOTE: It disables interrupts to ensure the atomicity of the get operation. */ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get( rtems_chain_control *the_chain @@ -498,13 +507,13 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get_unprotected( } /** - * @brief Insert a node on a chain + * @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 ensure the atomicity - * of the extract operation. + * NOTE: It disables interrupts to ensure the atomicity + * of the extract operation. */ RTEMS_INLINE_ROUTINE void rtems_chain_insert( rtems_chain_node *after_node, @@ -526,12 +535,12 @@ RTEMS_INLINE_ROUTINE void rtems_chain_insert_unprotected( } /** - * @brief Append a node on the end of a chain + * @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 ensure the atomicity of the - * append operation. + * NOTE: It disables interrupts to ensure the atomicity of the + * append operation. */ RTEMS_INLINE_ROUTINE void rtems_chain_append( rtems_chain_control *the_chain, @@ -542,12 +551,12 @@ RTEMS_INLINE_ROUTINE void rtems_chain_append( } /** - * @brief Append a node on the end of a chain (unprotected) + * @brief Append a node on the end of a chain (unprotected). * - * 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 does NOT disable interrupts to ensure the atomicity of the - * append operation. + * NOTE: It does NOT disable interrupts to ensure the atomicity of the + * append operation. */ RTEMS_INLINE_ROUTINE void rtems_chain_append_unprotected( rtems_chain_control *the_chain, @@ -557,15 +566,16 @@ RTEMS_INLINE_ROUTINE void rtems_chain_append_unprotected( _Chain_Append_unprotected( the_chain, the_node ); } -/** @brief Prepend a Node +/** + * @brief Prepend a node. * - * This routine prepends the_node onto the front of the_chain. + * This routine prepends the_node onto the front of the_chain. * - * @param[in] the_chain is the chain to be operated upon. - * @param[in] the_node is the node to be prepended. + * @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. + * NOTE: It disables interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void rtems_chain_prepend( rtems_chain_control *the_chain, @@ -575,15 +585,16 @@ RTEMS_INLINE_ROUTINE void rtems_chain_prepend( _Chain_Prepend( the_chain, the_node ); } -/** @brief Prepend a Node (unprotected) +/** + * @brief Prepend a node (unprotected). * - * This routine prepends the_node onto the front of the_chain. + * This routine prepends the_node onto the front of the_chain. * - * @param[in] the_chain is the chain to be operated upon. - * @param[in] the_node is the node to be prepended. + * @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. + * NOTE: It does NOT disable interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void rtems_chain_prepend_unprotected( rtems_chain_control *the_chain, diff --git a/cpukit/sapi/inline/rtems/extension.inl b/cpukit/sapi/inline/rtems/extension.inl index 968b62b58e..0d0cfc2320 100644 --- a/cpukit/sapi/inline/rtems/extension.inl +++ b/cpukit/sapi/inline/rtems/extension.inl @@ -3,7 +3,7 @@ * * @ingroup ClassicUserExtensions * - * @brief User Extensions API. + * @brief User Extensions API */ /* diff --git a/cpukit/sapi/inline/rtems/rbtree.inl b/cpukit/sapi/inline/rtems/rbtree.inl index f7983ad10d..20e7aa3890 100644 --- a/cpukit/sapi/inline/rtems/rbtree.inl +++ b/cpukit/sapi/inline/rtems/rbtree.inl @@ -1,18 +1,20 @@ /** - * @file rtems/rbtree.inl + * @file + * + * @brief Constants and Structures Associated with the RBTree API in RTEMS * - * This include file contains all the constants and structures associated - * with the RBTree API in RTEMS. The rbtree is a Red Black Tree that - * is part of the Super Core. This is the published interface to that - * code. + * This include file contains all the constants and structures associated + * with the RBTree API in RTEMS. The rbtree is a Red Black Tree that + * is part of the Super Core. This is the published interface to that + * code. */ /* - * Copyright (c) 2010-2012 Gedare Bloom. + * Copyright (c) 2010-2012 Gedare Bloom. * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. */ #ifndef _RTEMS_RBTREE_H @@ -25,11 +27,11 @@ #include <rtems/score/rbtree.inl> /** - * @brief Initialize a RBTree Header + * @brief Initialize a RBTree header. * - * This routine initializes @a the_rbtree structure to manage the - * contiguous array of @a number_nodes nodes which starts at - * @a starting_address. Each node is of @a node_size bytes. + * This routine initializes @a the_rbtree structure to manage the + * contiguous array of @a number_nodes nodes which starts at + * @a starting_address. Each node is of @a node_size bytes. */ RTEMS_INLINE_ROUTINE void rtems_rbtree_initialize( rtems_rbtree_control *the_rbtree, @@ -45,9 +47,9 @@ RTEMS_INLINE_ROUTINE void rtems_rbtree_initialize( } /** - * @brief Initialize this RBTree as Empty + * @brief Initialize this RBTree as Empty * - * This routine initializes @a the_rbtree to contain zero nodes. + * This routine initializes @a the_rbtree to contain zero nodes. */ RTEMS_INLINE_ROUTINE void rtems_rbtree_initialize_empty( rtems_rbtree_control *the_rbtree, @@ -59,10 +61,10 @@ RTEMS_INLINE_ROUTINE void rtems_rbtree_initialize_empty( } /** - * @brief Set off rbtree + * @brief Set off RBtree. * - * This function sets the next and previous fields of the @a node to NULL - * indicating the @a node is not part of any rbtree. + * This function sets the next and previous fields of the @a node to NULL + * indicating the @a node is not part of any rbtree. */ RTEMS_INLINE_ROUTINE void rtems_rbtree_set_off_rbtree( rtems_rbtree_node *node @@ -72,10 +74,10 @@ RTEMS_INLINE_ROUTINE void rtems_rbtree_set_off_rbtree( } /** - * @brief Is the Node off RBTree + * @brief Is the Node off RBTree. * - * This function returns true if the @a node is not on a rbtree. A @a node is - * off rbtree if the next and previous fields are set to NULL. + * This function returns true if the @a node is not on a rbtree. A @a node is + * off rbtree if the next and previous fields are set to NULL. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_node_off_rbtree( const rtems_rbtree_node *node @@ -85,9 +87,9 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_node_off_rbtree( } /** - * @brief Is the RBTree Node Pointer NULL + * @brief Is the RBTree Node Pointer NULL. * - * This function returns true if @a the_node is NULL and false otherwise. + * This function returns true if @a the_node is NULL and false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_null_node( const rtems_rbtree_node *the_node @@ -97,9 +99,9 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_null_node( } /** - * @brief Return pointer to RBTree Root + * @brief Return pointer to RBTree root. * - * This function returns a pointer to the root node of @a the_rbtree. + * This function returns a pointer to the root node of @a the_rbtree. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_root( const rtems_rbtree_control *the_rbtree @@ -109,9 +111,9 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_root( } /** - * @brief Return pointer to RBTree Minimum + * @brief Return pointer to RBTree Minimum * - * This function returns a pointer to the minimum node of @a the_rbtree. + * This function returns a pointer to the minimum node of @a the_rbtree. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_min( const rtems_rbtree_control *the_rbtree @@ -121,9 +123,9 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_min( } /** - * @brief Return pointer to RBTree Maximum + * @brief Return pointer to RBTree maximum. * - * This function returns a pointer to the maximum node of @a the_rbtree. + * This function returns a pointer to the maximum node of @a the_rbtree. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_max( const rtems_rbtree_control *the_rbtree @@ -133,9 +135,9 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_max( } /** - * @brief Return pointer to the left child node from this node + * @brief Return pointer to the left child node from this node. * - * This function returns a pointer to the left child node of @a the_node. + * This function returns a pointer to the left child node of @a the_node. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_left( const rtems_rbtree_node *the_node @@ -145,9 +147,9 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_left( } /** - * @brief Return pointer to the right child node from this node + * @brief Return pointer to the right child node from this node. * - * This function returns a pointer to the right child node of @a the_node. + * This function returns a pointer to the right child node of @a the_node. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_right( const rtems_rbtree_node *the_node @@ -157,9 +159,9 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_right( } /** - * @brief Return pointer to the parent child node from this node + * @brief Return pointer to the parent child node from this node. * - * This function returns a pointer to the parent node of @a the_node. + * This function returns a pointer to the parent node of @a the_node. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_parent( const rtems_rbtree_node *the_node @@ -169,10 +171,10 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_parent( } /** - * @brief Are Two Nodes Equal + * @brief Are two nodes equal. * - * This function returns true if @a left and @a right are equal, - * and false otherwise. + * This function returns true if @a left and @a right are equal, + * and false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_are_nodes_equal( const rtems_rbtree_node *left, @@ -183,10 +185,10 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_are_nodes_equal( } /** - * @brief Is the RBTree Empty + * @brief Is the RBTree empty. * - * This function returns true if there a no nodes on @a the_rbtree and - * false otherwise. + * This function returns true if there a no nodes on @a the_rbtree and + * false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_empty( const rtems_rbtree_control *the_rbtree @@ -196,10 +198,10 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_empty( } /** - * @brief Is this the Minimum Node on the RBTree + * @brief Is this the minimum node on the RBTree. * - * This function returns true if @a the_node is the min node on @a the_rbtree - * and false otherwise. + * This function returns true if @a the_node is the min node on @a the_rbtree + * and false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_min( const rtems_rbtree_control *the_rbtree, @@ -210,10 +212,10 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_min( } /** - * @brief Is this the Maximum Node on the RBTree + * @brief Is this the maximum node on the RBTree. * - * This function returns true if @a the_node is the max node on @a the_rbtree - * and false otherwise. + * This function returns true if @a the_node is the max node on @a the_rbtree + * and false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_max( const rtems_rbtree_control *the_rbtree, @@ -225,10 +227,10 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_max( /** - * @brief Does this RBTree have only One Node + * @brief Does this RBTree have only one node. * - * This function returns true if there is only one node on @a the_rbtree and - * false otherwise. + * This function returns true if there is only one node on @a the_rbtree and + * false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_has_only_one_node( const rtems_rbtree_control *the_rbtree @@ -238,10 +240,10 @@ RTEMS_INLINE_ROUTINE bool rtems_rbtree_has_only_one_node( } /** - * @brief Is this Node the RBTree Root + * @brief Is this node the RBTree root. * - * This function returns true if @a the_node is the root of @a the_rbtree and - * false otherwise. + * This function returns true if @a the_node is the root of @a the_rbtree and + * false otherwise. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_root( const rtems_rbtree_control *the_rbtree, @@ -262,14 +264,14 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node* rtems_rbtree_find_unprotected( return _RBTree_Find_unprotected( the_rbtree, the_node ); } -/** @brief Find the node with given key in the tree +/** @brief Find the node with given key in the tree. * - * This function returns a pointer to the node having key equal to the key - * of @a the_node if it exists within @a the_rbtree, and NULL if not. - * @a the_node has to be made up before a search. + * This function returns a pointer to the node having key equal to the key + * of @a the_node if it exists within @a the_rbtree, and NULL if not. + * @a the_node has to be made up before a search. * - * @note If the tree is not unique and contains duplicate keys, the set - * of duplicate keys acts as FIFO. + * @note If the tree is not unique and contains duplicate keys, the set + * of duplicate keys acts as FIFO. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node* rtems_rbtree_find( const rtems_rbtree_control *the_rbtree, @@ -331,10 +333,10 @@ RTEMS_INLINE_ROUTINE void rtems_rbtree_extract_unprotected( } /** - * @brief Extract the specified node from a rbtree + * @brief Extract the specified node from a rbtree. * - * This routine extracts @a the_node from @a the_rbtree on which it resides. - * It disables interrupts to ensure the atomicity of the extract operation. + * This routine extracts @a the_node from @a the_rbtree on which it resides. + * It disables interrupts to ensure the atomicity of the extract operation. */ RTEMS_INLINE_ROUTINE void rtems_rbtree_extract( rtems_rbtree_control *the_rbtree, @@ -345,10 +347,10 @@ RTEMS_INLINE_ROUTINE void rtems_rbtree_extract( } /** - * @brief Obtain the min node on a rbtree + * @brief Obtain the min node on a rbtree. * - * This function removes the min node from @a the_rbtree and returns - * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. + * This function removes the min node from @a the_rbtree and returns + * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_min_unprotected( @@ -359,11 +361,11 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_min_unprotected( } /** - * @brief Obtain the min node on a rbtree + * @brief Obtain the min node on a rbtree. * - * This function removes the min node from @a the_rbtree and returns - * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. - * It disables interrupts to ensure the atomicity of the get operation. + * This function removes the min node from @a the_rbtree and returns + * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. + * It disables interrupts to ensure the atomicity of the get operation. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_min( rtems_rbtree_control *the_rbtree @@ -373,10 +375,10 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_min( } /** - * @brief Obtain the max node on a rbtree + * @brief Obtain the max node on a rbtree. * - * This function removes the max node from @a the_rbtree and returns - * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. + * This function removes the max node from @a the_rbtree and returns + * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_max_unprotected( @@ -387,11 +389,11 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_max_unprotected( } /** - * @brief Obtain the max node on a rbtree + * @brief Obtain the max node on a rbtree. * - * This function removes the max node from @a the_rbtree and returns - * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. - * It disables interrupts to ensure the atomicity of the get operation. + * This function removes the max node from @a the_rbtree and returns + * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. + * It disables interrupts to ensure the atomicity of the get operation. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_max( rtems_rbtree_control *the_rbtree @@ -401,11 +403,11 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_get_max( } /** - * @brief Peek at the min node on a rbtree + * @brief Peek at the min node on a rbtree. * - * This function returns a pointer to the min node from @a the_rbtree - * without changing the tree. If @a the_rbtree is empty, - * then NULL is returned. + * This function returns a pointer to the min node from @a the_rbtree + * without changing the tree. If @a the_rbtree is empty, + * then NULL is returned. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_peek_min( const rtems_rbtree_control *the_rbtree @@ -415,11 +417,11 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_peek_min( } /** - * @brief Peek at the max node on a rbtree + * @brief Peek at the max node on a rbtree. * - * This function returns a pointer to the max node from @a the_rbtree - * without changing the tree. If @a the_rbtree is empty, - * then NULL is returned. + * This function returns a pointer to the max node from @a the_rbtree + * without changing the tree. If @a the_rbtree is empty, + * then NULL is returned. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_peek_max( const rtems_rbtree_control *the_rbtree @@ -439,11 +441,11 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_control *rtems_rbtree_find_header_unprotected( } /** - * @brief Find the control header of the tree containing a given node. + * @brief Find the control header of the tree containing a given node. * - * This routine finds the rtems_rbtree_control structure of the tree - * containing @a the_node. - * It disables interrupts to ensure the atomicity of the find operation. + * This routine finds the rtems_rbtree_control structure of the tree + * containing @a the_node. + * It disables interrupts to ensure the atomicity of the find operation. */ RTEMS_INLINE_ROUTINE rtems_rbtree_control *rtems_rbtree_find_header( rtems_rbtree_node *the_node @@ -464,15 +466,15 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_insert_unprotected( } /** - * @brief Insert a node on a rbtree + * @brief Insert a node on a rbtree. * - * This routine inserts @a the_node on @a the_rbtree. - * It disables interrupts to ensure the atomicity of the insert operation. + * This routine inserts @a the_node on @a the_rbtree. + * It disables interrupts to ensure the atomicity of the insert operation. * - * @retval 0 Successfully inserted. - * @retval -1 NULL @a the_node. - * @retval RBTree_Node* if one with equal key to the key of @a the_node exists - * in an unique @a the_rbtree. + * @retval 0 Successfully inserted. + * @retval -1 NULL @a the_node. + * @retval RBTree_Node* if one with equal key to the key of @a the_node exists + * in an unique @a the_rbtree. */ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_insert( rtems_rbtree_control *the_rbtree, @@ -482,7 +484,8 @@ RTEMS_INLINE_ROUTINE rtems_rbtree_node *rtems_rbtree_insert( return _RBTree_Insert( the_rbtree, the_node ); } -/** @brief Determines whether the tree is unique +/** + * @brief Determines whether the tree is unique. */ RTEMS_INLINE_ROUTINE bool rtems_rbtree_is_unique( const rtems_rbtree_control *the_rbtree diff --git a/cpukit/sapi/inline/rtems/timespec.inl b/cpukit/sapi/inline/rtems/timespec.inl index 9874b65153..659c39fd35 100644 --- a/cpukit/sapi/inline/rtems/timespec.inl +++ b/cpukit/sapi/inline/rtems/timespec.inl @@ -1,9 +1,7 @@ /** - * @file rtems/sapi/timespec.inl + * @file * - * @ingroup - * - * @brief Timespec API. + * @brief Timespec API */ /* @@ -31,14 +29,14 @@ */ /** - * @brief Is Timespec Valid + * @brief Is timespec valid * - * This method determines the validity of a timespec. + * This method determines the validity of a timespec. * - * @param[in] time is the timespec instance to validate. + * @param[in] time is the timespec instance to validate. * - * @return This method returns true if @a time is valid and - * false otherwise. + * @retval true The timespec is valid. + * @retval false The timespec is not valid. */ RTEMS_INLINE_ROUTINE bool rtems_timespec_is_valid( const struct timespec *time @@ -48,15 +46,16 @@ RTEMS_INLINE_ROUTINE bool rtems_timespec_is_valid( } /** - * @brief Timespec Less Than Operator + * @brief Timespec less than operator. * - * This method is the less than operator for timespecs. + * This method is the less than operator for timespecs. * - * @param[in] lhs is the left hand side timespec - * @param[in] rhs is the right hand side timespec + * @param[in] lhs is the left hand side timespec + * @param[in] rhs is the right hand side timespec * - * @return This method returns true if @a lhs is less than the @a rhs and - * false otherwise. + * @retval true @a lhs is less than @a rhr. + * @retval false @a lhs is not less than @a rhr. + * */ RTEMS_INLINE_ROUTINE bool rtems_timespec_less_than( const struct timespec *lhs, @@ -67,15 +66,15 @@ RTEMS_INLINE_ROUTINE bool rtems_timespec_less_than( } /** - * @brief Add to a Timespec + * @brief Add to a timespec. * - * This routine adds two timespecs. The second argument is added - * to the first. + * This routine adds two timespecs. The second argument is added + * to the first. * - * @param[in] time is the base time to be added to - * @param[in] add is the timespec to add to the first argument + * @param[in] time is the base time to be added to + * @param[in] add is the timespec to add to the first argument * - * @return This method returns the number of seconds @a time increased by. + * @return This method returns the number of seconds @a time increased by. */ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_add_to( struct timespec *time, @@ -86,14 +85,14 @@ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_add_to( } /** - * @brief Convert Timespec to Number of Ticks + * @brief Convert timespec to number of ticks. * - * This routine convert the @a time timespec to the corresponding number - * of clock ticks. + * This routine convert the @a time timespec to the corresponding number + * of clock ticks. * - * @param[in] time is the time to be converted + * @param[in] time is the time to be converted * - * @return This method returns the number of ticks computed. + * @return This method returns the number of ticks computed. */ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_to_ticks( const struct timespec *time @@ -103,13 +102,13 @@ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_to_ticks( } /** - * @brief Convert Ticks to Timespec + * @brief Convert ticks to timespec. * - * This routine converts the @a ticks value to the corresponding - * timespec format @a time. + * This routine converts the @a ticks value to the corresponding + * timespec format @a time. * - * @param[in] time is the timespec format time result - * @param[in] ticks is the number of ticks to convert + * @param[in] time is the timespec format time result + * @param[in] ticks is the number of ticks to convert */ RTEMS_INLINE_ROUTINE void rtems_timespec_from_ticks( @@ -121,16 +120,16 @@ RTEMS_INLINE_ROUTINE void rtems_timespec_from_ticks( } /** - * @brief Subtract Two Timespec + * @brief Subtract two timespec. * - * This routine subtracts two timespecs. @a result is set to - * @a end - @a start. + * This routine subtracts two timespecs. @a result is set to + * @a end - @a start. * - * @param[in] start is the starting time - * @param[in] end is the ending time - * @param[in] result is the difference between starting and ending time. + * @param[in] start is the starting time + * @param[in] end is the ending time + * @param[in] result is the difference between starting and ending time. * - * @return This method fills in @a result. + * @return This method fills in @a result. */ RTEMS_INLINE_ROUTINE void rtems_timespec_subtract( const struct timespec *start, @@ -142,17 +141,17 @@ RTEMS_INLINE_ROUTINE void rtems_timespec_subtract( } /** - * @brief Divide Timespec By Integer + * @brief Divide timespec by integer. * - * This routine divides a timespec by an integer value. The expected - * use is to assist in benchmark calculations where you typically - * divide a duration by a number of iterations. + * This routine divides a timespec by an integer value. The expected + * use is to assist in benchmark calculations where you typically + * divide a duration by a number of iterations. * - * @param[in] time is the total - * @param[in] iterations is the number of iterations - * @param[in] result is the average time. + * @param[in] time is the total + * @param[in] iterations is the number of iterations + * @param[in] result is the average time. * - * @return This method fills in @a result. + * @return This method fills in @a result. */ RTEMS_INLINE_ROUTINE void rtems_timespec_divide_by_integer( const struct timespec *time, @@ -164,17 +163,17 @@ RTEMS_INLINE_ROUTINE void rtems_timespec_divide_by_integer( } /** - * @brief Divide Timespec + * @brief Divide timespec. * - * This routine divides a timespec by another timespec. The - * intended use is for calculating percentages to three decimal points. + * This routine divides a timespec by another timespec. The + * intended use is for calculating percentages to three decimal points. * - * @param[in] lhs is the left hand number - * @param[in] rhs is the right hand number - * @param[in] ival_percentage is the integer portion of the average - * @param[in] fval_percentage is the thousandths of percentage + * @param[in] lhs is the left hand number + * @param[in] rhs is the right hand number + * @param[in] ival_percentage is the integer portion of the average + * @param[in] fval_percentage is the thousandths of percentage * - * @return This method fills in @a result. + * @return This method fills in @a result. */ RTEMS_INLINE_ROUTINE void rtems_timespec_divide( const struct timespec *lhs, @@ -187,14 +186,14 @@ RTEMS_INLINE_ROUTINE void rtems_timespec_divide( } /** - * @brief Set Timespec to Seconds Nanosecond + * @brief Set timespec to seconds nanosecond. * - * This method sets the timespec to the specified seconds and nanoseconds - * value. + * This method sets the timespec to the specified seconds and nanoseconds + * value. * - * @param[in] _time points to the timespec instance to validate. - * @param[in] _seconds is the seconds portion of the timespec - * @param[in] _nanoseconds is the nanoseconds portion of the timespec + * @param[in] _time points to the timespec instance to validate. + * @param[in] _seconds is the seconds portion of the timespec + * @param[in] _nanoseconds is the nanoseconds portion of the timespec */ RTEMS_INLINE_ROUTINE void rtems_timespec_set( struct timespec *_time, @@ -206,12 +205,12 @@ RTEMS_INLINE_ROUTINE void rtems_timespec_set( } /** - * @brief Zero Timespec + * @brief Zero timespec. * - * This method sets the timespec to zero. - * value. + * This method sets the timespec to zero. + * value. * - * @param[in] _time points to the timespec instance to zero. + * @param[in] _time points to the timespec instance to zero. */ RTEMS_INLINE_ROUTINE void rtems_timespec_zero( struct timespec *_time @@ -221,13 +220,13 @@ RTEMS_INLINE_ROUTINE void rtems_timespec_zero( } /** - * @brief Get Seconds Portion of Timespec + * @brief Get seconds portion of timespec. * - * This method returns the seconds portion of the specified timespec + * This method returns the seconds portion of the specified timespec * - * @param[in] _time points to the timespec + * @param[in] _time points to the timespec * - * @return The seconds portion of @a _time. + * @return The seconds portion of @a _time. */ RTEMS_INLINE_ROUTINE time_t rtems_timespec_get_seconds( struct timespec *_time @@ -237,13 +236,13 @@ RTEMS_INLINE_ROUTINE time_t rtems_timespec_get_seconds( } /** - * @brief Get Nanoseconds Portion of Timespec + * @brief Get nanoseconds portion of timespec. * - * This method returns the nanoseconds portion of the specified timespec + * This method returns the nanoseconds portion of the specified timespec * - * @param[in] _time points to the timespec + * @param[in] _time points to the timespec * - * @return The nanoseconds portion of @a _time. + * @return The nanoseconds portion of @a _time. */ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_get_nanoseconds( struct timespec *_time @@ -254,15 +253,15 @@ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_get_nanoseconds( /** - * @brief Timespec Greater Than Operator + * @brief Timespec greater than operator. * - * This method is the greater than operator for timespecs. + * This method is the greater than operator for timespecs. * - * @param[in] lhs is the left hand side timespec - * @param[in] rhs is the right hand side timespec + * @param[in] lhs is the left hand side timespec + * @param[in] rhs is the right hand side timespec * - * @return This method returns true if @a lhs is greater than the @a rhs and - * false otherwise. + * @retval true @a lhs is greater than @a rhr. + * @retval false @a lhs is not greater than @a rhr. */ RTEMS_INLINE_ROUTINE bool rtems_timespec_greater_than( const struct timespec *_lhs, @@ -274,13 +273,13 @@ RTEMS_INLINE_ROUTINE bool rtems_timespec_greater_than( /** * @brief Timespec equal to Operator * - * This method is the is equal to than operator for timespecs. + * This method is the is equal to than operator for timespecs. * - * @param[in] lhs is the left hand side timespec - * @param[in] rhs is the right hand side timespec + * @param[in] lhs is the left hand side timespec + * @param[in] rhs is the right hand side timespec * - * @return This method returns true if @a lhs is equal to @a rhs and - * false otherwise. + * @retval true @a lhs is equal to @a rhr. + * @retval false @a lhs is not equal to @a rhr. */ RTEMS_INLINE_ROUTINE bool rtems_timespec_equal_to( const struct timespec *lhs, |