diff options
author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2009-09-25 17:51:46 +0000 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2009-09-25 17:51:46 +0000 |
commit | c42d1a459be526a29aa6a013b38380498ef19317 (patch) | |
tree | 51a876b02390aad043b51ca27d91d593a48236bd /cpukit/score/include/rtems/score/userext.h | |
parent | 2009-09-25 Sebastian Huber <Sebastian.Huber@embedded-brains.de> (diff) | |
download | rtems-c42d1a459be526a29aa6a013b38380498ef19317.tar.bz2 |
2009-09-25 Sebastian Huber <Sebastian.Huber@embedded-brains.de>
* sapi/include/rtems/extension.h, sapi/src/extensiondelete.c,
sapi/src/extensionident.c, sapi/src/extensioncreate.c,
sapi/inline/rtems/extension.inl, score/include/rtems/score/userext.h,
score/src/userextthreaddelete.c, score/src/userext.c,
score/src/userextthreadcreate.c, score/src/userextremoveset.c,
score/src/userextthreadbegin.c, score/src/userextaddset.c,
score/src/userextthreadstart.c, score/src/userextthreadswitch.c,
score/src/userextthreadrestart.c: Documentation. The types
User_extensions_routine and rtems_extension are now deprecated.
Removed unused types User_extensions_thread_post_switch_extension and
rtems_task_post_switch_extension. Renamed _User_extensions_Add_API_set()
in _User_extensions_Add_set(). Renamed _User_extensions_Add_set() in
_User_extensions_Add_set_with_table().
* score/src/userextaddapiset.c: Removed file.
* score/Makefile.am: Update.
Diffstat (limited to '')
-rw-r--r-- | cpukit/score/include/rtems/score/userext.h | 424 |
1 files changed, 197 insertions, 227 deletions
diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h index 938630eb0e..65fc1881c9 100644 --- a/cpukit/score/include/rtems/score/userext.h +++ b/cpukit/score/include/rtems/score/userext.h @@ -1,9 +1,9 @@ -/** - * @file rtems/score/userext.h +/** + * @file + * + * @ingroup ScoreUserExt * - * This include file contains all information about user extensions. This - * Handler provides mechanisms which can be used to initialize and manipulate - * all user extensions. + * @brief User Extension Handler API. */ /* @@ -20,14 +20,6 @@ #ifndef _RTEMS_SCORE_USEREXT_H #define _RTEMS_SCORE_USEREXT_H -/** - * @defgroup ScoreUserExt User Extension Handler - * - * This handler encapsulates functionality related to the management of - * the user extensions to the SuperCore that are available to the user. - */ -/**@{*/ - #ifdef __cplusplus extern "C" { #endif @@ -36,310 +28,288 @@ extern "C" { #include <rtems/score/chain.h> #include <rtems/score/thread.h> -/*@}*/ - -/** @defgroup ScoreUserExtStruct User Extension Handler Structures - * - * The following records defines the User Extension Table. - * This table defines the application dependent routines which - * are invoked at critical points in the life of each thread and - * the system as a whole. - */ -/*@{*/ - -/** - * This type indicates the return type of a user extension method. - */ -typedef void User_extensions_routine; +typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; /** - * This type defines the prototype of a thread creation extension handler. - * The handler is passed the thread executing and the thread being created. + * @defgroup ScoreUserExt User Extension Handler + * + * @ingroup Score + * + * @brief The User Extension Handler provides invocation of application + * dependent routines at critical points in the life of each thread and the + * system as a whole. + * + * @{ */ -typedef bool ( *User_extensions_thread_create_extension )( - Thread_Control *, - Thread_Control * - ); /** - * This type defines the prototype of a thread deletion extension handler. - * The handler is passed the thread executing and the thread being deleted. + * @brief Task create extension. + * + * It corresponds to _Thread_Initialize() (used by the rtems_task_create() + * directive). The first parameter points to the currently executing thread + * which created the new thread. The second parameter points to the created + * thread. + * + * It is invoked after the new thread has been completely initialized, but + * before it is placed on a ready chain. + * + * Thread dispatching may be disabled. It can be assumed that the executing + * thread locked the allocator mutex. They only exception is the creation of + * the idle thread. In this case the allocator mutex is not locked. + * + * The user extension is expected to return @c true if it successfully + * executed, and @c false otherwise. A thread create user extension will + * frequently attempt to allocate resources. If this allocation fails, then the + * extension should return @c false and the entire task create operation will + * fail. */ -typedef User_extensions_routine ( *User_extensions_thread_delete_extension )( - Thread_Control *, - Thread_Control * - ); +typedef bool ( *User_extensions_thread_create_extension )( + Thread_Control *, + Thread_Control * +); /** - * This type defines the prototype of thread starting extension handler. - * The handler is passed the thread executing and the thread being started. + * @brief Task delete extension. + * + * It corresponds to _Thread_Close() (used by the rtems_task_delete() + * directive). The first parameter points to the currently executing thread + * which deleted the thread. The second parameter points to the deleted + * thread. + * + * It is invoked before all resources of the thread are deleted. + * + * Thread dispatching is enabled. The executing thread locked the allocator + * mutex. */ -typedef User_extensions_routine ( *User_extensions_thread_start_extension )( - Thread_Control *, - Thread_Control * - ); +typedef void( *User_extensions_thread_delete_extension )( + Thread_Control *, + Thread_Control * +); /** - * This type defines the prototype of a thread restarting extension handler. - * The handler is passed the thread executing and the thread being restarted. + * @brief Task start extension. + * + * It corresponds to _Thread_Start() (used by the rtems_task_start() + * directive). The first parameter points to the currently executing thread + * which started the thread. The second parameter points to the started + * thread. + * + * It is invoked after the environment of the thread has been loaded and the + * thread has been made ready. + * + * Thread dispatching is disabled. The executing thread is not the holder of + * the allocator mutex. */ -typedef User_extensions_routine ( *User_extensions_thread_restart_extension )( - Thread_Control *, - Thread_Control * - ); +typedef void( *User_extensions_thread_start_extension )( + Thread_Control *, + Thread_Control * +); /** - * This type defines the prototype of thread context switch extension handler. - * The handler is passed the thread currently executing and the thread being - * switched to. + * @brief Task restart extension. + * + * It corresponds to _Thread_Restart() (used by the rtems_task_restart() + * directive). The first parameter points to the currently executing thread + * which restarted the thread. The second parameter points to the restarted + * thread. + * + * It is invoked after the environment of the thread has been loaded and the + * thread has been made ready. + * + * Thread dispatching is disabled. The executing thread is not the holder of + * the allocator mutex. */ -typedef User_extensions_routine ( *User_extensions_thread_switch_extension )( - Thread_Control *, - Thread_Control * - ); +typedef void( *User_extensions_thread_restart_extension )( + Thread_Control *, + Thread_Control * +); /** - * This type defines the prototype of a post context switch extension handler. - * The handler is passed the thread thread being switched to. + * @brief Task switch extension. + * + * It corresponds to _Thread_Dispatch(). The first parameter points to the + * currently executing thread. The second parameter points to the heir thread. + * + * It is invoked before the context switch from the executing to the heir + * thread. + * + * Thread dispatching is disabled. The state of the allocator mutex is + * arbitrary. + * + * The context switches initiated through _Thread_Start_multitasking() and + * _Thread_Stop_multitasking() are not covered by this extension. The + * executing thread may run with a minimal setup, for example with a freed task + * stack. */ -typedef User_extensions_routine (*User_extensions_thread_post_switch_extension)( - Thread_Control * - ); +typedef void( *User_extensions_thread_switch_extension )( + Thread_Control *, + Thread_Control * +); /** - * This type defines the prototype of a thread beginning to execute - * extension handler. The handler is passed the thread executing. This - * extension is executed in the context of the beginning thread. + * @brief Task begin extension. + * + * It corresponds to _Thread_Handler(). The first parameter points to the + * currently executing thread which begins now execution. + * + * Thread dispatching is disabled. The executing thread is not the holder of + * the allocator mutex. */ -typedef User_extensions_routine ( *User_extensions_thread_begin_extension )( - Thread_Control * - ); +typedef void( *User_extensions_thread_begin_extension )( + Thread_Control * +); /** - * This type defines the prototype of a thread exiting extension handler. - * The handler is passed the thread exiting. + * @brief Task exitted extension. + * + * It corresponds to _Thread_Handler(). The first parameter points to the + * currently executing thread which exitted before. + * + * Thread dispatching is disabled. The state of the allocator mutex is + * arbitrary. */ -typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )( - Thread_Control * - ); +typedef void( *User_extensions_thread_exitted_extension )( + Thread_Control * +); /** - * This type defines the prototype of the fatal error extension handler. - * The handler is passed an indicator of the source of the fatal error, - * whether it is internal to RTEMS and an error code. + * @brief Task fatal error extension. + * + * It corresponds to _Internal_error_Occurred() (used by the + * rtems_fatal_error_occurred() directive). The first parameter contains the + * internal error source. The second parameter indicates if it was an internal + * error. The third parameter contains the error code. + * + * This extension should not call any RTEMS directives. */ -typedef User_extensions_routine ( *User_extensions_fatal_extension )( - Internal_errors_Source /* the_source */, - bool /* is_internal */, - uint32_t /* the_error */ - ); +typedef void( *User_extensions_fatal_extension )( + Internal_errors_Source, + bool, + uint32_t +); /** - * This type defines a set of user extensions. + * @brief User extension table. */ typedef struct { - /** This field is the thread creation handler. */ - User_extensions_thread_create_extension thread_create; - /** This field is the thread starting handler. */ - User_extensions_thread_start_extension thread_start; - /** This field is the thread restarting handler. */ - User_extensions_thread_restart_extension thread_restart; - /** This field is the thread deleting handler */ - User_extensions_thread_delete_extension thread_delete; - /** This field is thread context switch handler. */ - User_extensions_thread_switch_extension thread_switch; - /** This field is the thread beginning handler. */ - User_extensions_thread_begin_extension thread_begin; - /** This field is thread exiting handler. */ - User_extensions_thread_exitted_extension thread_exitted; - /** This field is the fatal error extension. */ - User_extensions_fatal_extension fatal; + User_extensions_thread_create_extension thread_create; + User_extensions_thread_start_extension thread_start; + User_extensions_thread_restart_extension thread_restart; + User_extensions_thread_delete_extension thread_delete; + User_extensions_thread_switch_extension thread_switch; + User_extensions_thread_begin_extension thread_begin; + User_extensions_thread_exitted_extension thread_exitted; + User_extensions_fatal_extension fatal; } User_extensions_Table; /** - * This is used to manage the list of switch handlers. They are managed - * separately from other extensions for performance reasons. + * @brief Manages the switch callouts. + * + * They are managed separately from other extensions for performance reasons. */ typedef struct { - /** This field is a Chain Node structure and allows this to be placed on - * chains for set management. - */ Chain_Node Node; - /** This field is the thread switch extension. */ User_extensions_thread_switch_extension thread_switch; } User_extensions_Switch_control; /** - * This is used to manage each user extension set. - * The switch control is part of the extensions control even - * if not used due to the extension not having a switch - * handler. + * @brief Manages each user extension set. + * + * The switch control is part of the extensions control even if not used due to + * the extension not having a switch handler. */ typedef struct { - /** This field is a Chain Node structure and allows this to be placed on - * chains for set management. - */ Chain_Node Node; - /** This field is the thread switch user extension. */ User_extensions_Switch_control Switch; - /** This field is the rest of this user extension's entry points. */ User_extensions_Table Callouts; } User_extensions_Control; /** - * This is used to manage the list of active extensions. + * @brief List of active extensions. */ SCORE_EXTERN Chain_Control _User_extensions_List; /** - * This is used to manage a chain of user extension task - * switch nodes. + * @brief List of active task switch extensions. */ SCORE_EXTERN Chain_Control _User_extensions_Switches_list; -/*@}*/ -/** @addtogroup ScoreUserExt */ - -/*@{*/ - -/** @brief User extensions Handler Initialization +/** + * @name Extension Maintainance * - * This routine performs the initialization necessary for this handler. + * @{ */ -void _User_extensions_Handler_initialization(void); -/** @brief User extensions Add to API extension set - * - * This routine is used to add an API extension set to the active list. - * - * @param[in] the_extension is the extension set to add - */ -void _User_extensions_Add_API_set ( - User_extensions_Control *the_extension +void _User_extensions_Handler_initialization( void ); + +void _User_extensions_Add_set( + User_extensions_Control *extension ); -/** @brief User extensions Add extension set - * - * This routine is used to add a user extension set to the active list. - * - * @param[in] the_extension is the extension set to add - * @param[in] extension_table is the user's extension set - */ -void _User_extensions_Add_set ( - User_extensions_Control *the_extension, +RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table( + User_extensions_Control *extension, User_extensions_Table *extension_table -); +) +{ + extension->Callouts = *extension_table; -/** - * This routine is used to remove a user extension set from the active list. - */ -void _User_extensions_Remove_set ( - User_extensions_Control *the_extension + _User_extensions_Add_set( extension ); +} + +void _User_extensions_Remove_set( + User_extensions_Control *extension ); -/** @brief User extensions Thread create - * - * This routine is used to invoke the user extension for - * the thread creation operate. - * - * @param[in] the_thread is the thread being created. +/** @} */ + +/** + * @name Extension Callout Dispatcher * - * @return This method returns true if the user extension executed - * successfully. + * @{ */ -bool _User_extensions_Thread_create ( - Thread_Control *the_thread + +bool _User_extensions_Thread_create( + Thread_Control *created ); -/** @brief User extensions Thread delete - * - * This routine is used to invoke the user extension for - * the thread deletion operation. - * - * @param[in] the_thread is the thread being deleted. - */ -void _User_extensions_Thread_delete ( - Thread_Control *the_thread +void _User_extensions_Thread_delete( + Thread_Control *deleted ); -/** @brief User extensions Thread start - * - * This routine is used to invoke the user extension for - * the thread start operation. - * - * @param[in] the_thread is the thread being started. - */ -void _User_extensions_Thread_start ( - Thread_Control *the_thread +void _User_extensions_Thread_start( + Thread_Control *started ); -/** @brief User extensions Thread restart - * - * This routine is used to invoke the user extension for - * the thread restart operation. - * - * @param[in] the_thread is the thread being restarted. - */ -void _User_extensions_Thread_restart ( - Thread_Control *the_thread +void _User_extensions_Thread_restart( + Thread_Control *restarted ); -/** @brief User extensions Thread begin - * - * This routine is used to invoke the user extension which - * is invoked when a thread begins. - * - * @param[in] executing is the thread beginning to execute. - */ -void _User_extensions_Thread_begin ( +void _User_extensions_Thread_begin( Thread_Control *executing ); - -/** @brief User extensions Thread switch - * - * This routine is used to invoke the user extension which - * is invoked when a context switch occurs. - * - * @param[in] executing is the thread currently executing. - * @param[in] heir is the thread which will execute. - */ -void _User_extensions_Thread_switch ( +void _User_extensions_Thread_switch( Thread_Control *executing, Thread_Control *heir ); -/** @brief User extensions Thread exitted - * - * This routine is used to invoke the user extension which - * is invoked when a thread exits. - * - * @param[in] executing is the thread voluntarily exiting. - */ -void _User_extensions_Thread_exitted ( +void _User_extensions_Thread_exitted( Thread_Control *executing ); -/** @brief User extensions Fatal - * - * This routine is used to invoke the user extension invoked - * when a fatal error occurs. - * - * @param[in] the_source is the source of the fatal error. - * @param[in] is_internal is true if the error originated inside RTEMS. - * @param[in] the_error is an indication of the actual error. - */ -void _User_extensions_Fatal ( - Internal_errors_Source the_source, - bool is_internal, - uint32_t the_error +void _User_extensions_Fatal( + Internal_errors_Source source, + bool is_internal, + uint32_t error ); +/** @} */ + +/** @} */ + #ifdef __cplusplus } #endif -/**@}*/ - #endif /* end of include file */ |