From accbe670a0be2d5324b982ff4cab2d634c99fc76 Mon Sep 17 00:00:00 2001 From: Andreas Dachsberger Date: Fri, 5 Apr 2019 10:59:58 +0200 Subject: doxygen: score: adjust doc in corebarrierimpl.h to doxygen guidelines Update #3706. --- cpukit/include/rtems/score/corebarrierimpl.h | 89 ++++++++++++++++++++-------- 1 file changed, 65 insertions(+), 24 deletions(-) (limited to 'cpukit/include/rtems/score/corebarrierimpl.h') diff --git a/cpukit/include/rtems/score/corebarrierimpl.h b/cpukit/include/rtems/score/corebarrierimpl.h index 48061e6fe8..9e9ddfd81e 100644 --- a/cpukit/include/rtems/score/corebarrierimpl.h +++ b/cpukit/include/rtems/score/corebarrierimpl.h @@ -1,6 +1,8 @@ /** * @file * + * @ingroup RTEMSScoreBarrier + * * @brief Inlined Routines Associated with the SuperCore Barrier * * This include file contains all of the inlined routines associated @@ -29,24 +31,32 @@ extern "C" { /** * @addtogroup RTEMSScoreBarrier + * + * @{ */ -/**@{**/ #define CORE_BARRIER_TQ_OPERATIONS &_Thread_queue_Operations_FIFO /** - * @brief Initialize core barrier. + * @brief Initializes the core barrier. * * This routine initializes the barrier based on the parameters passed. * - * @param[in] the_barrier is the barrier to initialize - * @param[in] the_barrier_attributes define the behavior of this instance + * @param[out] the_barrier The barrier to initialize. + * @param[out] the_barrier_attributes The attributes which define the behavior of this instance. */ void _CORE_barrier_Initialize( CORE_barrier_Control *the_barrier, CORE_barrier_Attributes *the_barrier_attributes ); +/** + * @brief Destroys the core barrier. + * + * This routine destroys the barrier. + * + * @param[out] the_barrier The barrier to destroy. + */ RTEMS_INLINE_ROUTINE void _CORE_barrier_Destroy( CORE_barrier_Control *the_barrier ) @@ -54,6 +64,12 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Destroy( _Thread_queue_Destroy( &the_barrier->Wait_queue ); } +/** + * @brief Acquires critical core barrier. + * + * @param[in, out] the_barrier The barrier to acquire. + * @param queue_context The thread queue context. + */ RTEMS_INLINE_ROUTINE void _CORE_barrier_Acquire_critical( CORE_barrier_Control *the_barrier, Thread_queue_Context *queue_context @@ -62,6 +78,12 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Acquire_critical( _Thread_queue_Acquire_critical( &the_barrier->Wait_queue, queue_context ); } +/** + * @brief Releases core barrier. + * + * @param[in, out] the_barrier The barrier to release. + * @param queue_context The thread queue context. + */ RTEMS_INLINE_ROUTINE void _CORE_barrier_Release( CORE_barrier_Control *the_barrier, Thread_queue_Context *queue_context @@ -71,16 +93,17 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Release( } /** - * @brief Wait for the barrier. + * @brief Waits for the barrier. * - * This routine wait for the barrier to be released. If the barrier - * is set to automatic and this is the appropriate thread, then it returns - * immediately. Otherwise, the calling thread is blocked until the barrier - * is released. + * This routine waits for the barrier to be released. If the barrier + * is set to automatic and this is the appropriate thread, then it returns + * immediately. Otherwise, the calling thread is blocked until the barrier + * is released. * - * @param[in] the_barrier is the barrier to wait for - * @param[in,out] executing The currently executing thread. - * @param[in] wait is true if the calling thread is willing to wait + * @param[in, out] the_barrier The barrier to wait for. + * @param[in, out] executing The currently executing thread. + * @param wait This parameter is true if the calling thread is willing to wait. + * @param queue_context The thread queue context. * * @return The method status. */ @@ -91,6 +114,13 @@ Status_Control _CORE_barrier_Seize( Thread_queue_Context *queue_context ); +/** + * @brief Flushes the barrier. + * + * @param[in, out] the_barrier The barrier to flush. + * @param[out] filter The filter for flushing. + * @param[out] queue_context The thread queue context. + */ uint32_t _CORE_barrier_Do_flush( CORE_barrier_Control *the_barrier, Thread_queue_Flush_filter filter, @@ -98,16 +128,15 @@ uint32_t _CORE_barrier_Do_flush( ); /** - * @brief Manually release the barrier. + * @brief Manually releases the barrier. * - * This routine manually releases the barrier. All of the threads waiting - * for the barrier will be readied. + * This routine manually releases the barrier. All of the threads waiting + * for the barrier will be readied. * - * @param[in] the_barrier is the barrier to surrender - * @param[in] mp_callout is the routine to invoke if the - * thread unblocked is remote + * @param[in, out] the_barrier The barrier to surrender. + * @param[out] queue_context The thread queue context. * - * @retval the number of unblocked threads + * @return The number of unblocked threads. */ RTEMS_INLINE_ROUTINE uint32_t _CORE_barrier_Surrender( CORE_barrier_Control *the_barrier, @@ -121,6 +150,12 @@ RTEMS_INLINE_ROUTINE uint32_t _CORE_barrier_Surrender( ); } +/** + * @brief Flushes the barrier using _CORE_barrier_Do_flush(). + * + * @param[in, out] the_barrier The barrier to flush. + * @param queue_context The thread queue context. + */ RTEMS_INLINE_ROUTINE void _CORE_barrier_Flush( CORE_barrier_Control *the_barrier, Thread_queue_Context *queue_context @@ -134,12 +169,15 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Flush( } /** + * @brief Checks if the barrier is automatic. + * * This function returns true if the automatic release attribute is * enabled in the @a attribute_set and false otherwise. * - * @param[in] the_attribute is the attribute set to test + * @param the_attribute The attribute set to test. * - * @return true if the priority attribute is enabled + * @retval true The automatic release attribute is enabled. + * @retval false The automatic release attribute is not enabled. */ RTEMS_INLINE_ROUTINE bool _CORE_barrier_Is_automatic( CORE_barrier_Attributes *the_attribute @@ -150,11 +188,14 @@ RTEMS_INLINE_ROUTINE bool _CORE_barrier_Is_automatic( } /** + * @brief Returns the number of currently waiting threads. + * * This routine returns the number of threads currently waiting at the barrier. * - * @param[in] the_barrier is the barrier to obtain the number of blocked - * threads for - * @return the current count of this barrier + * @param[in] the_barrier The barrier to obtain the number of blocked + * threads of. + * + * @return the current count of waiting threads of this barrier. */ RTEMS_INLINE_ROUTINE uint32_t _CORE_barrier_Get_number_of_waiting_threads( CORE_barrier_Control *the_barrier -- cgit v1.2.3