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/sapi | |
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 'cpukit/sapi')
-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 |
5 files changed, 216 insertions, 170 deletions
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; |