From 7d2cc98b9cb1449f609fd67ff3d134dafe876f89 Mon Sep 17 00:00:00 2001 From: Andreas Dachsberger Date: Thu, 18 Apr 2019 08:57:32 +0200 Subject: doxygen: score: adjust doc in userextimpl.h to doxygen guidelines Update #3706. --- cpukit/include/rtems/score/userextimpl.h | 156 ++++++++++++++++++++++++++++++- 1 file changed, 152 insertions(+), 4 deletions(-) (limited to 'cpukit/include/rtems/score/userextimpl.h') diff --git a/cpukit/include/rtems/score/userextimpl.h b/cpukit/include/rtems/score/userextimpl.h index 851e28c179..8b456c072d 100644 --- a/cpukit/include/rtems/score/userextimpl.h +++ b/cpukit/include/rtems/score/userextimpl.h @@ -30,8 +30,9 @@ extern "C" { /** * @addtogroup RTEMSScoreUserExt + * + * @{ */ -/** @{ **/ /** * @brief Chain iterator for dynamic user extensions. @@ -77,15 +78,29 @@ extern Chain_Control _User_extensions_Switches_list; /** * @name Extension Maintainance + * + * @{ */ -/** @{ **/ +/** + * @brief Initializes the user extensions handler. + */ void _User_extensions_Handler_initialization( void ); +/** + * @brief Adds a user extension. + * + * @param extension The user extension to add. + */ void _User_extensions_Add_set( User_extensions_Control *extension ); +/** + * @brief Adds a user extension. + * + * @param extension The user extension to add. + */ RTEMS_INLINE_ROUTINE void _User_extensions_Add_API_set( User_extensions_Control *extension ) @@ -93,6 +108,12 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Add_API_set( _User_extensions_Add_set( extension ); } +/** + * @brief Adds a user extension with the given extension table as callouts. + * + * @param[in, out] extension The user extension to add. + * @param extension_table Is set as callouts for @a extension. + */ RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table( User_extensions_Control *extension, const User_extensions_Table *extension_table @@ -103,6 +124,11 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table( _User_extensions_Add_set( extension ); } +/** + * @brief Removes a user extension. + * + * @param extension The user extension to remove. + */ void _User_extensions_Remove_set( User_extensions_Control *extension ); @@ -125,36 +151,78 @@ typedef struct { bool ok; } User_extensions_Thread_create_context; +/** + * @brief Creates a visitor. + * + * @param executing The currently executing thread. + * @param[in, out] arg Is used as the thread create context for the operation. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_create_visitor( Thread_Control *executing, void *arg, const User_extensions_Table *callouts ); +/** + * @brief Deletes a visitor. + * + * @param executing The currently executing thread. + * @param[in, out] arg Parameter for the callout. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_delete_visitor( Thread_Control *executing, void *arg, const User_extensions_Table *callouts ); +/** + * @brief Starts a visitor. + * + * @param executing The currently executing thread. + * @param arg Parameter for the callout. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_start_visitor( Thread_Control *executing, void *arg, const User_extensions_Table *callouts ); +/** + * @brief Restarts a visitor. + * + * @param executing The currently executing thread. + * @param arg Parameter for the callout. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_restart_visitor( Thread_Control *executing, void *arg, const User_extensions_Table *callouts ); +/** + * @brief Calls the begin function of the thread callout for the visitor. + * + * @param executing The currently executing thread. + * @param arg This parameter is unused. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_begin_visitor( Thread_Control *executing, void *arg, const User_extensions_Table *callouts ); +/** + * @brief Calls the exitted function of the thread callout for the visitor. + * + * @param executing The currently executing thread. + * @param arg This parameter is unused. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_exitted_visitor( Thread_Control *executing, void *arg, @@ -166,12 +234,26 @@ typedef struct { Internal_errors_t error; } User_extensions_Fatal_context; +/** + * @brief Calls the fatal function of the thread callout for the visitor. + * + * @param executing The currently executing thread. + * @param arg Is used as the user extension fatal context. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Fatal_visitor( Thread_Control *executing, void *arg, const User_extensions_Table *callouts ); +/** + * @brief Terminates a visitor. + * + * @param executing The currently executing thread. + * @param arg This parameter is unused. + * @param callouts The user extension table for the operation. + */ void _User_extensions_Thread_terminate_visitor( Thread_Control *executing, void *arg, @@ -182,8 +264,8 @@ void _User_extensions_Thread_terminate_visitor( * @brief Iterates through all user extensions and calls the visitor for each. * * @param[in, out] arg The argument passed to the visitor. - * @param[in] visitor The visitor for each extension. - * @param[in] direction The iteration direction for dynamic extensions. + * @param visitor The visitor for each extension. + * @param direction The iteration direction for dynamic extensions. */ void _User_extensions_Iterate( void *arg, @@ -198,6 +280,14 @@ void _User_extensions_Iterate( */ /** @{ **/ +/** + * @brief Creates a thread. + * + * @param[out] created The thread to create. + * + * @retval true The operation succeeded. + * @retval false The operation failed. + */ static inline bool _User_extensions_Thread_create( Thread_Control *created ) { User_extensions_Thread_create_context ctx = { created, true }; @@ -211,6 +301,11 @@ static inline bool _User_extensions_Thread_create( Thread_Control *created ) return ctx.ok; } +/** + * @brief Deletes a thread. + * + * @param[out] created The thread to delete. + */ static inline void _User_extensions_Thread_delete( Thread_Control *deleted ) { _User_extensions_Iterate( @@ -220,6 +315,11 @@ static inline void _User_extensions_Thread_delete( Thread_Control *deleted ) ); } +/** + * @brief Starts a thread. + * + * @param created The thread to start. + */ static inline void _User_extensions_Thread_start( Thread_Control *started ) { _User_extensions_Iterate( @@ -229,6 +329,11 @@ static inline void _User_extensions_Thread_start( Thread_Control *started ) ); } +/** + * @brief Restarts a thread. + * + * @param created The thread to restart. + */ static inline void _User_extensions_Thread_restart( Thread_Control *restarted ) { _User_extensions_Iterate( @@ -238,6 +343,11 @@ static inline void _User_extensions_Thread_restart( Thread_Control *restarted ) ); } +/** + * @brief Begins a thread. + * + * @param created The thread to begin. + */ static inline void _User_extensions_Thread_begin( Thread_Control *executing ) { _User_extensions_Iterate( @@ -247,6 +357,12 @@ static inline void _User_extensions_Thread_begin( Thread_Control *executing ) ); } +/** + * @brief Switches the thread from the executing to the heir. + * + * @param executing The currently executing thread. + * @param heir The thread that will switch with @a executing. + */ static inline void _User_extensions_Thread_switch( Thread_Control *executing, Thread_Control *heir @@ -288,6 +404,11 @@ static inline void _User_extensions_Thread_switch( } } +/** + * @brief A user extension thread exitted. + * + * @param created The thread. + */ static inline void _User_extensions_Thread_exitted( Thread_Control *executing ) { _User_extensions_Iterate( @@ -297,6 +418,12 @@ static inline void _User_extensions_Thread_exitted( Thread_Control *executing ) ); } +/** + * @brief Forwards all visitors that there was a fatal failure. + * + * @param source The error source. + * @param error The error. + */ static inline void _User_extensions_Fatal( Internal_errors_Source source, Internal_errors_t error @@ -311,6 +438,11 @@ static inline void _User_extensions_Fatal( ); } +/** + * @brief Terminates the executing thread. + * + * @param executing The currently executing thread. + */ static inline void _User_extensions_Thread_terminate( Thread_Control *executing ) @@ -322,6 +454,11 @@ static inline void _User_extensions_Thread_terminate( ); } +/** + * @brief Disables interrupts and acquires the lock context. + * + * @param lock_context The lock context to acquire. + */ static inline void _User_extensions_Acquire( ISR_lock_Context *lock_context ) { _ISR_lock_ISR_disable_and_acquire( @@ -330,6 +467,11 @@ static inline void _User_extensions_Acquire( ISR_lock_Context *lock_context ) ); } +/** + * @brief Releases the lock context and enables interrupts. + * + * @param lock_context The lock context to release. + */ static inline void _User_extensions_Release( ISR_lock_Context *lock_context ) { _ISR_lock_Release_and_ISR_enable( @@ -338,6 +480,12 @@ static inline void _User_extensions_Release( ISR_lock_Context *lock_context ) ); } +/** + * @brief Destroys all user extension iterators of a thread. + * + * @param[in, out] the_thread The thread to destroy all user extension + * iterators of. + */ static inline void _User_extensions_Destroy_iterators( Thread_Control *the_thread ) -- cgit v1.2.3