From 742a2ba3b5b10bfc678fc5dba0ab8a2b73acc751 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 10 Nov 2011 14:09:08 +0000 Subject: 2011-11-10 Sebastian Huber * rtems/include/rtems/rtems/event.h, rtems/include/rtems/rtems/eventset.h, rtems/inline/rtems/rtems/eventset.inl: Documentation. --- cpukit/rtems/include/rtems/rtems/event.h | 193 +++++++++++++++++++++++----- cpukit/rtems/include/rtems/rtems/eventset.h | 110 ++++++++-------- 2 files changed, 218 insertions(+), 85 deletions(-) (limited to 'cpukit/rtems/include/rtems') diff --git a/cpukit/rtems/include/rtems/rtems/event.h b/cpukit/rtems/include/rtems/rtems/event.h index 05f66d64cd..d45fc0cabd 100644 --- a/cpukit/rtems/include/rtems/rtems/event.h +++ b/cpukit/rtems/include/rtems/rtems/event.h @@ -53,49 +53,151 @@ extern "C" { * * @ingroup ClassicRTEMS * - * This encapsulates functionality which XXX - */ -/**@{*/ - -/** - * This constant is passed as the event_in to the - * rtems_event_receive directive to determine which events are pending. - */ -#define EVENT_CURRENT 0 - -/** - * @brief Event_Manager_initialization + * @brief The event manager provides a high performance method of intertask + * communication and synchronization. * - * This routine performs the initialization necessary for this manager. + * An event flag is used by a task (or ISR) to inform another task of the + * occurrence of a significant situation. Thirty-two event flags are + * associated with each task. A collection of one or more event flags is + * referred to as an event set. The data type rtems_event_set is used to + * manage event sets. + * + * The application developer should remember the following key characteristics + * of event operations when utilizing the event manager: + * + * - Events provide a simple synchronization facility. + * - Events are aimed at tasks. + * - Tasks can wait on more than one event simultaneously. + * - Events are independent of one another. + * - Events do not hold or transport data. + * - Events are not queued. In other words, if an event is sent more than once + * to a task before being received, the second and subsequent send + * operations to that same task have no effect. + * + * An event set is posted when it is directed (or sent) to a task. A pending + * event is an event that has been posted but not received. An event condition + * is used to specify the event set which the task desires to receive and the + * algorithm which will be used to determine when the request is satisfied. An + * event condition is satisfied based upon one of two algorithms which are + * selected by the user. The @ref RTEMS_EVENT_ANY algorithm states that an + * event condition is satisfied when at least a single requested event is + * posted. The @ref RTEMS_EVENT_ALL algorithm states that an event condition + * is satisfied when every requested event is posted. + * + * An event set or condition is built by a bitwise or of the desired events. + * The set of valid events is @ref RTEMS_EVENT_0 through @ref RTEMS_EVENT_31. + * If an event is not explicitly specified in the set or condition, then it is + * not present. Events are specifically designed to be mutually exclusive, + * therefore bitwise or and addition operations are equivalent as long as each + * event appears exactly once in the event set list. + * + * For example, when sending the event set consisting of @ref RTEMS_EVENT_6, + * @ref RTEMS_EVENT_15, and @ref RTEMS_EVENT_31, the event parameter to the + * rtems_event_send() directive should be @ref RTEMS_EVENT_6 | + * @ref RTEMS_EVENT_15 | @ref RTEMS_EVENT_31. + * + * @{ */ -void _Event_Manager_initialization( void ); /** - * @brief rtems_event_send + * @brief Sends an event set to the target task. + * + * This directive sends an event set @a event_in to the task specified by + * @a target_task_id. + * + * Based upon the state of the target task, one of the following situations + * applies. The target task is + * - blocked waiting for events. + * If the waiting task's input event condition is + * - satisfied, then the task is made ready for execution. + * - not satisfied, then the event set is posted but left pending and the + * task remains blocked. + * - not waiting for events. + * - The event set is posted and left pending. + * + * Identical events sent to a task are not queued. In other words, the second, + * and subsequent, posting of an event to a task before it can perform an + * rtems_event_receive() has no effect. * - * This routine implements the rtems_event_send directive. It sends - * event_in to the task specified by ID. If the task is blocked - * waiting to receive events and the posting of event_in satisfies - * the task's event condition, then it is unblocked. + * The calling task will be preempted if it has preemption enabled and a + * higher priority task is unblocked as the result of this directive. + * + * Sending an event set to a global task which does not reside on the local + * node will generate a request telling the remote node to send the event set + * to the appropriate task. + * + * @param[in] target_task_id Identifier of the target task. Specifying + * @ref RTEMS_SELF results in the event set being sent to the calling task. + * @param[in] event_in Event set sent to the target task. + * + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_INVALID_ID Invalid task identifier. */ rtems_status_code rtems_event_send ( - rtems_id id, + rtems_id target_task_id, rtems_event_set event_in ); /** - * @brief rtems_event_receive - * - * This routine implements the rtems_event_receive directive. This - * directive is invoked when the calling task wishes to receive - * the event_in event condition. One of the fields in the option_set - * parameter determines whether the receive request is satisfied if - * any or all of the events are pending. If the event condition - * is not satisfied immediately, then the task may block with an - * optional timeout of TICKS clock ticks or return immediately. - * This determination is based on another field in the option_set - * parameter. This directive returns the events received in the - * event_out parameter. + * @brief Receives pending events. + * + * This directive attempts to receive the event condition specified in + * @a event_in. If @a event_in is set to @ref RTEMS_PENDING_EVENTS, then the + * current pending events are returned in @a event_out and left pending. The + * @aref RTEMS_WAIT and @aref RTEMS_NO_WAIT options in the @a option_set + * parameter are used to specify whether or not the task is willing to wait + * for the event condition to be satisfied. The @ref RTEMS_EVENT_ANY and @ref + * RTEMS_EVENT_ALL are used in the @a option_set parameter to specify whether + * at least a single event or the complete event set is necessary to satisfy + * the event condition. The @a event_out parameter is returned to the calling + * task with the value that corresponds to the events in @a event_in that were + * satisfied. + * + * A task can determine the pending event set by using a value of + * @ref RTEMS_PENDING_EVENTS for the input event set @a event_in. The pending + * events are returned to the calling task but the event set is left + * unaltered. + * + * A task can receive all of the currently pending events by using the a value + * of @ref RTEMS_ALL_EVENTS for the input event set @a event_in and + * @ref RTEMS_NO_WAIT | @ref RTEMS_EVENT_ANY for the option set @a option_set. + * The pending events are returned to the calling task and the event set is + * cleared. If no events are pending then the @ref RTEMS_UNSATISFIED status + * code will be returned. + * + * If pending events satisfy the event condition, then @a event_out is set to + * the satisfied events and the pending events in the event condition are + * cleared. If the event condition is not satisfied and @ref RTEMS_NO_WAIT is + * specified, then @a event_out is set to the currently satisfied events. If + * the calling task chooses to wait, then it will block waiting for the event + * condition. + * + * If the calling task must wait for the event condition to be satisfied, then + * the timeout parameter is used to specify the maximum interval to wait. If + * it is set to @ref RTEMS_NO_TIMEOUT, then the calling task will wait forever. + * + * This directive only affects the events specified in @a event_in. Any + * pending events that do not correspond to any of the events specified in + * @a event_in will be left pending. + * + * A clock tick is required to support the wait with time out functionality of + * this directive. + * + * @param[in] event_in Set of requested events (input events). + * @param[in] option_set Use a bitwise or of the following options + * - @ref RTEMS_WAIT - task will wait for event (default), + * - @ref RTEMS_NO_WAIT - task should not wait, + * - @ref RTEMS_EVENT_ALL - return after all events (default), and + * - @ref RTEMS_EVENT_ANY - return after any events. + * @param[in] ticks Time out in ticks. Use @ref RTEMS_NO_TIMEOUT to wait + * without a time out (potentially forever). + * @param[out] event_out Set of received events (output events). + * + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_UNSATISFIED Input events not satisfied (only with the + * @ref RTEMS_NO_WAIT option). + * @retval RTEMS_INVALID_ADDRESS The @a event_out pointer is @c NULL. + * @retval RTEMS_TIMEOUT Timed out waiting for events. */ rtems_status_code rtems_event_receive ( rtems_event_set event_in, @@ -104,6 +206,29 @@ rtems_status_code rtems_event_receive ( rtems_event_set *event_out ); +/** @} */ + +/** + * @defgroup ScoreEvent Event Handler + * + * @ingroup Score + * + * @{ + */ + +/** + * This constant is passed as the event_in to the + * rtems_event_receive directive to determine which events are pending. + */ +#define EVENT_CURRENT 0 + +/** + * @brief Event_Manager_initialization + * + * This routine performs the initialization necessary for this manager. + */ +void _Event_Manager_initialization( void ); + /** * @brief Event_Seize * @@ -149,6 +274,8 @@ void _Event_Timeout ( */ RTEMS_EVENT_EXTERN volatile Thread_blocking_operation_States _Event_Sync_state; +/** @} */ + #if defined(RTEMS_MULTIPROCESSING) #include #endif @@ -160,7 +287,5 @@ RTEMS_EVENT_EXTERN volatile Thread_blocking_operation_States _Event_Sync_state; } #endif -/**@}*/ - #endif /* end of include file */ diff --git a/cpukit/rtems/include/rtems/rtems/eventset.h b/cpukit/rtems/include/rtems/rtems/eventset.h index 679934f22b..2a86ebb070 100644 --- a/cpukit/rtems/include/rtems/rtems/eventset.h +++ b/cpukit/rtems/include/rtems/rtems/eventset.h @@ -19,108 +19,118 @@ #ifndef _RTEMS_RTEMS_EVENTSET_H #define _RTEMS_RTEMS_EVENTSET_H -/** - * @defgroup ClassicEventSet Event Sets - * - * @ingroup ClassicRTEMS - * - * This encapsulates functionality related to Classic API - * Event Sets. These are used by the Classic API Event Manager. - */ -/**@{*/ - #ifdef __cplusplus extern "C" { #endif /** - * The following defines the type used to control event sets. + * @defgroup ClassicEventSet Event Set + * + * @ingroup ClassicEvent + * + * @{ */ -typedef uint32_t rtems_event_set; /** - * The following constant is used to receive the set of currently pending - * events. + * @brief Integer type to hold an event set of up to 32 events represented as + * a bit field. */ -#define RTEMS_PENDING_EVENTS 0 +typedef uint32_t rtems_event_set; /** - * The following constant is used when you wish to send or receive all - * events. + * @brief Constant used to send or receive all events. */ #define RTEMS_ALL_EVENTS 0xFFFFFFFF -/** This defines the bit in the event set associated with event 0. */ +/** @brief Defines the bit in the event set associated with event 0. */ #define RTEMS_EVENT_0 0x00000001 -/** This defines the bit in the event set associated with event 1. */ +/** @brief Defines the bit in the event set associated with event 1. */ #define RTEMS_EVENT_1 0x00000002 -/** This defines the bit in the event set associated with event 2. */ +/** @brief Defines the bit in the event set associated with event 2. */ #define RTEMS_EVENT_2 0x00000004 -/** This defines the bit in the event set associated with event 3. */ +/** @brief Defines the bit in the event set associated with event 3. */ #define RTEMS_EVENT_3 0x00000008 -/** This defines the bit in the event set associated with event 4. */ +/** @brief Defines the bit in the event set associated with event 4. */ #define RTEMS_EVENT_4 0x00000010 -/** This defines the bit in the event set associated with event 5. */ +/** @brief Defines the bit in the event set associated with event 5. */ #define RTEMS_EVENT_5 0x00000020 -/** This defines the bit in the event set associated with event 6. */ +/** @brief Defines the bit in the event set associated with event 6. */ #define RTEMS_EVENT_6 0x00000040 -/** This defines the bit in the event set associated with event 7. */ +/** @brief Defines the bit in the event set associated with event 7. */ #define RTEMS_EVENT_7 0x00000080 -/** This defines the bit in the event set associated with event 8. */ +/** @brief Defines the bit in the event set associated with event 8. */ #define RTEMS_EVENT_8 0x00000100 -/** This defines the bit in the event set associated with event 9. */ +/** @brief Defines the bit in the event set associated with event 9. */ #define RTEMS_EVENT_9 0x00000200 -/** This defines the bit in the event set associated with event 10. */ +/** @brief Defines the bit in the event set associated with event 10. */ #define RTEMS_EVENT_10 0x00000400 -/** This defines the bit in the event set associated with event 11. */ +/** @brief Defines the bit in the event set associated with event 11. */ #define RTEMS_EVENT_11 0x00000800 -/** This defines the bit in the event set associated with event 12. */ +/** @brief Defines the bit in the event set associated with event 12. */ #define RTEMS_EVENT_12 0x00001000 -/** This defines the bit in the event set associated with event 13. */ +/** @brief Defines the bit in the event set associated with event 13. */ #define RTEMS_EVENT_13 0x00002000 -/** This defines the bit in the event set associated with event 14. */ +/** @brief Defines the bit in the event set associated with event 14. */ #define RTEMS_EVENT_14 0x00004000 -/** This defines the bit in the event set associated with event 15. */ +/** @brief Defines the bit in the event set associated with event 15. */ #define RTEMS_EVENT_15 0x00008000 -/** This defines the bit in the event set associated with event 16. */ +/** @brief Defines the bit in the event set associated with event 16. */ #define RTEMS_EVENT_16 0x00010000 -/** This defines the bit in the event set associated with event 17. */ +/** @brief Defines the bit in the event set associated with event 17. */ #define RTEMS_EVENT_17 0x00020000 -/** This defines the bit in the event set associated with event 18. */ +/** @brief Defines the bit in the event set associated with event 18. */ #define RTEMS_EVENT_18 0x00040000 -/** This defines the bit in the event set associated with event 19. */ +/** @brief Defines the bit in the event set associated with event 19. */ #define RTEMS_EVENT_19 0x00080000 -/** This defines the bit in the event set associated with event 20. */ +/** @brief Defines the bit in the event set associated with event 20. */ #define RTEMS_EVENT_20 0x00100000 -/** This defines the bit in the event set associated with event 21. */ +/** @brief Defines the bit in the event set associated with event 21. */ #define RTEMS_EVENT_21 0x00200000 -/** This defines the bit in the event set associated with event 22. */ +/** @brief Defines the bit in the event set associated with event 22. */ #define RTEMS_EVENT_22 0x00400000 -/** This defines the bit in the event set associated with event 23. */ +/** @brief Defines the bit in the event set associated with event 23. */ #define RTEMS_EVENT_23 0x00800000 -/** This defines the bit in the event set associated with event 24. */ +/** @brief Defines the bit in the event set associated with event 24. */ #define RTEMS_EVENT_24 0x01000000 -/** This defines the bit in the event set associated with event 25. */ +/** @brief Defines the bit in the event set associated with event 25. */ #define RTEMS_EVENT_25 0x02000000 -/** This defines the bit in the event set associated with event 26. */ +/** @brief Defines the bit in the event set associated with event 26. */ #define RTEMS_EVENT_26 0x04000000 -/** This defines the bit in the event set associated with event 27. */ +/** @brief Defines the bit in the event set associated with event 27. */ #define RTEMS_EVENT_27 0x08000000 -/** This defines the bit in the event set associated with event 29. */ +/** @brief Defines the bit in the event set associated with event 29. */ #define RTEMS_EVENT_28 0x10000000 -/** This defines the bit in the event set associated with event 29. */ +/** @brief Defines the bit in the event set associated with event 29. */ #define RTEMS_EVENT_29 0x20000000 -/** This defines the bit in the event set associated with event 30. */ +/** @brief Defines the bit in the event set associated with event 30. */ #define RTEMS_EVENT_30 0x40000000 -/** This defines the bit in the event set associated with event 31. */ +/** @brief Defines the bit in the event set associated with event 31. */ #define RTEMS_EVENT_31 0x80000000 +/** @} */ + +/** + * @brief Constant used to receive the set of currently pending events in + * rtems_event_receive(). + * + * @ingroup ClassicEvent + */ +#define RTEMS_PENDING_EVENTS 0 + +/** + * @addtogroup ScoreEvent + * + * @{ + */ + /** * The following constant is the value of an event set which * has no events pending. */ #define EVENT_SETS_NONE_PENDING 0 +/** @} */ + #ifndef __RTEMS_APPLICATION__ #include #endif @@ -129,7 +139,5 @@ typedef uint32_t rtems_event_set; } #endif -/**@}*/ - #endif /* end of include file */ -- cgit v1.2.3