diff options
-rw-r--r-- | cpukit/ChangeLog | 18 | ||||
-rw-r--r-- | cpukit/sapi/include/rtems/extension.h | 251 | ||||
-rw-r--r-- | cpukit/sapi/inline/rtems/extension.inl | 49 | ||||
-rw-r--r-- | cpukit/sapi/src/extensioncreate.c | 31 | ||||
-rw-r--r-- | cpukit/sapi/src/extensiondelete.c | 26 | ||||
-rw-r--r-- | cpukit/sapi/src/extensionident.c | 29 | ||||
-rw-r--r-- | cpukit/score/Makefile.am | 2 | ||||
-rw-r--r-- | cpukit/score/include/rtems/score/userext.h | 424 | ||||
-rw-r--r-- | cpukit/score/src/userext.c | 14 | ||||
-rw-r--r-- | cpukit/score/src/userextaddset.c | 27 | ||||
-rw-r--r-- | cpukit/score/src/userextremoveset.c | 12 | ||||
-rw-r--r-- | cpukit/score/src/userextthreadbegin.c | 24 | ||||
-rw-r--r-- | cpukit/score/src/userextthreadcreate.c | 13 | ||||
-rw-r--r-- | cpukit/score/src/userextthreaddelete.c | 13 | ||||
-rw-r--r-- | cpukit/score/src/userextthreadrestart.c | 14 | ||||
-rw-r--r-- | cpukit/score/src/userextthreadstart.c | 14 | ||||
-rw-r--r-- | cpukit/score/src/userextthreadswitch.c | 12 |
17 files changed, 510 insertions, 463 deletions
diff --git a/cpukit/ChangeLog b/cpukit/ChangeLog index 5d9bc7eff2..190e5ea82d 100644 --- a/cpukit/ChangeLog +++ b/cpukit/ChangeLog @@ -1,5 +1,23 @@ 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. + +2009-09-25 Sebastian Huber <Sebastian.Huber@embedded-brains.de> + * score/src/heap.c, score/include/rtems/score/heap.h: Reduced alignment requirement for CPU_ALIGNMENT from four to two. diff --git a/cpukit/sapi/include/rtems/extension.h b/cpukit/sapi/include/rtems/extension.h index 0d62c1df55..b7b09126a5 100644 --- a/cpukit/sapi/include/rtems/extension.h +++ b/cpukit/sapi/include/rtems/extension.h @@ -1,18 +1,12 @@ /** - * @file rtems/extension.h + * @file + * + * @ingroup ClassicUserExtensions + * + * @brief User Extensions API. */ /* - * This include file contains all the constants, structures, and - * prototypes associated with the User Extension Manager. This manager - * provides a mechanism for manipulating sets of user-defined extensions. - * - * Directives provided are: - * - * + create user extension set - * + get ID of user extension set - * + delete user extension set - * * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * @@ -39,97 +33,220 @@ extern "C" { #include <rtems/rtems/status.h> #include <rtems/rtems/types.h> -/* - * Extension related types +SAPI_EXT_EXTERN Objects_Information _Extension_Information; + +typedef struct { + Objects_Control Object; + User_extensions_Control Extension; +} Extension_Control; + +void _Extension_Manager_initialization(void); + +typedef User_extensions_routine + rtems_extension RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; + +/** + * @defgroup ClassicUserExtensions User Extensions + * + * @ingroup ClassicRTEMS + * + * @brief The User Extensions Manager allows the application developer to + * augment the executive by allowing them to supply extension routines which + * are invoked at critical system events. + * + * @section ClassicUserExtensionsSets Extension Sets + * + * An @ref User_extensions_Table "extension set" is defined as a set of + * routines which are invoked at each of the critical system events at which + * user extension routines are invoked. Together a set of these routines + * typically perform a specific functionality such as performance monitoring or + * debugger support. + * + * RTEMS allows the user to have multiple extension sets active at the same + * time. First, a single static extension set may be defined as the + * application's User Extension Table which is included as part of the + * Configuration Table. This extension set is active for the entire life of the + * system and may not be deleted. This extension set is especially important + * because it is the only way the application can provided a fatal error + * extension which is invoked if RTEMS fails during the + * rtems_initialize_data_structures() directive. The static extension set is + * optional and may be configured as @c NULL if no static extension set is + * required. + * + * Second, the user can install dynamic extensions using the + * rtems_extension_create() directive. These extensions are RTEMS objects in + * that they have a name, an ID, and can be dynamically created and deleted. In + * contrast to the static extension set, these extensions can only be created + * and installed after the rtems_initialize_data_structures() directive + * successfully completes execution. Dynamic extensions are useful for + * encapsulating the functionality of an extension set. For example, the + * application could use extensions to manage a special coprocessor, do + * performance monitoring, and to do stack bounds checking. Each of these + * extension sets could be written and installed independently of the others. + * + * All user extensions are optional and RTEMS places no naming restrictions on + * the user. The user extension entry points are copied into an internal RTEMS + * structure. This means the user does not need to keep the table after + * creating it, and changing the handler entry points dynamically in a table + * once created has no effect. Creating a table local to a function can save + * space in space limited applications. + * + * Extension switches do not effect the context switch overhead if no switch + * handler is installed. + * + * @section ClassicUserExtensionsTCB Task Control Block Area + * + * RTEMS provides for a pointer to a user-defined data area for each extension + * set to be linked to each task's control block (TCB). This area is only + * available for the dynamic extensions. This set of pointers is an extension + * of the TCB and can be used to store additional data required by the user's + * extension functions. It is also possible for a user extension to utilize the + * notepad locations associated with each task although this may conflict with + * application usage of those particular notepads. + * + * The TCB extension is an array of pointers in the TCB. The index into the + * table can be obtained from the extension identifier returned when the + * extension is created: + * + * @code + * rtems_tcb *task = some_task; + * size_t index = rtems_object_id_get_index(extension_id); + * void *extension_data = task->extensions [index]; + * @endcode + * + * The number of pointers in the area is the same as the number of user + * extension sets configured. This allows an application to augment the TCB + * with user-defined information. For example, an application could implement + * task profiling by storing timing statistics in the TCB's extended memory + * area. When a task context switch is being executed, the task switch + * extension could read a real-time clock to calculate how long the task being + * swapped out has run as well as timestamp the starting time for the task + * being swapped in. + * + * If used, the extended memory area for the TCB should be allocated and the + * TCB extension pointer should be set at the time the task is created or + * started by either the task create or task start extension. The application + * is responsible for managing this extended memory area for the TCBs. The + * memory may be reinitialized by the task restart extension and should be + * deallocated by the task delete extension when the task is deleted. Since the + * TCB extension buffers would most likely be of a fixed size, the RTEMS + * partition manager could be used to manage the application's extended memory + * area. The application could create a partition of fixed size TCB extension + * buffers and use the partition manager's allocation and deallocation + * directives to obtain and release the extension buffers. + * + * @section ClassicUserExtensionsOrder Order of Invokation + * + * When one of the critical system events occur, the user extensions are + * invoked in either @a forward or @a reverse order. Forward order indicates + * that the static extension set is invoked followed by the dynamic extension + * sets in the order in which they were created. Reverse order means that the + * dynamic extension sets are invoked in the opposite of the order in which + * they were created followed by the static extension set. By invoking the + * extension sets in this order, extensions can be built upon one another. At + * the following system events, the extensions are invoked in forward order: + * + * - Task creation + * - Task initiation + * - Task reinitiation + * - Task deletion + * - Task context switch + * - Post task context switch + * - Task begins to execute + * + * At the following system events, the extensions are invoked in reverse order: + * + * - Task deletion + * - Fatal error detection + * + * At these system events, the extensions are invoked in reverse order to + * insure that if an extension set is built upon another, the more complicated + * extension is invoked before the extension set it is built upon. For example, + * by invoking the static extension set last it is known that the "system" + * fatal error extension will be the last fatal error extension executed. + * Another example is use of the task delete extension by the Standard C + * Library. Extension sets which are installed after the Standard C Library + * will operate correctly even if they utilize the C Library because the C + * Library's task delete extension is invoked after that of the other + * extensions. + * + * @{ */ -typedef User_extensions_routine rtems_extension; typedef User_extensions_thread_create_extension rtems_task_create_extension; typedef User_extensions_thread_delete_extension rtems_task_delete_extension; typedef User_extensions_thread_start_extension rtems_task_start_extension; typedef User_extensions_thread_restart_extension rtems_task_restart_extension; typedef User_extensions_thread_switch_extension rtems_task_switch_extension; -typedef User_extensions_thread_post_switch_extension - rtems_task_post_switch_extension; typedef User_extensions_thread_begin_extension rtems_task_begin_extension; typedef User_extensions_thread_exitted_extension rtems_task_exitted_extension; typedef User_extensions_fatal_extension rtems_fatal_extension; typedef User_extensions_Table rtems_extensions_table; -/* - * The following defines the information control block used to manage - * this class of objects. - */ - -SAPI_EXT_EXTERN Objects_Information _Extension_Information; - -/* - * The following records define the control block used to manage - * each extension. - */ - -typedef struct { - Objects_Control Object; - User_extensions_Control Extension; -} Extension_Control; - -/* - * _Extension_Manager_initialization +/** + * @brief Creates an extension set object. * - * DESCRIPTION: + * This directive creates a extension set object from the extension table + * @a extension_table. The assigned extension set identifier is returned in + * @a id. The identifier is used to access this extension set in other + * extension set related directives. The name @a name will be assigned to the + * extension set object. * - * This routine performs the initialization necessary for this manager. - */ - -void _Extension_Manager_initialization(void); - -/* - * rtems_extension_create + * Newly created extension sets are immediately installed and are invoked upon + * the next system event supporting an extension. * - * DESCRIPTION: + * This directive will not cause the calling task to be preempted. * - * This routine implements the rtems_extension_create directive. The - * extension will have the name name. The entry points of the - * routines which constitute this extension set are in EXTENSION_TABLE. - * It returns the id of the created extension in ID. + * @retval RTEMS_SUCCESSFUL Extension set created successfully. + * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL. + * @retval RTEMS_INVALID_NAME Invalid extension set name. + * @retval RTEMS_TOO_MANY Too many extension sets created. */ - rtems_status_code rtems_extension_create( rtems_name name, rtems_extensions_table *extension_table, - Objects_Id *id + rtems_id *id ); -/* - * rtems_extension_ident +/** + * @brief Identifies an extension set object by a name. + * + * This directive obtains an extension set identifier in @a id associated with + * the extension set name @a name. If the extension set name is not unique, + * then the extension set identifier will match one of the extension sets with + * that name. However, this extension set identifier is not guaranteed to + * correspond to the desired extension set. The extension set identifier is + * used to access this extension set in other extension set related directives. * - * DESCRIPTION: + * This directive will not cause the calling task to be preempted. * - * This routine implements the rtems_extension_ident directive. - * This directive returns the extension ID associated with name. - * If more than one extension is named name, then the extension - * to which the ID belongs is arbitrary. + * @retval RTEMS_SUCCESSFUL Extension set identified successfully. + * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL. + * @retval RTEMS_INVALID_NAME Extension set name not found or invalid name. */ - rtems_status_code rtems_extension_ident( - rtems_name name, - Objects_Id *id + rtems_name name, + rtems_id *id ); -/* - * rtems_extension_delete +/** + * @brief Deletes an extension set object specified by the identifier @a id. + * + * Any subsequent references to the extension's name and identifier are + * invalid. * - * DESCRIPTION: + * This directive will not cause the calling task to be preempted. * - * This routine implements the rtems_extension_delete directive. The - * extension indicated by ID is deleted. + * @retval RTEMS_SUCCESSFUL Extension set deleted successfully. + * @retval RTEMS_INVALID_ID Invalid extension set identifier. */ - rtems_status_code rtems_extension_delete( - Objects_Id id + rtems_id id ); +/** @} */ + #ifndef __RTEMS_APPLICATION__ #include <rtems/extension.inl> #endif diff --git a/cpukit/sapi/inline/rtems/extension.inl b/cpukit/sapi/inline/rtems/extension.inl index 5b516b9f56..36005b7d7f 100644 --- a/cpukit/sapi/inline/rtems/extension.inl +++ b/cpukit/sapi/inline/rtems/extension.inl @@ -1,8 +1,9 @@ /** - * @file rtems/extension.inl + * @file * - * This file contains the static inline implementation of the inlined routines - * from the Extension Manager. + * @ingroup ClassicUserExtensions + * + * @brief User Extensions API. */ /* @@ -19,31 +20,11 @@ #ifndef __EXTENSION_MANAGER_inl #define __EXTENSION_MANAGER_inl -/*PAGE - * - * _Extension_Allocate - * - * DESCRIPTION: - * - * This function allocates a extension control block from - * the inactive chain of free extension control blocks. - */ - RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Allocate( void ) { return (Extension_Control *) _Objects_Allocate( &_Extension_Information ); } -/*PAGE - * - * _Extension_Free - * - * DESCRIPTION: - * - * This routine frees a extension control block to the - * inactive chain of free extension control blocks. - */ - RTEMS_INLINE_ROUTINE void _Extension_Free ( Extension_Control *the_extension ) @@ -51,19 +32,6 @@ RTEMS_INLINE_ROUTINE void _Extension_Free ( _Objects_Free( &_Extension_Information, &the_extension->Object ); } -/*PAGE - * - * _Extension_Get - * - * DESCRIPTION: - * - * This function maps extension IDs to extension control blocks. - * If ID corresponds to a local extension, then it returns - * the extension control pointer which maps to ID and location - * is set to OBJECTS_LOCAL. Otherwise, location is set - * to OBJECTS_ERROR and the returned value is undefined. - */ - RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Get ( Objects_Id id, Objects_Locations *location @@ -73,15 +41,6 @@ RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Get ( _Objects_Get( &_Extension_Information, id, location ); } -/*PAGE - * - * _Extension_Is_null - * - * DESCRIPTION: - * - * This function returns TRUE if the_extension is NULL and FALSE otherwise. - */ - RTEMS_INLINE_ROUTINE bool _Extension_Is_null ( Extension_Control *the_extension ) diff --git a/cpukit/sapi/src/extensioncreate.c b/cpukit/sapi/src/extensioncreate.c index d2e146d6eb..9e939f57af 100644 --- a/cpukit/sapi/src/extensioncreate.c +++ b/cpukit/sapi/src/extensioncreate.c @@ -1,6 +1,12 @@ -/* - * Extension Manager -- rtems_extension_create +/** + * @file + * + * @ingroup ClassicUserExtensions * + * @brief User Extensions Implementation. + */ + +/* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). * @@ -21,27 +27,10 @@ #include <rtems/score/thread.h> #include <rtems/extension.h> -/*PAGE - * - * rtems_extension_create - * - * This directive creates a extension and performs some initialization. - * - * Input parameters: - * name - extension name - * extension_table - pointer to extension set information - * id - pointer to extension id - * - * Output parameters: - * id - extension id - * RTEMS_SUCCESSFUL - if successful - * error code - if unsuccessful - */ - rtems_status_code rtems_extension_create( rtems_name name, rtems_extensions_table *extension_table, - Objects_Id *id + rtems_id *id ) { Extension_Control *the_extension; @@ -61,7 +50,7 @@ rtems_status_code rtems_extension_create( return RTEMS_TOO_MANY; } - _User_extensions_Add_set( &the_extension->Extension, extension_table ); + _User_extensions_Add_set_with_table( &the_extension->Extension, extension_table ); _Objects_Open( &_Extension_Information, diff --git a/cpukit/sapi/src/extensiondelete.c b/cpukit/sapi/src/extensiondelete.c index dd97859cd2..02e08767fd 100644 --- a/cpukit/sapi/src/extensiondelete.c +++ b/cpukit/sapi/src/extensiondelete.c @@ -1,6 +1,12 @@ -/* - * Extension Manager -- rtems_extension_delete +/** + * @file + * + * @ingroup ClassicUserExtensions * + * @brief User Extensions Implementation. + */ + +/* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). * @@ -21,22 +27,8 @@ #include <rtems/score/thread.h> #include <rtems/extension.h> -/*PAGE - * - * rtems_extension_delete - * - * This directive allows a thread to delete a extension. - * - * Input parameters: - * id - extension id - * - * Output parameters: - * RTEMS_SUCCESSFUL - if successful - * error code - if unsuccessful - */ - rtems_status_code rtems_extension_delete( - Objects_Id id + rtems_id id ) { Extension_Control *the_extension; diff --git a/cpukit/sapi/src/extensionident.c b/cpukit/sapi/src/extensionident.c index 767deee166..626c106b0b 100644 --- a/cpukit/sapi/src/extensionident.c +++ b/cpukit/sapi/src/extensionident.c @@ -1,6 +1,12 @@ -/* - * Extension Manager -- rtems_extension_ident +/** + * @file + * + * @ingroup ClassicUserExtensions * + * @brief User Extensions Implementation. + */ + +/* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). * @@ -21,26 +27,9 @@ #include <rtems/score/thread.h> #include <rtems/extension.h> -/*PAGE - * - * rtems_extension_ident - * - * This directive returns the system ID associated with - * the extension name. - * - * Input parameters: - * name - user defined message queue name - * id - pointer to extension id - * - * Output parameters: - * *id - message queue id - * RTEMS_SUCCESSFUL - if successful - * error code - if unsuccessful - */ - rtems_status_code rtems_extension_ident( rtems_name name, - Objects_Id *id + rtems_id *id ) { Objects_Name_or_id_lookup_errors status; diff --git a/cpukit/score/Makefile.am b/cpukit/score/Makefile.am index 127a4e7756..d2375e2d13 100644 --- a/cpukit/score/Makefile.am +++ b/cpukit/score/Makefile.am @@ -196,7 +196,7 @@ libscore_a_SOURCES += src/watchdog.c src/watchdogadjust.c \ src/watchdogtickle.c src/watchdogreport.c src/watchdogreportchain.c ## USEREXT_C_FILES -libscore_a_SOURCES += src/userextaddapiset.c src/userextaddset.c \ +libscore_a_SOURCES += src/userextaddset.c \ src/userext.c src/userextremoveset.c src/userextthreadbegin.c \ src/userextthreadcreate.c src/userextthreaddelete.c \ src/userextthreadrestart.c src/userextthreadstart.c \ 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 */ diff --git a/cpukit/score/src/userext.c b/cpukit/score/src/userext.c index 190c15f85f..9b778b6300 100644 --- a/cpukit/score/src/userext.c +++ b/cpukit/score/src/userext.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). @@ -19,10 +27,6 @@ #include <rtems/score/wkspace.h> #include <string.h> -/** - * This routine performs the initialization necessary for this handler. - */ - void _User_extensions_Handler_initialization(void) { User_extensions_Control *extension; @@ -49,7 +53,7 @@ void _User_extensions_Handler_initialization(void) ); for ( i = 0 ; i < number_of_extensions ; i++ ) { - _User_extensions_Add_set (extension, &initial_extensions[i]); + _User_extensions_Add_set_with_table (extension, &initial_extensions[i]); extension++; } } diff --git a/cpukit/score/src/userextaddset.c b/cpukit/score/src/userextaddset.c index 516477a50e..fd732e73c4 100644 --- a/cpukit/score/src/userextaddset.c +++ b/cpukit/score/src/userextaddset.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,28 +24,19 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/** - * This routine is used to add a user extension set to the active list. - * - * @note Must be before _User_extensions_Handler_initialization to - * ensure proper inlining. - */ - -void _User_extensions_Add_set ( - User_extensions_Control *the_extension, - User_extensions_Table *extension_table +void _User_extensions_Add_set( + User_extensions_Control *the_extension ) { - the_extension->Callouts = *extension_table; - _Chain_Append( &_User_extensions_List, &the_extension->Node ); /* * If a switch handler is present, append it to the switch chain. */ - if ( extension_table->thread_switch != NULL ) { - the_extension->Switch.thread_switch = extension_table->thread_switch; + if ( the_extension->Callouts.thread_switch != NULL ) { + the_extension->Switch.thread_switch = + the_extension->Callouts.thread_switch; _Chain_Append( &_User_extensions_Switches_list, &the_extension->Switch.Node diff --git a/cpukit/score/src/userextremoveset.c b/cpukit/score/src/userextremoveset.c index dcff2ef626..4466007c25 100644 --- a/cpukit/score/src/userextremoveset.c +++ b/cpukit/score/src/userextremoveset.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,10 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/** - * This routine is used to remove a user extension set from the active list. - */ - void _User_extensions_Remove_set ( User_extensions_Control *the_extension ) diff --git a/cpukit/score/src/userextthreadbegin.c b/cpukit/score/src/userextthreadbegin.c index 7c36604d2a..eacdc15706 100644 --- a/cpukit/score/src/userextthreadbegin.c +++ b/cpukit/score/src/userextthreadbegin.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,12 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/*PAGE - * - * _User_extensions_Thread_begin - * - */ - void _User_extensions_Thread_begin ( Thread_Control *executing ) @@ -40,11 +42,6 @@ void _User_extensions_Thread_begin ( } } -/*PAGE - * - * _User_extensions_Thread_exitted - */ - void _User_extensions_Thread_exitted ( Thread_Control *executing ) @@ -63,11 +60,6 @@ void _User_extensions_Thread_exitted ( } } -/*PAGE - * - * _User_extensions_Fatal - */ - void _User_extensions_Fatal ( Internal_errors_Source the_source, bool is_internal, diff --git a/cpukit/score/src/userextthreadcreate.c b/cpukit/score/src/userextthreadcreate.c index 2b6c3f21c7..b7e7e6e855 100644 --- a/cpukit/score/src/userextthreadcreate.c +++ b/cpukit/score/src/userextthreadcreate.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,11 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/*PAGE - * - * _User_extensions_Thread_create - */ - bool _User_extensions_Thread_create ( Thread_Control *the_thread ) diff --git a/cpukit/score/src/userextthreaddelete.c b/cpukit/score/src/userextthreaddelete.c index 4f7214805b..393580f3ab 100644 --- a/cpukit/score/src/userextthreaddelete.c +++ b/cpukit/score/src/userextthreaddelete.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,11 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/*PAGE - * - * _User_extensions_Thread_delete - */ - void _User_extensions_Thread_delete ( Thread_Control *the_thread ) diff --git a/cpukit/score/src/userextthreadrestart.c b/cpukit/score/src/userextthreadrestart.c index d8af932cf2..f159c8bb0e 100644 --- a/cpukit/score/src/userextthreadrestart.c +++ b/cpukit/score/src/userextthreadrestart.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,12 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/*PAGE - * - * _User_extensions_Thread_restart - * - */ - void _User_extensions_Thread_restart ( Thread_Control *the_thread ) diff --git a/cpukit/score/src/userextthreadstart.c b/cpukit/score/src/userextthreadstart.c index 1534571344..e6364e158a 100644 --- a/cpukit/score/src/userextthreadstart.c +++ b/cpukit/score/src/userextthreadstart.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,12 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/*PAGE - * - * _User_extensions_Thread_start - * - */ - void _User_extensions_Thread_start ( Thread_Control *the_thread ) diff --git a/cpukit/score/src/userextthreadswitch.c b/cpukit/score/src/userextthreadswitch.c index 2a88c9f4f9..e7896e79a0 100644 --- a/cpukit/score/src/userextthreadswitch.c +++ b/cpukit/score/src/userextthreadswitch.c @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup ScoreUserExt + * + * @brief User Extension Handler implementation. + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,10 +24,6 @@ #include <rtems/system.h> #include <rtems/score/userext.h> -/** - * This routine is used to invoke the user extension which - * is invoked when a context switch occurs. - */ void _User_extensions_Thread_switch ( Thread_Control *executing, Thread_Control *heir |