[PATCH 20/20] rtems: Update event documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Nov 20 11:15:26 UTC 2020
---
cpukit/include/rtems/rtems/eventdata.h | 6 ++
cpukit/include/rtems/rtems/eventimpl.h | 86 ++++++++++++++++++++++----
2 files changed, 79 insertions(+), 13 deletions(-)
diff --git a/cpukit/include/rtems/rtems/eventdata.h b/cpukit/include/rtems/rtems/eventdata.h
index fa69a2a932..23f0a1bf9e 100644
--- a/cpukit/include/rtems/rtems/eventdata.h
+++ b/cpukit/include/rtems/rtems/eventdata.h
@@ -30,7 +30,13 @@ extern "C" {
* @{
*/
+/**
+ * @brief This structure is used to manage a set of events.
+ */
typedef struct {
+ /**
+ * @brief The member contains the pending events.
+ */
rtems_event_set pending_events;
} Event_Control;
diff --git a/cpukit/include/rtems/rtems/eventimpl.h b/cpukit/include/rtems/rtems/eventimpl.h
index dc56ad2127..4635d76437 100644
--- a/cpukit/include/rtems/rtems/eventimpl.h
+++ b/cpukit/include/rtems/rtems/eventimpl.h
@@ -25,13 +25,42 @@ extern "C" {
#endif
/**
- * @defgroup ClassicEventImpl Classic Event Implementation
+ * @defgroup ClassicEventImpl Event Implementation
*
* @ingroup RTEMSImplClassic
*
* @{
*/
+/**
+ * @brief Seizes a set of events.
+ *
+ * @param event_in is the input event set.
+ *
+ * @param option_set is the option set.
+ *
+ * @param ticks is the optional timeout in clock ticks.
+ *
+ * @param event_out[out] is the output event set.
+ *
+ * @param executing[in, out] is the executing thread.
+ *
+ * @param event[in, out] is the source event set.
+ *
+ * @param wait_class is the thread wait class of the source event set.
+ *
+ * @param block_state is the thread blocking state of the source event set.
+ *
+ * @param lock_context[in, out] is the lock context set up by _Thread_Get().
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_UNSATISFIED The events of interest were not immediately
+ * available.
+ *
+ * @retval ::RTEMS_TIMEOUT The events of interest were not available within the
+ * specified timeout interval.
+ */
rtems_status_code _Event_Seize(
rtems_event_set event_in,
rtems_option option_set,
@@ -44,6 +73,21 @@ rtems_status_code _Event_Seize(
ISR_lock_Context *lock_context
);
+/**
+ * @brief Surrenders a set of events.
+ *
+ * @param the_thread[in, out] is the thread of the event set.
+ *
+ * @param event_in is the set of events to post.
+ *
+ * @param event[in, out] is the target event set.
+ *
+ * @param wait_class is the thread wait class of the target event set.
+ *
+ * @param lock_context[in, out] is the lock context set up by _Thread_Get().
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ */
rtems_status_code _Event_Surrender(
Thread_Control *the_thread,
rtems_event_set event_in,
@@ -52,16 +96,23 @@ rtems_status_code _Event_Surrender(
ISR_lock_Context *lock_context
);
+/**
+ * @brief Initializes an event control block to have no pending events.
+ *
+ * @param event is the event control block to initialize.
+ */
RTEMS_INLINE_ROUTINE void _Event_Initialize( Event_Control *event )
{
event->pending_events = 0;
}
/**
- * @brief Checks if on events are posted in the event_set.
+ * @brief Checks if the event set is empty.
+ *
+ * @param the_event_set is the event set to check.
*
- * This function returns TRUE if on events are posted in the event_set,
- * and FALSE otherwise.
+ * @return Returns true, if there are no posted events in the event set,
+ * otherwise false.
*/
RTEMS_INLINE_ROUTINE bool _Event_sets_Is_empty(
rtems_event_set the_event_set
@@ -71,10 +122,11 @@ RTEMS_INLINE_ROUTINE bool _Event_sets_Is_empty(
}
/**
- * @brief Posts the given new_events into the event_set passed in.
+ * @brief Posts the events in the specified event set.
*
- * This routine posts the given new_events into the event_set
- * passed in. The result is returned to the user in event_set.
+ * @param the_new_events is the set of events to post.
+ *
+ * @param the_event_set[in, out] is the event set.
*/
RTEMS_INLINE_ROUTINE void _Event_sets_Post(
rtems_event_set the_new_events,
@@ -85,10 +137,14 @@ RTEMS_INLINE_ROUTINE void _Event_sets_Post(
}
/**
- * @brief Returns the events in event_condition that are set in event_set.
+ * @brief Gets the events of the specified event condition.
+ *
+ * @param the_event_set is the event set.
*
- * This function returns the events in event_condition which are
- * set in event_set.
+ * @param the_event_condition is the event condition defining the events of interest.
+ *
+ * @return Return the events of the event condition which are posted in the
+ * event set.
*/
RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Get(
rtems_event_set the_event_set,
@@ -99,10 +155,14 @@ RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Get(
}
/**
- * @brief Removes the events in mask from the event_set passed in.
+ * @brief Clears a set of events from an event set.
+ *
+ * @param the_event_set is the event set.
+ *
+ * @param the_mask is the set of events to clear.
*
- * This function removes the events in mask from the event_set
- * passed in. The result is returned to the user in event_set.
+ * @return Returns the event set with all event cleared specified by the event
+ * mask.
*/
RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Clear(
rtems_event_set the_event_set,
--
2.26.2
More information about the devel
mailing list