From 134fc76d3b306e3627cefc612a269aa3e04ee9f8 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 14 Oct 2020 11:30:19 +0200 Subject: rtems: Update event documentation --- 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, -- cgit v1.2.3