From e4f2fe13e777a9a0c44acdea42951b28356bf7dc Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 6 Aug 2009 16:32:54 +0000 Subject: 2009-08-06 Christian Mauderer * rtems/include/rtems/rtems/types.h: Improve documentation. --- cpukit/rtems/include/rtems/rtems/types.h | 149 ++++++++++++++++++------------- 1 file changed, 85 insertions(+), 64 deletions(-) (limited to 'cpukit/rtems/include/rtems/rtems/types.h') diff --git a/cpukit/rtems/include/rtems/rtems/types.h b/cpukit/rtems/include/rtems/rtems/types.h index 4cd4dd5a0d..4c867c5cf4 100644 --- a/cpukit/rtems/include/rtems/rtems/types.h +++ b/cpukit/rtems/include/rtems/rtems/types.h @@ -1,7 +1,9 @@ /** - * @file rtems/rtems/types.h + * @file * - * This include file defines the types used by the RTEMS API. + * @ingroup ClassicRTEMS + * + * @brief Types used by the Classic API. */ /* COPYRIGHT (c) 1989-2008. @@ -17,15 +19,6 @@ #ifndef _RTEMS_RTEMS_TYPES_H #define _RTEMS_RTEMS_TYPES_H -/** - * @defgroup ClassicTypes Types - * - * @ingroup ClassicRTEMS - * - * This encapsulates functionality which XXX - */ -/**@{*/ - /* * RTEMS basic type definitions */ @@ -46,68 +39,92 @@ extern "C" { #endif -/** This type defines a single precision float. */ +/** + * @addtogroup ClassicRTEMS + * + * @{ + */ + #ifdef RTEMS_DEPRECATED_TYPES +/** + * @brief Single precision float type. + * + * @deprecated Use @c float instead. + */ typedef single_precision rtems_single; -/** This type defines a double precision float. */ +/** + * @brief Double precision float type. + * + * @deprecated Use @c double instead. + */ typedef double_precision rtems_double; -/** This type defines the RTEMS boolean type . */ +/** + * @brief RTEMS boolean type. + * + * @deprecated Use @c bool instead + */ typedef boolean rtems_boolean; #endif -/** This type defines is for Classic API object names. */ +/** + * @brief Classic API object name Type. + * + * Contains the name of a Classic API object. It is an unsigned 32 bit integer + * which can be treated as a numeric value or initialized using + * rtems_build_name() to contain four ASCII characters. + */ typedef uint32_t rtems_name; /** - * This type defines is for RTEMS object Id. Although this - * type name is specific to the Classic API, the format of - * an object Id is the same across all APIs. + * @brief Used to manage and manipulate RTEMS object identifier. */ typedef Objects_Id rtems_id; /** - * This defines a value that is an invalid object Id. + * @brief Invalid object identifier value. + * + * No object can have this identifier value. */ #define RTEMS_ID_NONE OBJECTS_ID_NONE /** - * This type is the public name for task context area. + * @brief Public name for task context area. */ typedef Context_Control rtems_context; #if (CPU_HARDWARE_FP == TRUE) || (CPU_SOFTWARE_FP == TRUE) /** - * This type is the public name for task floating point context area. + * @brief Public name for task floating point context area. */ typedef Context_Control_fp rtems_context_fp; #endif /** - * This type is the public name for the architecture specific - * stack frame built as part of vectoring an interrupt. + * @brief Defines the format of the interrupt stack frame as it appears to a + * user ISR. + * + * This data structure may not be defined on all ports */ typedef CPU_Interrupt_frame rtems_interrupt_frame; /** - * This type defines the public name for the information - * structure returned by the Heap Handler via the Region - * Manager. + * @brief Information structure returned by the Heap Handler via the Region + * Manager. */ typedef Heap_Information_block region_information_block; /** - * This type defines the public name for the type that is - * used to manage intervals specified by clock ticks. + * @brief Used to manage and manipulate intervals specified by clock ticks. */ typedef Watchdog_Interval rtems_interval; /** - * This is the public type used to represent the CPU usage per thread. + * @brief Represents the CPU usage per thread. * - * @note When using nanosecond granularity timing, RTEMS may internally - * use a variety of represenations. + * When using nano seconds granularity timing, RTEMS may internally use a + * variety of represenations. */ #ifndef __RTEMS_USE_TICKS_CPU_USAGE_STATISTICS__ typedef struct timespec rtems_thread_cpu_usage_t; @@ -117,30 +134,41 @@ typedef Watchdog_Interval rtems_interval; /** - * The following record defines the time of control block. This - * control block is used to maintain the current time of day. - * - * @note This is an RTEID (a.k.a. Classic API) style time/date. + * @brief Data structure to manage and manipulate calendar time. */ typedef struct { - /** This field is the year, A.D. */ + /** + * @brief Year, A.D. + */ uint32_t year; - /** This field is the month, 1 -> 12 */ + /** + * @brief Month, 1 .. 12. + */ uint32_t month; - /** This field is the day, 1 -> 31 */ + /** + * @brief Day, 1 .. 31. + */ uint32_t day; - /** This field is the hour, 0 -> 23 */ + /** + * @brief Hour, 0 .. 23. + */ uint32_t hour; - /** This field is the minute, 0 -> 59 */ + /** + * @brief Minute, 0 .. 59. + */ uint32_t minute; - /** This field is the second, 0 -> 59 */ + /** + * @brief Second, 0 .. 59. + */ uint32_t second; - /** This field is the elapsed ticks between secs */ + /** + * @brief Elapsed ticks between seconds. + */ uint32_t ticks; } rtems_time_of_day; /** - * This defines the public name for an RTEMS API task mode type. + * @brief Task mode type. */ typedef Modes_Control rtems_mode; @@ -149,67 +177,60 @@ typedef Modes_Control rtems_mode; */ #if defined(RTEMS_MULTIPROCESSING) /** - * This defines the public name for the set of MPCI packet - * classes which are internally dispatched to the managers. + * @brief Set of MPCI packet classes which are internally dispatched to the + * managers. */ typedef MP_packet_Classes rtems_mp_packet_classes; /** - * This defines the public name for the common prefix - * found at the beginning of each MPCI packet sent between - * nodes. This can be thought of as an envelope. + * @brief Prefix found at the beginning of each MPCI packet sent between nodes. */ typedef MP_packet_Prefix rtems_packet_prefix; /** - * This defines the public name for the type for an indirect pointer - * to the initialization entry point for an MPCI handler. + * @brief Indirect pointer to the initialization entry point for an MPCI + * handler. */ typedef MPCI_initialization_entry rtems_mpci_initialization_entry; /** - * This defines the public name for the type for an indirect pointer - * to the get_packet entry point for an MPCI handler. + * @brief Indirect pointer to the get_packet entry point for an MPCI handler. */ typedef MPCI_get_packet_entry rtems_mpci_get_packet_entry; /** - * This defines the public name for the type for an indirect pointer - * to the return_packet entry point for an MPCI handler. + * @brief Indirect pointer to the return_packet entry point for an MPCI + * handler. */ typedef MPCI_return_packet_entry rtems_mpci_return_packet_entry; /** - * This defines the public name for the type for an indirect pointer - * to the send_packet entry point for an MPCI handler. + * @brief Indirect pointer to the send_packet entry point for an MPCI handler. */ typedef MPCI_send_entry rtems_mpci_send_packet_entry; /** - * This defines the public name for the type for an indirect pointer - * to the receive entry point for an MPCI handler. + * @brief Indirect pointer to the receive entry point for an MPCI handler. */ typedef MPCI_receive_entry rtems_mpci_receive_packet_entry; /** - * This defines the public name for the return type from every - * MPCI handler routine. + * @brief Return type from every MPCI handler routine. */ typedef MPCI_Entry rtems_mpci_entry; /** - * This defines the public name for the structure which is used to - * configure an MPCI handler. + * @brief Structure which is used to configure an MPCI handler. */ typedef MPCI_Control rtems_mpci_table; #endif +/** @} */ + #ifdef __cplusplus } #endif -/**@}*/ - #endif /* end of include file */ -- cgit v1.2.3