From 8c8fd64a704ccd5958a6a426771ea533c4eb8744 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 6 Jun 2008 18:03:45 +0000 Subject: 2008-06-06 Joel Sherrill * rtems/include/rtems.h, rtems/include/rtems/rtems/clock.h, rtems/include/rtems/rtems/config.h, rtems/include/rtems/rtems/dpmem.h, rtems/include/rtems/rtems/eventset.h, rtems/include/rtems/rtems/object.h, rtems/include/rtems/rtems/part.h, rtems/include/rtems/rtems/ratemon.h, rtems/include/rtems/rtems/region.h, rtems/include/rtems/rtems/sem.h, rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h, rtems/include/rtems/rtems/types.h, rtems/src/ratemonperiod.c: Improve Classic API Doxygen. --- cpukit/rtems/include/rtems.h | 22 +++--- cpukit/rtems/include/rtems/rtems/clock.h | 2 + cpukit/rtems/include/rtems/rtems/config.h | 56 +++++++++++++++ cpukit/rtems/include/rtems/rtems/dpmem.h | 13 ++-- cpukit/rtems/include/rtems/rtems/eventset.h | 3 +- cpukit/rtems/include/rtems/rtems/object.h | 10 +-- cpukit/rtems/include/rtems/rtems/part.h | 22 ++++-- cpukit/rtems/include/rtems/rtems/ratemon.h | 105 +++++++++++++++++++++++++--- cpukit/rtems/include/rtems/rtems/region.h | 51 ++++++++++++-- cpukit/rtems/include/rtems/rtems/sem.h | 29 +++++++- cpukit/rtems/include/rtems/rtems/tasks.h | 25 +++++-- cpukit/rtems/include/rtems/rtems/timer.h | 65 +++++++++++++++-- cpukit/rtems/include/rtems/rtems/types.h | 87 ++++++++++++++++++++--- 13 files changed, 423 insertions(+), 67 deletions(-) (limited to 'cpukit/rtems/include') diff --git a/cpukit/rtems/include/rtems.h b/cpukit/rtems/include/rtems.h index 49cf5f76e0..8eb91f12fa 100644 --- a/cpukit/rtems/include/rtems.h +++ b/cpukit/rtems/include/rtems.h @@ -1,10 +1,8 @@ /** * @file rtems.h * - * This include file contains information about RTEMS executive that - * is required by the application and is CPU independent. It includes - * two (2) CPU dependent files to tailor its data structures for a - * particular processor. + * This include file provides the public interface to the RTEMS Classic + * API. */ /* COPYRIGHT (c) 1989-2008. @@ -23,7 +21,8 @@ /** * @defgroup ClassicRTEMS Classic API RTEMS Header * - * This encapsulates functionality which XXX + * This encapsulates functionality which is specific to the Classic API + * and generally shared across the various object classes. */ /**@{*/ @@ -42,7 +41,6 @@ extern "C" { * which are not included in the formally defined and supported API. * Define this at your own risk. */ - #define __RTEMS_APPLICATION__ #endif @@ -85,9 +83,9 @@ extern "C" { */ #define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP -/* - * The following define the constants which may be used in name searches. - */ +/********************************************************************** + * CONSTANTS WHICH MAY BE USED IN OBJECT NAME TO ID SEARCHES + **********************************************************************/ /** * This constant indicates that the search is across all nodes. @@ -115,9 +113,9 @@ extern "C" { */ #define RTEMS_WHO_AM_I OBJECTS_WHO_AM_I -/* - * Parameters and return id's for _Objects_Get_next - */ +/********************************************************************** + * Parameters and return Id's for _Objects_Get_next + **********************************************************************/ /** * This constant is the lowest valid valid for the index portion diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h index a6fc6bbb6a..721e30ae35 100644 --- a/cpukit/rtems/include/rtems/rtems/clock.h +++ b/cpukit/rtems/include/rtems/rtems/clock.h @@ -63,7 +63,9 @@ typedef enum { * Standard flavor style to return TOD in for a rtems_clock_get option. */ typedef struct { + /** This is the seconds portion of a time of day. */ uint32_t seconds; + /** This is the microseconds portion of a time of day. */ uint32_t microseconds; } rtems_clock_time_value; diff --git a/cpukit/rtems/include/rtems/rtems/config.h b/cpukit/rtems/include/rtems/rtems/config.h index 1c7866ae8d..5afc3063d4 100644 --- a/cpukit/rtems/include/rtems/rtems/config.h +++ b/cpukit/rtems/include/rtems/rtems/config.h @@ -41,16 +41,72 @@ extern "C" { * + required number of each object type */ typedef struct { + /** + * This field contains the maximum number of Classic API + * Tasks which are configured for this application. + */ uint32_t maximum_tasks; + + /** + * This field contains the maximum number of Classic API + * Timers which are configured for this application. + */ uint32_t maximum_timers; + + /** + * This field contains the maximum number of Classic API + * Semaphores which are configured for this application. + */ uint32_t maximum_semaphores; + + /** + * This field contains the maximum number of Classic API + * Message Queues which are configured for this application. + */ uint32_t maximum_message_queues; + + /** + * This field contains the maximum number of Classic API + * Partitions which are configured for this application. + */ uint32_t maximum_partitions; + + /** + * This field contains the maximum number of Classic API + * Regions which are configured for this application. + */ uint32_t maximum_regions; + + /** + * This field contains the maximum number of Classic API + * Dual Ported Memory Areas which are configured for this + * application. + */ uint32_t maximum_ports; + + /** + * This field contains the maximum number of Classic API + * Rate Monotonic Periods which are configured for this + * application. + */ uint32_t maximum_periods; + + /** + * This field contains the maximum number of Classic API + * Barriers which are configured for this application. + */ uint32_t maximum_barriers; + + /** + * This field contains the number of Classic API Initialization + * Tasks which are configured for this application. + */ uint32_t number_of_initialization_tasks; + + /** + * This field is the set of Classic API Initialization + * Tasks which are configured for this application. + */ rtems_initialization_tasks_table *User_initialization_tasks_table; } rtems_api_configuration_table; diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h b/cpukit/rtems/include/rtems/rtems/dpmem.h index 5a16107471..5a862c6984 100644 --- a/cpukit/rtems/include/rtems/rtems/dpmem.h +++ b/cpukit/rtems/include/rtems/rtems/dpmem.h @@ -50,7 +50,8 @@ extern "C" { /** * @defgroup ClassicDPMEM Classic API Dual Ported Memory * - * This encapsulates functionality which XXX + * This encapsulates functionality related to the + * Classic API Dual Ported Memory Manager. */ /**@{*/ @@ -60,10 +61,14 @@ extern "C" { * all information required to support the port related operations. */ typedef struct { + /** This field is the object management portion of a Port instance. */ Objects_Control Object; - void *internal_base; /* base internal address */ - void *external_base; /* base external address */ - uint32_t length; /* length of dual-ported area */ + /** This field is the base internal address of the port. */ + void *internal_base; + /** This field is the base external address of the port. */ + void *external_base; + /** This field is the length of dual-ported area of the port. */ + uint32_t length; } Dual_ported_memory_Control; /** diff --git a/cpukit/rtems/include/rtems/rtems/eventset.h b/cpukit/rtems/include/rtems/rtems/eventset.h index c6e991bb96..e8e50bd06f 100644 --- a/cpukit/rtems/include/rtems/rtems/eventset.h +++ b/cpukit/rtems/include/rtems/rtems/eventset.h @@ -22,7 +22,8 @@ /** * @defgroup ClassicEventSet Classic API Event Set * - * This encapsulates functionality which XXX + * This encapsulates functionality related to Classic API + * Event Sets. These are used by the Classic API Event Manager. */ /**@{*/ diff --git a/cpukit/rtems/include/rtems/rtems/object.h b/cpukit/rtems/include/rtems/rtems/object.h index 367e5ef224..6e8d6a9f4f 100644 --- a/cpukit/rtems/include/rtems/rtems/object.h +++ b/cpukit/rtems/include/rtems/rtems/object.h @@ -97,7 +97,7 @@ typedef struct { * @note The object must be have a name of the 32-bit form. * * @return @a *name will contain user defined object name - * @return @a{RTEMS_SUCCESSFUL - if successful + * @return @a RTEMS_SUCCESSFUL - if successful * @return error code - if unsuccessful */ rtems_status_code rtems_object_get_classic_name( @@ -149,7 +149,7 @@ rtems_status_code rtems_object_set_name( * * This function returns the API portion of the Id. * - * @param[in] id is the Id of the object to obtain the API from + * @param[in] _id is the Id of the object to obtain the API from * * @return This method returns the API portion of the provided * @a _id. @@ -166,7 +166,7 @@ rtems_status_code rtems_object_set_name( * * This function returns the class portion of the ID. * - * @param[in] id is the Id of the object to obtain the class from + * @param[in] _id is the Id of the object to obtain the class from * * @return This method returns the class portion of the provided * @a _id. @@ -183,7 +183,7 @@ rtems_status_code rtems_object_set_name( * * This function returns the node portion of the ID. * - * @param[in] id is the Id of the object to obtain the node from + * @param[in] _id is the Id of the object to obtain the node from * * @return This method returns the node portion of the provided * @a _id. @@ -200,7 +200,7 @@ rtems_status_code rtems_object_set_name( * * This function returns the index portion of the ID. * - * @param[in] id is the Id of the object to obtain the index from + * @param[in] _id is the Id of the object to obtain the index from * * @return This method returns the index portion of the provided * @a _id. diff --git a/cpukit/rtems/include/rtems/rtems/part.h b/cpukit/rtems/include/rtems/rtems/part.h index 3e1843978a..32b23ded6b 100644 --- a/cpukit/rtems/include/rtems/rtems/part.h +++ b/cpukit/rtems/include/rtems/rtems/part.h @@ -52,7 +52,8 @@ extern "C" { /** * @defgroup ClassicPart Classic API Partition * - * This encapsulates functionality which XXX + * This encapsulates functionality related to the + * Classic API Partition Manager. */ /**@{*/ @@ -60,13 +61,20 @@ extern "C" { * The following defines the control block used to manage each partition. */ typedef struct { + /** This field is the object management portion of a Partition instance. */ Objects_Control Object; - void *starting_address; /* physical address */ - uint32_t length; /* in bytes */ - uint32_t buffer_size; /* in bytes */ - rtems_attribute attribute_set; /* attributes */ - uint32_t number_of_used_blocks; /* or allocated buffers */ - Chain_Control Memory; /* buffer chain */ + /** This field is the physical starting address of the Partition. */ + void *starting_address; + /** This field is the size of the Partition in bytes. */ + uint32_t length; + /** This field is the size of each buffer in bytes */ + uint32_t buffer_size; + /** This field is the attribute set provided at create time. */ + rtems_attribute attribute_set; + /** This field is the of allocated buffers. */ + uint32_t number_of_used_blocks; + /** This field is the chain used to manage unallocated buffers. */ + Chain_Control Memory; } Partition_Control; /** diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h index cccf40dd9f..d1dfbeb64d 100644 --- a/cpukit/rtems/include/rtems/rtems/ratemon.h +++ b/cpukit/rtems/include/rtems/rtems/ratemon.h @@ -42,7 +42,8 @@ /** * @defgroup ClassicRateMon Classic API Rate Monotonic * - * This encapsulates functionality which XXX + * This encapsulates functionality related to the + * Classic API Rate Monotonic Manager. */ /**@{*/ @@ -54,7 +55,7 @@ extern "C" { * The user can define this at configure time and go back to ticks * resolution. */ -#ifndef __RTEMS_USE_TICKS_RATE_MONOTONIC_STATISTICS__ +#if defined(__RTEMS_USE_TICKS_RATE_MONOTONIC_STATISTICS__) /** * Enable the nanosecond accurate statistics * @@ -62,9 +63,14 @@ extern "C" { * is used. */ #define RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS +#endif +/** + * This is the type used to manage the rate monotonic timing + * statistics. + */ +#if defined(RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS) typedef struct timespec rtems_rate_monotonic_period_time_t; - #else typedef uint32_t rtems_rate_monotonic_period_time_t; #endif @@ -83,13 +89,37 @@ extern "C" { * period may be. */ typedef enum { - RATE_MONOTONIC_INACTIVE, /* off chain, never initialized */ - RATE_MONOTONIC_OWNER_IS_BLOCKING, /* on chain, owner is blocking on it */ - RATE_MONOTONIC_ACTIVE, /* on chain, running continuously */ - RATE_MONOTONIC_EXPIRED_WHILE_BLOCKING, /* on chain, expired while owner was */ - /* was blocking on it */ - RATE_MONOTONIC_EXPIRED /* off chain, will be reset by next */ - /* rtems_rate_monotonic_period */ + /** + * This value indicates the period is off the watchdog chain, + * and has never been initialized. + */ + RATE_MONOTONIC_INACTIVE, + + /** + * This value indicates the period is on the watchdog chain, and + * the owner is blocked waiting on it. + */ + RATE_MONOTONIC_OWNER_IS_BLOCKING, + + /** + * This value indicates the period is on the watchdog chain, and + * running. The owner should be executed or blocked waiting on + * another object. + */ + RATE_MONOTONIC_ACTIVE, + + /** + * This value indicates the period is on the watchdog chain, and + * has expired. The owner should be blocked waiting for the next period. + */ + RATE_MONOTONIC_EXPIRED_WHILE_BLOCKING, + + /** + * This value indicates the period is off the watchdog chain, and + * has expired. The owner is still executing and has taken too much + * all time to complete this iteration of the period. + */ + RATE_MONOTONIC_EXPIRED, } rtems_rate_monotonic_period_states; /** @@ -102,15 +132,23 @@ typedef enum { * The following defines the statistics kept on each period instance. */ typedef struct { + /** This field contains the number of periods executed. */ uint32_t count; + /** This field contains the number of periods missed. */ uint32_t missed_count; + /** This field contains the least amount of CPU time used in a period. */ rtems_thread_cpu_usage_t min_cpu_time; + /** This field contains the highest amount of CPU time used in a period. */ rtems_thread_cpu_usage_t max_cpu_time; + /** This field contains the total amount of wall time used in a period. */ rtems_thread_cpu_usage_t total_cpu_time; + /** This field contains the least amount of wall time used in a period. */ rtems_rate_monotonic_period_time_t min_wall_time; + /** This field contains the highest amount of wall time used in a period. */ rtems_rate_monotonic_period_time_t max_wall_time; + /** This field contains the total amount of CPU time used in a period. */ rtems_rate_monotonic_period_time_t total_wall_time; } rtems_rate_monotonic_period_statistics; @@ -118,9 +156,24 @@ typedef struct { * The following defines the period status structure. */ typedef struct { + /** This is the Id of the thread using this period. */ Objects_Id owner; + + /** This is the current state of this period. */ rtems_rate_monotonic_period_states state; + + /** + * This is the length of wall time that has passed since this period + * was last initiated. If the period is expired or has not been initiated, + * then this field has no meaning. + */ rtems_rate_monotonic_period_time_t since_last_period; + + /** + * This is the amount of CPU time that has been used since this period + * was last initiated. If the period is expired or has not been initiated, + * then this field has no meaning. + */ rtems_thread_cpu_usage_t executed_since_last_period; } rtems_rate_monotonic_period_status; @@ -129,13 +182,43 @@ typedef struct { * each period. */ typedef struct { + /** This field is the object management portion of a Period instance. */ Objects_Control Object; + + /** This is the timer used to provide the unblocking mechanism. */ Watchdog_Control Timer; + + /** This field indicates the current state of the period. */ rtems_rate_monotonic_period_states state; + + /** + * This field contains the total CPU usage used while executing + * the body of the loop that is executed each period. + */ rtems_thread_cpu_usage_t owner_executed_at_period; + + /** + * This field contains the total wall timer that passed while + * executing the body of the loop that is executed each period. + */ rtems_rate_monotonic_period_time_t time_at_period; + + /** + * This field contains the length of the next period to be + * executed. + */ uint32_t next_length; + + /** + * This field contains a pointer to the TCB for the thread + * which owns and uses this period instance. + */ Thread_Control *owner; + + /** + * This field contains the statistics which are maintained + * on each period. + */ rtems_rate_monotonic_period_statistics Statistics; } Rate_monotonic_Control; @@ -148,7 +231,7 @@ typedef struct { RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information; /** - * _Rate_monotonic_Manager_initialization + * @brief Rate Monotonic Manager Initialization * * This routine performs the initialization necessary for this manager. */ diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h index 74d66ea334..7f071bfcb5 100644 --- a/cpukit/rtems/include/rtems/rtems/region.h +++ b/cpukit/rtems/include/rtems/rtems/region.h @@ -66,14 +66,53 @@ extern "C" { */ typedef struct { + /** + * This field is the object management portion of a Region instance. + */ Objects_Control Object; - Thread_queue_Control Wait_queue; /* waiting threads */ - void *starting_address; /* physical start addr */ - uint32_t length; /* physical length(bytes) */ - uint32_t page_size; /* in bytes */ - uint32_t maximum_segment_size; /* in bytes */ + + /** + * This is the set of threads blocked waiting on memory. + */ + Thread_queue_Control Wait_queue; + + /** + * This is the physical starting address of the Region area. + */ + void *starting_address; + + /** + * This is the physical length (in bytes) of the Region memory. + */ + uint32_t length; + + /** + * This is the physical page size (in bytes) of each allocated segment. + */ + uint32_t page_size; + + /** + * This is the maximum segment size (in bytes) that can ever be allocated + * from this Region. It is calculated at creation time. + */ + uint32_t maximum_segment_size; + + /** + * This is the Classic API attribute provided to the create directive. + * It is translated into behavioral attributes on the SuperCore Heap + * instance. + */ rtems_attribute attribute_set; - uint32_t number_of_used_blocks; /* blocks allocated */ + + /** + * This is the number of blocks currently allocated from this Region. + */ + uint32_t number_of_used_blocks; + + /** + * This is the Heap instance which implements the core functionality + * of a Region instance. + */ Heap_Control Memory; } Region_Control; diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h index 656717d653..f58ef5ec36 100644 --- a/cpukit/rtems/include/rtems/rtems/sem.h +++ b/cpukit/rtems/include/rtems/rtems/sem.h @@ -53,7 +53,8 @@ extern "C" { /** * @defgroup ClassicSem Classic API Semaphore * - * This encapsulates functionality which XXX + * This encapsulates functionality related to the Classic API + * Semaphore Manager. */ /**@{*/ @@ -61,10 +62,36 @@ extern "C" { * The following defines the control block used to manage each semaphore. */ typedef struct { + /** This field is the object management portion of a Semaphore instance. */ Objects_Control Object; + + /** + * This is the Classic API attribute provided to the create directive. + * It is translated into behavioral attributes on the SuperCore Semaphore + * or Mutex instance. + */ rtems_attribute attribute_set; + + /** + * This contains the memory associated with the SuperCore Semaphore or + * Mutex instance that provides the primary functionality of each + * Classic API Semaphore instance. The structure used is dependent + * on the attributes specified by the user on the create directive. + * + * @note Only one of these has meaning in a particular Classic API + * Semaphore instance. + */ union { + /** + * This is the SuperCore Mutex instance associated with this Classic + * API Semaphore instance. + */ CORE_mutex_Control mutex; + + /** + * This is the SuperCore Semaphore instance associated with this Classic + * API Semaphore instance. + */ CORE_semaphore_Control semaphore; } Core_control; } Semaphore_Control; diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h index f2227957bb..f09b0eb329 100644 --- a/cpukit/rtems/include/rtems/rtems/tasks.h +++ b/cpukit/rtems/include/rtems/rtems/tasks.h @@ -182,13 +182,20 @@ typedef rtems_task ( *rtems_task_entry )( * initialization time. */ typedef struct { - rtems_name name; /* task name */ - size_t stack_size; /* task stack size */ - rtems_task_priority initial_priority; /* task priority */ - rtems_attribute attribute_set; /* task attributes */ - rtems_task_entry entry_point; /* task entry point */ - rtems_mode mode_set; /* task initial mode */ - rtems_task_argument argument; /* task argument */ + /** This is the Initialization Task's name. */ + rtems_name name; + /** This is the Initialization Task's stack size. */ + size_t stack_size; + /** This is the Initialization Task's priority. */ + rtems_task_priority initial_priority; + /** This is the Initialization Task's attributes. */ + rtems_attribute attribute_set; + /** This is the Initialization Task's entry point. */ + rtems_task_entry entry_point; + /** This is the Initialization Task's initial mode. */ + rtems_mode mode_set; + /** This is the Initialization Task's argument. */ + rtems_task_argument argument; } rtems_initialization_tasks_table; /** @@ -196,9 +203,13 @@ typedef struct { * the RTEMS API to function correctly. */ typedef struct { + /** This field contains the notepads for this task. */ uint32_t Notepads[ RTEMS_NUMBER_NOTEPADS ]; + /** This field contains the pending events for this task. */ rtems_event_set pending_events; + /** This field contains the event wait condition for this task. */ rtems_event_set event_condition; + /** This field contains the Classic API Signal information for this task. */ ASR_Information Signal; } RTEMS_API_Control; diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h index d474660af9..a7d6029620 100644 --- a/cpukit/rtems/include/rtems/rtems/timer.h +++ b/cpukit/rtems/include/rtems/rtems/timer.h @@ -67,10 +67,33 @@ extern "C" { * may belong. */ typedef enum { + /** + * This value indicates the timer is currently in use as an interval + * timer which will fire in the clock tick ISR. + */ TIMER_INTERVAL, + + /** + * This value indicates the timer is currently in use as an interval + * timer which will fire in the timer server task. + */ TIMER_INTERVAL_ON_TASK, + + /** + * This value indicates the timer is currently in use as an time of day + * timer which will fire in the clock tick ISR. + */ TIMER_TIME_OF_DAY, + + /** + * This value indicates the timer is currently in use as an time of day + * timer which will fire in the timer server task. + */ TIMER_TIME_OF_DAY_ON_TASK, + + /** + * This value indicates the timer is currently not in use. + */ TIMER_DORMANT } Timer_Classes; @@ -79,6 +102,11 @@ typedef enum { */ typedef void rtems_timer_service_routine; +/** + * This type defines the type used to manage and indirectly invoke + * Timer Service Routines (TSRs). This defines the prototype and interface + * for a function which is to be used as a TSR. + */ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtems_id, void * @@ -98,17 +126,29 @@ RTEMS_TIMER_EXTERN Objects_Information _Timer_Information; RTEMS_TIMER_EXTERN Thread_Control *_Timer_Server; /** - * The following chains contain the list of interval timers that are + * This chain contains the list of interval timers that are * executed in the context of the Timer Server. * - * NOTE: These are extern'ed because they do not have to be in the - * minimum footprint. They are only really required when + * @note This is extern'ed because they do not have to be in the + * minimum footprint. It is only really required when * task-based timers are used. Since task-based timers can - * not be started until the server is initiated, these structures - * do not have to be initialized until then. They are declared + * not be started until the server is initiated, this structure + * does not have to be initialized until then. This is declared * in the same file as _Timer_Server_body. */ extern Chain_Control _Timer_Ticks_chain; + +/** + * This chain contains the list of time of day timers that are + * executed in the context of the Timer Server. + * + * @note This is extern'ed because they do not have to be in the + * minimum footprint. It is only really required when + * task-based timers are used. Since task-based timers can + * not be started until the server is initiated, this structure + * does not have to be initialized until then. This is declared + * in the same file as _Timer_Server_body. + */ extern Chain_Control _Timer_Seconds_chain; /** @@ -116,8 +156,11 @@ extern Chain_Control _Timer_Seconds_chain; * each timer. */ typedef struct { + /** This field is the object management portion of a Timer instance. */ Objects_Control Object; + /** This field is the Watchdog instance which will be the scheduled. */ Watchdog_Control Ticker; + /** This field indicates what type of timer this currently is. */ Timer_Classes the_class; } Timer_Control; @@ -288,9 +331,13 @@ rtems_status_code rtems_timer_initiate_server( * service. */ typedef struct { + /** This indicates the current type of the timer. */ Timer_Classes the_class; + /** This indicates the initial requested interval. */ Watchdog_Interval initial; + /** This indicates the time the timer was initially scheduled. */ Watchdog_Interval start_time; + /** This indicates the time the timer is scheduled to fire. */ Watchdog_Interval stop_time; } rtems_timer_information; @@ -340,6 +387,10 @@ void _Timer_Server_process_ticks_chain(void); */ void _Timer_Server_process_seconds_chain(void); +/** + * This method resets a timer and places it on the Ticks chain. It + * is assumed that the timer has already been canceled. + */ #define _Timer_Server_reset_ticks_timer() \ do { \ if ( !_Chain_Is_empty( &_Timer_Ticks_chain ) ) { \ @@ -348,6 +399,10 @@ void _Timer_Server_process_seconds_chain(void); } \ } while (0) +/** + * This method resets a timer and places it on the Seconds chain. It + * is assumed that the timer has already been canceled. + */ #define _Timer_Server_reset_seconds_timer() \ do { \ if ( !_Chain_Is_empty( &_Timer_Seconds_chain ) ) { \ diff --git a/cpukit/rtems/include/rtems/rtems/types.h b/cpukit/rtems/include/rtems/rtems/types.h index 7b5eb9e213..0eb53c30bb 100644 --- a/cpukit/rtems/include/rtems/rtems/types.h +++ b/cpukit/rtems/include/rtems/rtems/types.h @@ -44,28 +44,56 @@ extern "C" { #include #endif -typedef single_precision rtems_single; /* single precision float */ -typedef double_precision rtems_double; /* double precision float */ +/** This type defines a single precision float. */ +typedef single_precision rtems_single; +/** This type defines a double precision float. */ +typedef double_precision rtems_double; + +/** This type defines the RTEMS boolean type . */ typedef boolean rtems_boolean; +/** This type defines is for Classic API object names. */ 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. + */ typedef Objects_Id rtems_id; +/** + * This defines a value that is an invalid object Id. + */ #define RTEMS_ID_NONE OBJECTS_ID_NONE +/** + * This type is the public name for task context area. + */ typedef Context_Control rtems_context; + +/** + * This type is the public name for task floating point context area. + */ typedef Context_Control_fp rtems_context_fp; + +/** + * This type is the public name for the architecture specific + * stack frame built as part of vectoring an interrupt. + */ typedef CPU_Interrupt_frame rtems_interrupt_frame; /** - * Region information block + * This type defines the public name for the information + * structure returned by the Heap Handler via the Region + * Manager. */ typedef Heap_Information_block region_information_block; /** - * Time related + * This type defines the public name for the type that is + * used to manage intervals specified by clock ticks. */ typedef Watchdog_Interval rtems_interval; @@ -73,7 +101,7 @@ 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 style time/date. + * @note This is an RTEID (a.k.a. Classic API) style time/date. */ typedef struct { /** This field is the year, A.D. */ @@ -93,7 +121,7 @@ typedef struct { } rtems_time_of_day; /** - * Define the type for an RTEMS API task mode. + * This defines the public name for an RTEMS API task mode type. */ typedef Modes_Control rtems_mode; @@ -101,18 +129,61 @@ typedef Modes_Control rtems_mode; * MPCI related entries */ #if defined(RTEMS_MULTIPROCESSING) +/** + * This defines the public name for the 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. + */ 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. + */ 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. + */ 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. + */ 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. + */ 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. + */ typedef MPCI_receive_entry rtems_mpci_receive_packet_entry; -typedef MPCI_Entry rtems_mpci_entry; +/** + * This defines the public name for the 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. + */ +typedef MPCI_Control rtems_mpci_table; -typedef MPCI_Control rtems_mpci_table; #endif #ifdef __cplusplus -- cgit v1.2.3