From 2ad3d0245928ecbff016dd02efb10ba142c75843 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 28 Apr 2008 18:21:01 +0000 Subject: 2008-04-28 Joel Sherrill * rtems/include/rtems.h, rtems/include/rtems/rtems/ratemon.h, rtems/include/rtems/rtems/status.h, rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h, rtems/inline/rtems/rtems/sem.inl: More Doxygen warnings removed. --- cpukit/ChangeLog | 7 + cpukit/rtems/include/rtems.h | 62 ++++++++- cpukit/rtems/include/rtems/rtems/ratemon.h | 18 ++- cpukit/rtems/include/rtems/rtems/status.h | 203 +++++++++++++++++++++++------ cpukit/rtems/include/rtems/rtems/tasks.h | 26 +++- cpukit/rtems/include/rtems/rtems/timer.h | 2 + cpukit/rtems/inline/rtems/rtems/sem.inl | 11 ++ 7 files changed, 281 insertions(+), 48 deletions(-) diff --git a/cpukit/ChangeLog b/cpukit/ChangeLog index 774972b377..92279765eb 100644 --- a/cpukit/ChangeLog +++ b/cpukit/ChangeLog @@ -1,3 +1,10 @@ +2008-04-28 Joel Sherrill + + * rtems/include/rtems.h, rtems/include/rtems/rtems/ratemon.h, + rtems/include/rtems/rtems/status.h, + rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h, + rtems/inline/rtems/rtems/sem.inl: More Doxygen warnings removed. + 2008-04-28 Daron Chabot * posix/src/keycreate.c, posix/src/pthreadequal.c, diff --git a/cpukit/rtems/include/rtems.h b/cpukit/rtems/include/rtems.h index e4441ec069..49cf5f76e0 100644 --- a/cpukit/rtems/include/rtems.h +++ b/cpukit/rtems/include/rtems.h @@ -31,7 +31,11 @@ extern "C" { #endif -/* +#if (!defined(__RTEMS_VIOLATE_KERNEL_VISIBILITY__)) && \ + (!defined(__RTEMS_INSIDE__)) +/** + * @brief Compiling RTEMS Application Macro + * * Unless told otherwise, the RTEMS include files will hide some stuff * from normal application code. Defining this crosses a boundary which * is undesirable since it means your application is using RTEMS features @@ -39,7 +43,6 @@ extern "C" { * Define this at your own risk. */ -#if (!defined(__RTEMS_VIOLATE_KERNEL_VISIBILITY__)) && (!defined(__RTEMS_INSIDE__)) #define __RTEMS_APPLICATION__ #endif @@ -76,23 +79,72 @@ extern "C" { #include #include +/** + * This constant indicates whether this processor variant has + * hardware floating point support. + */ #define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP -/** +/* * The following define the constants which may be used in name searches. */ + +/** + * This constant indicates that the search is across all nodes. + */ #define RTEMS_SEARCH_ALL_NODES OBJECTS_SEARCH_ALL_NODES + +/** + * This constant indicates that the search is across all nodes + * except the one the call is made from. + */ #define RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES + +/** + * This constant indicates that the search is to be restricted + * to the local node. + */ #define RTEMS_SEARCH_LOCAL_NODE OBJECTS_SEARCH_LOCAL_NODE -#define RTEMS_WHO_AM_I OBJECTS_WHO_AM_I /** + * This constant indicates that the caller wants to obtain the + * name of the currently executing thread. + * + * @note This constant is only meaningful when obtaining the name + * of a task. + */ +#define RTEMS_WHO_AM_I OBJECTS_WHO_AM_I + +/* * Parameters and return id's for _Objects_Get_next */ + +/** + * This constant is the lowest valid valid for the index portion + * of an object Id. + */ #define RTEMS_OBJECT_ID_INITIAL_INDEX OBJECTS_ID_INITIAL_INDEX + +/** + * This constant is the maximum valid valid for the index portion + * of an object Id. + */ #define RTEMS_OBJECT_ID_FINAL_INDEX OBJECTS_ID_FINAL_INDEX -#define RTEMS_OBJECT_ID_INITIAL(api, class, node) OBJECTS_ID_INITIAL(api, class, node) +/** + * This method returns the Id of the object with the lowest + * valid index valud. + * + * @param[in] _api is the API of the object + * @param[in] _class is the Object Class of the object + * @param[in] _node is the node where the object resides + */ +#define RTEMS_OBJECT_ID_INITIAL(_api, _class, _node) \ + OBJECTS_ID_INITIAL(_api, _class, _node) + +/** + * This constant is the maximum valid object Id. + */ #define RTEMS_OBJECT_ID_FINAL OBJECTS_ID_FINAL /** diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h index 56c5f7d6a3..038c26e31e 100644 --- a/cpukit/rtems/include/rtems/rtems/ratemon.h +++ b/cpukit/rtems/include/rtems/rtems/ratemon.h @@ -158,7 +158,13 @@ typedef struct { Thread_Control *owner; rtems_rate_monotonic_period_statistics Statistics; } Rate_monotonic_Control; - + +/** + * @brief Rate Monotonic Period Class Management Structure + * + * This instance of Objects_Information is used to manage the + * set of rate monotonic period instances. + */ RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information; /** @@ -320,6 +326,11 @@ void _Rate_monotonic_Timeout( #define _Rate_monotonic_Reset_wall_time_statistics( _the_period ) #endif +/** + * @brief Rate_monotonic_Reset_cpu_use_statistics + * + * This helper method resets the period CPU usage statistics structure. + */ #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period ) \ do { \ @@ -331,6 +342,11 @@ void _Rate_monotonic_Timeout( #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period ) #endif +/** + * @brief Rate_monotonic_Reset_statistics + * + * This helper method resets the period wall time statistics structure. + */ #define _Rate_monotonic_Reset_statistics( _the_period ) \ do { \ memset( \ diff --git a/cpukit/rtems/include/rtems/rtems/status.h b/cpukit/rtems/include/rtems/rtems/status.h index 5a50941136..d32b433842 100644 --- a/cpukit/rtems/include/rtems/rtems/status.h +++ b/cpukit/rtems/include/rtems/rtems/status.h @@ -29,55 +29,178 @@ extern "C" { #endif -/* types */ - -/* enumerated constants */ - +/** + * @brief Classic API Status + * + * This enumerates the possible status values returned b + * Classic API directives. + */ typedef enum { - RTEMS_SUCCESSFUL = 0, /* successful completion */ - RTEMS_TASK_EXITTED = 1, /* returned from a thread */ - RTEMS_MP_NOT_CONFIGURED = 2, /* multiprocessing not configured */ - RTEMS_INVALID_NAME = 3, /* invalid object name */ - RTEMS_INVALID_ID = 4, /* invalid object id */ - RTEMS_TOO_MANY = 5, /* too many */ - RTEMS_TIMEOUT = 6, /* timed out waiting */ - RTEMS_OBJECT_WAS_DELETED = 7, /* object deleted while waiting */ - RTEMS_INVALID_SIZE = 8, /* specified size was invalid */ - RTEMS_INVALID_ADDRESS = 9, /* address specified is invalid */ - RTEMS_INVALID_NUMBER = 10, /* number was invalid */ - RTEMS_NOT_DEFINED = 11, /* item has not been initialized */ - RTEMS_RESOURCE_IN_USE = 12, /* resources still outstanding */ - RTEMS_UNSATISFIED = 13, /* request not satisfied */ - RTEMS_INCORRECT_STATE = 14, /* thread is in wrong state */ - RTEMS_ALREADY_SUSPENDED = 15, /* thread already in state */ - RTEMS_ILLEGAL_ON_SELF = 16, /* illegal on calling thread */ - RTEMS_ILLEGAL_ON_REMOTE_OBJECT = 17, /* illegal for remote object */ - RTEMS_CALLED_FROM_ISR = 18, /* called from wrong environment */ - RTEMS_INVALID_PRIORITY = 19, /* invalid thread priority */ - RTEMS_INVALID_CLOCK = 20, /* invalid date/time */ - RTEMS_INVALID_NODE = 21, /* invalid node id */ - RTEMS_NOT_CONFIGURED = 22, /* directive not configured */ - RTEMS_NOT_OWNER_OF_RESOURCE = 23, /* not owner of resource */ - RTEMS_NOT_IMPLEMENTED = 24, /* directive not implemented */ - RTEMS_INTERNAL_ERROR = 25, /* RTEMS inconsistency detected */ - RTEMS_NO_MEMORY = 26, /* could not get enough memory */ - RTEMS_IO_ERROR = 27, /* driver IO error */ - RTEMS_PROXY_BLOCKING = 28 /* internal error only */ + /** + * This is the status to indicate successful completion. + */ + RTEMS_SUCCESSFUL = 0, + /** + * This is the status to indicate that a thread exited. + */ + RTEMS_TASK_EXITTED = 1, + /** + * This is the status to indicate multiprocessing is not configured. + */ + RTEMS_MP_NOT_CONFIGURED = 2, + /** + * This is the status to indicate that the object name was invalid. + */ + RTEMS_INVALID_NAME = 3, + /** + * This is the status to indicate that the object Id was invalid. + */ + RTEMS_INVALID_ID = 4, + /** + * This is the status to indicate you have attempted to create too many + * instances of a particular object class. + */ + RTEMS_TOO_MANY = 5, + /** + * This is the status to indicate that a blocking directive timed out. + */ + RTEMS_TIMEOUT = 6, + /** + * This is the status to indicate the the object was deleted + * while the task was blocked waiting. + */ + RTEMS_OBJECT_WAS_DELETED = 7, + /** + * This is the status to indicate that the specified size was invalid. + */ + RTEMS_INVALID_SIZE = 8, + /** + * This is the status to indicate that the specified address is invalid. + */ + RTEMS_INVALID_ADDRESS = 9, + /** + * This is the status to indicate that the specified number was invalid. + */ + RTEMS_INVALID_NUMBER = 10, + /** + * This is the status to indicate that the item has not been initialized. + */ + RTEMS_NOT_DEFINED = 11, + /** + * This is the status to indicate that the object still has + * resources in use. + */ + RTEMS_RESOURCE_IN_USE = 12, + /** + * This is the status to indicate that the request was not satisfied. + */ + RTEMS_UNSATISFIED = 13, + /** + * This is the status to indicate that a thread is in wrong state + * was in the wrong execution state for the requested operation. + */ + RTEMS_INCORRECT_STATE = 14, + /** + * This is the status to indicate thread was already suspended. + */ + RTEMS_ALREADY_SUSPENDED = 15, + /** + * This is the status to indicate that the operation is illegal + * on calling thread. + */ + RTEMS_ILLEGAL_ON_SELF = 16, + /** + * This is the status to indicate illegal for remote object. + */ + RTEMS_ILLEGAL_ON_REMOTE_OBJECT = 17, + /** + * This is the status to indicate that the operation should not be + * called from from this excecution environment. + */ + RTEMS_CALLED_FROM_ISR = 18, + /** + * This is the status to indicate that an invalid thread priority + * was provided. + */ + RTEMS_INVALID_PRIORITY = 19, + /** + * This is the status to indicate that the specified date/time was invalid. + */ + RTEMS_INVALID_CLOCK = 20, + /** + * This is the status to indicate that the specified node Id was invalid. + */ + RTEMS_INVALID_NODE = 21, + /** + * This is the status to indicate that the directive was not configured. + */ + RTEMS_NOT_CONFIGURED = 22, + /** + * This is the status to indicate that the caller is not the + * owner of the resource. + */ + RTEMS_NOT_OWNER_OF_RESOURCE = 23, + /** + * This is the status to indicate the the directive or requested + * portion of the directive is not implemented. This is a hint + * that you have stumbled across an opportunity to submit code + * to the RTEMS Project. + */ + RTEMS_NOT_IMPLEMENTED = 24, + /** + * This is the status to indicate that an internal RTEMS inconsistency + * was detected. + */ + RTEMS_INTERNAL_ERROR = 25, + /** + * This is the status to indicate that the directive attempted to allocate + * memory but was unable to do so. + */ + RTEMS_NO_MEMORY = 26, + /** + * This is the status to indicate an driver IO error. + */ + RTEMS_IO_ERROR = 27, + /** + * This is the status is used internally to RTEMS when performing + * operations on behalf of remote tasks. This is referred to as + * proxying operations and this status indicates that the operation + * could not be completed immediately and the "proxy is blocking." + * + * @note This status will @b NOT be returned to the user. + */ + RTEMS_PROXY_BLOCKING = 28, } rtems_status_code; +/** + * This is the lowest valid value for a Classic API status code. + */ #define RTEMS_STATUS_CODES_FIRST RTEMS_SUCCESSFUL -#define RTEMS_STATUS_CODES_LAST RTEMS_PROXY_BLOCKING -extern rtems_status_code _Status_Object_name_errors_to_status[]; +/** + * This is the highest valid value for a Classic API status code. + */ +#define RTEMS_STATUS_CODES_LAST RTEMS_PROXY_BLOCKING +/** + * This array is used to map SuperCore Object Handler return + * codes to Classic API status codes. + */ #ifdef RTEMS_API_INIT rtems_status_code _Status_Object_name_errors_to_status[] = { - RTEMS_SUCCESSFUL, /* OBJECTS_SUCCESSFUL */ - RTEMS_INVALID_NAME, /* OBJECTS_INVALID_NAME */ - RTEMS_INVALID_ADDRESS, /* OBJECTS_INVALID_ADDRESS */ - RTEMS_INVALID_ID, /* OBJECTS_INVALID_ID */ - RTEMS_INVALID_NODE /* OBJECTS_INVALID_NODE */ + /** This maps OBJECTS_SUCCESSFUL to RTEMS_SUCCESSFUL. */ + RTEMS_SUCCESSFUL, + /** This maps OBJECTS_INVALID_NAME to RTEMS_INVALID_NAME. */ + RTEMS_INVALID_NAME, + /** This maps OBJECTS_INVALID_ADDRESS to RTEMS_INVALID_NAME. */ + RTEMS_INVALID_ADDRESS, + /** This maps OBJECTS_INVALID_ID to RTEMS_INVALID_ADDRESS. */ + RTEMS_INVALID_ID, + /** This maps OBJECTS_INVALID_NODE to RTEMS_INVALID_NODE. */ + RTEMS_INVALID_NODE }; +#else +extern rtems_status_code _Status_Object_name_errors_to_status[]; #endif /* diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h index d10ac03853..f2227957bb 100644 --- a/cpukit/rtems/include/rtems/rtems/tasks.h +++ b/cpukit/rtems/include/rtems/rtems/tasks.h @@ -81,9 +81,30 @@ extern "C" { */ typedef Priority_Control rtems_task_priority; +/** + * This is the constant used with the rtems_task_set_priority + * directive to indicate that the caller wants to obtain its + * current priority rather than set it as the name of the + * directive indicates. + */ #define RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY +/** + * This constant is the least valid value for a Classic API + * task priority. + */ #define RTEMS_MINIMUM_PRIORITY (PRIORITY_MINIMUM + 1) + +/** + * This constant is the maximum valid value for a Classic API + * task priority. + * + * @note This is actually the priority of the IDLE thread so + * using this priority will result in having a task + * which never executes. This could be useful if you + * want to ensure that a task does not executes during + * certain operations such as a system mode change. + */ #define RTEMS_MAXIMUM_PRIORITY PRIORITY_MAXIMUM /** @@ -129,6 +150,7 @@ typedef Priority_Control rtems_task_priority; /** This is used to indicate the highest numbered notepad. */ #define RTEMS_NOTEPAD_LAST RTEMS_NOTEPAD_15 +/** This is used to indicate the number of notepads available. */ #define RTEMS_NUMBER_NOTEPADS (RTEMS_NOTEPAD_LAST+1) /** @@ -180,8 +202,8 @@ typedef struct { ASR_Information Signal; } RTEMS_API_Control; -/* - * The following defines the information control block used to +/** + * The following instantiates the information control block used to * manage this class of objects. */ RTEMS_TASKS_EXTERN Objects_Information _RTEMS_tasks_Information; diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h index 1fbe458da9..e1e0b7c0bc 100644 --- a/cpukit/rtems/include/rtems/rtems/timer.h +++ b/cpukit/rtems/include/rtems/rtems/timer.h @@ -312,6 +312,8 @@ rtems_status_code rtems_timer_get_information( */ extern Watchdog_Control _Timer_Seconds_timer; +/** + * This method is used to temporaril #define _Timer_Server_stop_ticks_timer() \ _Watchdog_Remove( &_Timer_Server->Timer ) diff --git a/cpukit/rtems/inline/rtems/rtems/sem.inl b/cpukit/rtems/inline/rtems/rtems/sem.inl index 01058d2257..566c823f81 100644 --- a/cpukit/rtems/inline/rtems/rtems/sem.inl +++ b/cpukit/rtems/inline/rtems/rtems/sem.inl @@ -67,6 +67,17 @@ RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get ( _Objects_Get( &_Semaphore_Information, id, location ); } +/** + * @brief Semaphore_Get (Interrupts disabled) + * + * This function maps semaphore IDs to semaphore control blocks. + * If ID corresponds to a local semaphore, then it returns + * the_semaphore control pointer which maps to ID and location + * is set to OBJECTS_LOCAL. if the semaphore ID is global and + * resides on a remote node, then location is set to OBJECTS_REMOTE, + * and the_semaphore is undefined. Otherwise, location is set + * to OBJECTS_ERROR and the_semaphore is undefined. + */ RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get_interrupt_disable ( Objects_Id id, Objects_Locations *location, -- cgit v1.2.3