forked from Imagelibrary/rtems
2011-11-10 Sebastian Huber <sebastian.huber@embedded-brains.de>
* rtems/include/rtems/rtems/event.h, rtems/include/rtems/rtems/eventset.h, rtems/inline/rtems/rtems/eventset.inl: Documentation.
This commit is contained in:
Sebastian Huber
@@ -1,3 +1,9 @@
|
||||
2011-11-10 Sebastian Huber <sebastian.huber@embedded-brains.de>
|
||||
|
||||
* rtems/include/rtems/rtems/event.h,
|
||||
rtems/include/rtems/rtems/eventset.h,
|
||||
rtems/inline/rtems/rtems/eventset.inl: Documentation.
|
||||
|
||||
2011-11-07 Ralf Corsepius <ralf.corsepius@rtems.org>
|
||||
|
||||
PR 1952/cpukit
|
||||
|
||||
@@ -53,9 +53,168 @@ extern "C" {
|
||||
*
|
||||
* @ingroup ClassicRTEMS
|
||||
*
|
||||
* This encapsulates functionality which XXX
|
||||
* @brief The event manager provides a high performance method of intertask
|
||||
* communication and synchronization.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @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.
|
||||
*
|
||||
* 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 target_task_id,
|
||||
rtems_event_set event_in
|
||||
);
|
||||
|
||||
/**
|
||||
* @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,
|
||||
rtems_option option_set,
|
||||
rtems_interval ticks,
|
||||
rtems_event_set *event_out
|
||||
);
|
||||
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup ScoreEvent Event Handler
|
||||
*
|
||||
* @ingroup Score
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
/**@{*/
|
||||
|
||||
/**
|
||||
* This constant is passed as the event_in to the
|
||||
@@ -70,40 +229,6 @@ extern "C" {
|
||||
*/
|
||||
void _Event_Manager_initialization( void );
|
||||
|
||||
/**
|
||||
* @brief rtems_event_send
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
rtems_status_code rtems_event_send (
|
||||
rtems_id 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.
|
||||
*/
|
||||
rtems_status_code rtems_event_receive (
|
||||
rtems_event_set event_in,
|
||||
rtems_option option_set,
|
||||
rtems_interval ticks,
|
||||
rtems_event_set *event_out
|
||||
);
|
||||
|
||||
/**
|
||||
* @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 <rtems/rtems/eventmp.h>
|
||||
#endif
|
||||
@@ -160,7 +287,5 @@ RTEMS_EVENT_EXTERN volatile Thread_blocking_operation_States _Event_Sync_state;
|
||||
}
|
||||
#endif
|
||||
|
||||
/**@}*/
|
||||
|
||||
#endif
|
||||
/* end of include file */
|
||||
|
||||
@@ -19,101 +19,109 @@
|
||||
#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
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Integer type to hold an event set of up to 32 events represented as
|
||||
* a bit field.
|
||||
*/
|
||||
typedef uint32_t rtems_event_set;
|
||||
|
||||
/**
|
||||
* The following constant is used to receive the set of currently pending
|
||||
* events.
|
||||
* @brief Constant used to send or receive all events.
|
||||
*/
|
||||
#define RTEMS_ALL_EVENTS 0xFFFFFFFF
|
||||
|
||||
/** @brief Defines the bit in the event set associated with event 0. */
|
||||
#define RTEMS_EVENT_0 0x00000001
|
||||
/** @brief Defines the bit in the event set associated with event 1. */
|
||||
#define RTEMS_EVENT_1 0x00000002
|
||||
/** @brief Defines the bit in the event set associated with event 2. */
|
||||
#define RTEMS_EVENT_2 0x00000004
|
||||
/** @brief Defines the bit in the event set associated with event 3. */
|
||||
#define RTEMS_EVENT_3 0x00000008
|
||||
/** @brief Defines the bit in the event set associated with event 4. */
|
||||
#define RTEMS_EVENT_4 0x00000010
|
||||
/** @brief Defines the bit in the event set associated with event 5. */
|
||||
#define RTEMS_EVENT_5 0x00000020
|
||||
/** @brief Defines the bit in the event set associated with event 6. */
|
||||
#define RTEMS_EVENT_6 0x00000040
|
||||
/** @brief Defines the bit in the event set associated with event 7. */
|
||||
#define RTEMS_EVENT_7 0x00000080
|
||||
/** @brief Defines the bit in the event set associated with event 8. */
|
||||
#define RTEMS_EVENT_8 0x00000100
|
||||
/** @brief Defines the bit in the event set associated with event 9. */
|
||||
#define RTEMS_EVENT_9 0x00000200
|
||||
/** @brief Defines the bit in the event set associated with event 10. */
|
||||
#define RTEMS_EVENT_10 0x00000400
|
||||
/** @brief Defines the bit in the event set associated with event 11. */
|
||||
#define RTEMS_EVENT_11 0x00000800
|
||||
/** @brief Defines the bit in the event set associated with event 12. */
|
||||
#define RTEMS_EVENT_12 0x00001000
|
||||
/** @brief Defines the bit in the event set associated with event 13. */
|
||||
#define RTEMS_EVENT_13 0x00002000
|
||||
/** @brief Defines the bit in the event set associated with event 14. */
|
||||
#define RTEMS_EVENT_14 0x00004000
|
||||
/** @brief Defines the bit in the event set associated with event 15. */
|
||||
#define RTEMS_EVENT_15 0x00008000
|
||||
/** @brief Defines the bit in the event set associated with event 16. */
|
||||
#define RTEMS_EVENT_16 0x00010000
|
||||
/** @brief Defines the bit in the event set associated with event 17. */
|
||||
#define RTEMS_EVENT_17 0x00020000
|
||||
/** @brief Defines the bit in the event set associated with event 18. */
|
||||
#define RTEMS_EVENT_18 0x00040000
|
||||
/** @brief Defines the bit in the event set associated with event 19. */
|
||||
#define RTEMS_EVENT_19 0x00080000
|
||||
/** @brief Defines the bit in the event set associated with event 20. */
|
||||
#define RTEMS_EVENT_20 0x00100000
|
||||
/** @brief Defines the bit in the event set associated with event 21. */
|
||||
#define RTEMS_EVENT_21 0x00200000
|
||||
/** @brief Defines the bit in the event set associated with event 22. */
|
||||
#define RTEMS_EVENT_22 0x00400000
|
||||
/** @brief Defines the bit in the event set associated with event 23. */
|
||||
#define RTEMS_EVENT_23 0x00800000
|
||||
/** @brief Defines the bit in the event set associated with event 24. */
|
||||
#define RTEMS_EVENT_24 0x01000000
|
||||
/** @brief Defines the bit in the event set associated with event 25. */
|
||||
#define RTEMS_EVENT_25 0x02000000
|
||||
/** @brief Defines the bit in the event set associated with event 26. */
|
||||
#define RTEMS_EVENT_26 0x04000000
|
||||
/** @brief Defines the bit in the event set associated with event 27. */
|
||||
#define RTEMS_EVENT_27 0x08000000
|
||||
/** @brief Defines the bit in the event set associated with event 29. */
|
||||
#define RTEMS_EVENT_28 0x10000000
|
||||
/** @brief Defines the bit in the event set associated with event 29. */
|
||||
#define RTEMS_EVENT_29 0x20000000
|
||||
/** @brief Defines the bit in the event set associated with event 30. */
|
||||
#define RTEMS_EVENT_30 0x40000000
|
||||
/** @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
|
||||
|
||||
/**
|
||||
* The following constant is used when you wish to send or receive all
|
||||
* events.
|
||||
* @addtogroup ScoreEvent
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
#define RTEMS_ALL_EVENTS 0xFFFFFFFF
|
||||
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_1 0x00000002
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_3 0x00000008
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_5 0x00000020
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_7 0x00000080
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_9 0x00000200
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_11 0x00000800
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_13 0x00002000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_15 0x00008000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_17 0x00020000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_19 0x00080000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_21 0x00200000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_23 0x00800000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_25 0x02000000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_27 0x08000000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_29 0x20000000
|
||||
/** This 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. */
|
||||
#define RTEMS_EVENT_31 0x80000000
|
||||
|
||||
/**
|
||||
* The following constant is the value of an event set which
|
||||
@@ -121,6 +129,8 @@ typedef uint32_t rtems_event_set;
|
||||
*/
|
||||
#define EVENT_SETS_NONE_PENDING 0
|
||||
|
||||
/** @} */
|
||||
|
||||
#ifndef __RTEMS_APPLICATION__
|
||||
#include <rtems/rtems/eventset.inl>
|
||||
#endif
|
||||
@@ -129,7 +139,5 @@ typedef uint32_t rtems_event_set;
|
||||
}
|
||||
#endif
|
||||
|
||||
/**@}*/
|
||||
|
||||
#endif
|
||||
/* end of include file */
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
#include <rtems/score/isr.h> /* ISR_Level */
|
||||
|
||||
/**
|
||||
* @addtogroup ClassicEventSet
|
||||
* @addtogroup ScoreEvent
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user