<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>change log for rtems (2011-11-10)</title>
</head>
<body text='#000000' bgcolor='#ffffff'>
<a name='cs1'></a>
<table border='0' cellspacing='0' cellpadding='5' width='100%' bgcolor='#eeeeee'>
<tr><td colspan='3' bgcolor='#dddddd'>
<font color='#bb2222'><strong>sh</strong></font>
</td></tr>
<tr><td colspan='3' bgcolor='#dddddd'><pre>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.
</pre></td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/cpukit/ChangeLog.diff?r1=text&tr1=1.2988&r2=text&tr2=1.2989&diff_format=h">M</a></td><td width='1%'>1.2989</td><td width='100%'>cpukit/ChangeLog</td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/cpukit/rtems/include/rtems/rtems/event.h.diff?r1=text&tr1=1.26&r2=text&tr2=1.27&diff_format=h">M</a></td><td width='1%'>1.27</td><td width='100%'>cpukit/rtems/include/rtems/rtems/event.h</td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/cpukit/rtems/include/rtems/rtems/eventset.h.diff?r1=text&tr1=1.16&r2=text&tr2=1.17&diff_format=h">M</a></td><td width='1%'>1.17</td><td width='100%'>cpukit/rtems/include/rtems/rtems/eventset.h</td></tr>
<tr><td width='1%'><a href="http://www.rtems.com/cgi-bin/viewcvs.cgi//rtems/cpukit/rtems/inline/rtems/rtems/eventset.inl.diff?r1=text&tr1=1.17&r2=text&tr2=1.18&diff_format=h">M</a></td><td width='1%'>1.18</td><td width='100%'>cpukit/rtems/inline/rtems/rtems/eventset.inl</td></tr>
</table>
<pre>
<font color='#006600'>diff -u rtems/cpukit/ChangeLog:1.2988 rtems/cpukit/ChangeLog:1.2989
--- rtems/cpukit/ChangeLog:1.2988 Wed Nov 9 12:51:58 2011
+++ rtems/cpukit/ChangeLog Thu Nov 10 08:09:08 2011
</font><font color='#997700'>@@ -1,3 +1,9 @@
</font><font color='#000088'>+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.
+
</font> 2011-11-07 Ralf Corsepius <ralf.corsepius@rtems.org>
PR 1952/cpukit
<font color='#006600'>diff -u rtems/cpukit/rtems/include/rtems/rtems/event.h:1.26 rtems/cpukit/rtems/include/rtems/rtems/event.h:1.27
--- rtems/cpukit/rtems/include/rtems/rtems/event.h:1.26 Tue Dec 15 12:26:40 2009
+++ rtems/cpukit/rtems/include/rtems/rtems/event.h Thu Nov 10 08:09:08 2011
</font><font color='#997700'>@@ -53,49 +53,151 @@
</font> *
* @ingroup ClassicRTEMS
*
<font color='#880000'>- * 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
</font><font color='#000088'>+ * @brief The event manager provides a high performance method of intertask
+ * communication and synchronization.
</font> *
<font color='#880000'>- * This routine performs the initialization necessary for this manager.
- */
-void _Event_Manager_initialization( void );
-
-/**
- * @brief rtems_event_send
</font><font color='#000088'>+ * 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.<span style="background-color: #FF0000"> </span>
+ *
+ * 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.<span style="background-color: #FF0000"> </span>
+ *
+ * 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.<span style="background-color: #FF0000"> </span>
+ *
+ * @{
+ */
+
+/**
+ * @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.<span style="background-color: #FF0000"> </span>
+ * - not waiting for events.
+ * - The event set is posted and left pending.<span style="background-color: #FF0000"> </span>
+ *
+ * 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.
</font> *
<font color='#880000'>- * 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.
</font><font color='#000088'>+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID Invalid task identifier.
</font> */
rtems_status_code rtems_event_send (
<font color='#880000'>- rtems_id id,
</font><font color='#000088'>+ rtems_id target_task_id,
</font> rtems_event_set event_in
);
/**
<font color='#880000'>- * @brief rtems_event_receive
</font><font color='#000088'>+ * @brief Receives pending events.
</font> *
<font color='#880000'>- * 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.
</font><font color='#000088'>+ * 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).
+ *<span style="background-color: #FF0000"> </span>
+ * @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.
</font> */
rtems_status_code rtems_event_receive (
rtems_event_set event_in,
<font color='#997700'>@@ -104,6 +206,29 @@
</font> rtems_event_set *event_out
);
<font color='#000088'>+/** @} */
+
+/**
+ * @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 );
+
</font> /**
* @brief Event_Seize
*
<font color='#997700'>@@ -149,6 +274,8 @@
</font> */
RTEMS_EVENT_EXTERN volatile Thread_blocking_operation_States _Event_Sync_state;
<font color='#000088'>+/** @} */
+
</font> #if defined(RTEMS_MULTIPROCESSING)
#include <rtems/rtems/eventmp.h>
#endif
<font color='#997700'>@@ -160,7 +287,5 @@
</font> }
#endif
<font color='#880000'>-/**@}*/
-
</font> #endif
/* end of include file */
<font color='#006600'>diff -u rtems/cpukit/rtems/include/rtems/rtems/eventset.h:1.16 rtems/cpukit/rtems/include/rtems/rtems/eventset.h:1.17
--- rtems/cpukit/rtems/include/rtems/rtems/eventset.h:1.16 Wed Aug 5 13:17:12 2009
+++ rtems/cpukit/rtems/include/rtems/rtems/eventset.h Thu Nov 10 08:09:08 2011
</font><font color='#997700'>@@ -19,108 +19,118 @@
</font> #ifndef _RTEMS_RTEMS_EVENTSET_H
#define _RTEMS_RTEMS_EVENTSET_H
<font color='#880000'>-/**
- * @defgroup ClassicEventSet Event Sets
- *
- * @ingroup ClassicRTEMS
- *
- * This encapsulates functionality related to Classic API
- * Event Sets. These are used by the Classic API Event Manager.
- */
-/**@{*/
-
</font> #ifdef __cplusplus
extern "C" {
#endif
/**
<font color='#880000'>- * The following defines the type used to control event sets.
</font><font color='#000088'>+ * @defgroup ClassicEventSet Event Set
+ *
+ * @ingroup ClassicEvent
+ *
+ * @{
</font> */
<font color='#880000'>-typedef uint32_t rtems_event_set;
</font>
/**
<font color='#880000'>- * The following constant is used to receive the set of currently pending
- * events.
</font><font color='#000088'>+ * @brief Integer type to hold an event set of up to 32 events represented as
+ * a bit field.
</font> */
<font color='#880000'>-#define RTEMS_PENDING_EVENTS 0
</font><font color='#000088'>+typedef uint32_t rtems_event_set;
</font>
/**
<font color='#880000'>- * The following constant is used when you wish to send or receive all
- * events.
</font><font color='#000088'>+ * @brief Constant used to send or receive all events.
</font> */
#define RTEMS_ALL_EVENTS 0xFFFFFFFF
<font color='#880000'>-/** This defines the bit in the event set associated with event 0. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 0. */
</font> #define RTEMS_EVENT_0 0x00000001
<font color='#880000'>-/** This defines the bit in the event set associated with event 1. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 1. */
</font> #define RTEMS_EVENT_1 0x00000002
<font color='#880000'>-/** This defines the bit in the event set associated with event 2. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 2. */
</font> #define RTEMS_EVENT_2 0x00000004
<font color='#880000'>-/** This defines the bit in the event set associated with event 3. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 3. */
</font> #define RTEMS_EVENT_3 0x00000008
<font color='#880000'>-/** This defines the bit in the event set associated with event 4. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 4. */
</font> #define RTEMS_EVENT_4 0x00000010
<font color='#880000'>-/** This defines the bit in the event set associated with event 5. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 5. */
</font> #define RTEMS_EVENT_5 0x00000020
<font color='#880000'>-/** This defines the bit in the event set associated with event 6. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 6. */
</font> #define RTEMS_EVENT_6 0x00000040
<font color='#880000'>-/** This defines the bit in the event set associated with event 7. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 7. */
</font> #define RTEMS_EVENT_7 0x00000080
<font color='#880000'>-/** This defines the bit in the event set associated with event 8. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 8. */
</font> #define RTEMS_EVENT_8 0x00000100
<font color='#880000'>-/** This defines the bit in the event set associated with event 9. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 9. */
</font> #define RTEMS_EVENT_9 0x00000200
<font color='#880000'>-/** This defines the bit in the event set associated with event 10. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 10. */
</font> #define RTEMS_EVENT_10 0x00000400
<font color='#880000'>-/** This defines the bit in the event set associated with event 11. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 11. */
</font> #define RTEMS_EVENT_11 0x00000800
<font color='#880000'>-/** This defines the bit in the event set associated with event 12. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 12. */
</font> #define RTEMS_EVENT_12 0x00001000
<font color='#880000'>-/** This defines the bit in the event set associated with event 13. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 13. */
</font> #define RTEMS_EVENT_13 0x00002000
<font color='#880000'>-/** This defines the bit in the event set associated with event 14. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 14. */
</font> #define RTEMS_EVENT_14 0x00004000
<font color='#880000'>-/** This defines the bit in the event set associated with event 15. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 15. */
</font> #define RTEMS_EVENT_15 0x00008000
<font color='#880000'>-/** This defines the bit in the event set associated with event 16. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 16. */
</font> #define RTEMS_EVENT_16 0x00010000
<font color='#880000'>-/** This defines the bit in the event set associated with event 17. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 17. */
</font> #define RTEMS_EVENT_17 0x00020000
<font color='#880000'>-/** This defines the bit in the event set associated with event 18. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 18. */
</font> #define RTEMS_EVENT_18 0x00040000
<font color='#880000'>-/** This defines the bit in the event set associated with event 19. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 19. */
</font> #define RTEMS_EVENT_19 0x00080000
<font color='#880000'>-/** This defines the bit in the event set associated with event 20. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 20. */
</font> #define RTEMS_EVENT_20 0x00100000
<font color='#880000'>-/** This defines the bit in the event set associated with event 21. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 21. */
</font> #define RTEMS_EVENT_21 0x00200000
<font color='#880000'>-/** This defines the bit in the event set associated with event 22. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 22. */
</font> #define RTEMS_EVENT_22 0x00400000
<font color='#880000'>-/** This defines the bit in the event set associated with event 23. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 23. */
</font> #define RTEMS_EVENT_23 0x00800000
<font color='#880000'>-/** This defines the bit in the event set associated with event 24. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 24. */
</font> #define RTEMS_EVENT_24 0x01000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 25. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 25. */
</font> #define RTEMS_EVENT_25 0x02000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 26. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 26. */
</font> #define RTEMS_EVENT_26 0x04000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 27. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 27. */
</font> #define RTEMS_EVENT_27 0x08000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 29. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 29. */
</font> #define RTEMS_EVENT_28 0x10000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 29. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 29. */
</font> #define RTEMS_EVENT_29 0x20000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 30. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 30. */
</font> #define RTEMS_EVENT_30 0x40000000
<font color='#880000'>-/** This defines the bit in the event set associated with event 31. */
</font><font color='#000088'>+/** @brief Defines the bit in the event set associated with event 31. */
</font> #define RTEMS_EVENT_31 0x80000000
<font color='#000088'>+/** @} */
+
+/**
+ * @brief Constant used to receive the set of currently pending events in
+ * rtems_event_receive().
+ *
+ * @ingroup ClassicEvent
+ */
+#define RTEMS_PENDING_EVENTS 0
+
+/**
+ * @addtogroup ScoreEvent
+ *
+ * @{
+ */
+
</font> /**
* The following constant is the value of an event set which
* has no events pending.
*/
#define EVENT_SETS_NONE_PENDING 0
<font color='#000088'>+/** @} */
+
</font> #ifndef __RTEMS_APPLICATION__
#include <rtems/rtems/eventset.inl>
#endif
<font color='#997700'>@@ -129,7 +139,5 @@
</font> }
#endif
<font color='#880000'>-/**@}*/
-
</font> #endif
/* end of include file */
<font color='#006600'>diff -u rtems/cpukit/rtems/inline/rtems/rtems/eventset.inl:1.17 rtems/cpukit/rtems/inline/rtems/rtems/eventset.inl:1.18
--- rtems/cpukit/rtems/inline/rtems/rtems/eventset.inl:1.17 Wed Feb 23 07:59:03 2011
+++ rtems/cpukit/rtems/inline/rtems/rtems/eventset.inl Thu Nov 10 08:09:08 2011
</font><font color='#997700'>@@ -25,7 +25,7 @@
</font> #include <rtems/score/isr.h> /* ISR_Level */
/**
<font color='#880000'>- * @addtogroup ClassicEventSet
</font><font color='#000088'>+ * @addtogroup ScoreEvent
</font> * @{
*/
</pre>
<p> </p>
<p>--<br />
<small>Generated by <a href="http://www.codewiz.org/projects/index.html#loginfo">Deluxe Loginfo</a> 2.122 by Bernardo Innocenti <bernie@develer.com></small></p>
</body>
</html>