diff options
Diffstat (limited to '')
-rw-r--r-- | doc/user/userext.t | 721 |
1 files changed, 0 insertions, 721 deletions
diff --git a/doc/user/userext.t b/doc/user/userext.t deleted file mode 100644 index 7f4a10180d..0000000000 --- a/doc/user/userext.t +++ /dev/null @@ -1,721 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter User Extensions Manager - -@cindex user extensions - -@section Introduction - -The RTEMS 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. The directives provided by the user extensions -manager are: - -@itemize @bullet -@item @code{@value{DIRPREFIX}extension_create} - Create an extension set -@item @code{@value{DIRPREFIX}extension_ident} - Get ID of an extension set -@item @code{@value{DIRPREFIX}extension_delete} - Delete an extension set -@end itemize - -@section Background - -User extension routines are invoked when the -following system events occur: - -@itemize @bullet -@item Task creation -@item Task initiation -@item Task reinitiation -@item Task deletion -@item Task context switch -@item Post task context switch -@item Task begin -@item Task exits -@item Fatal error detection -@end itemize - -These extensions are invoked as a function with -arguments that are appropriate to the system event. - -@subsection Extension Sets - -@cindex extension set - -An 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 is informed of -the entry points which constitute an extension set via the -following @value{STRUCTURE}: - -@findex rtems_extensions_table -@ifset is-C -@example -@group -typedef struct @{ - rtems_task_create_extension thread_create; - rtems_task_start_extension thread_start; - rtems_task_restart_extension thread_restart; - rtems_task_delete_extension thread_delete; - rtems_task_switch_extension thread_switch; - rtems_task_begin_extension thread_begin; - rtems_task_exitted_extension thread_exitted; - rtems_fatal_extension fatal; -@} rtems_extensions_table; -@end group -@end example -@end ifset - -@ifset is-Ada -@example -type Extensions_Table is - record - Task_Create : RTEMS.Task_Create_Extension; - Task_Start : RTEMS.Task_Start_Extension; - Task_Restart : RTEMS.Task_Restart_Extension; - Task_Delete : RTEMS.Task_Delete_Extension; - Task_Switch : RTEMS.Task_Switch_Extension; - Task_Post_Switch : RTEMS.Task_Post_Switch_Extension; - Task_Begin : RTEMS.Task_Begin_Extension; - Task_Exitted : RTEMS.Task_Exitted_Extension; - Fatal : RTEMS.Fatal_Error_Extension; - end record; -@end example -@end ifset - - -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 -initialize_executive directive. The static extension set is -optional and may be configured as NULL if no static extension -set is required. - -Second, the user can install dynamic extensions using -the @code{@value{DIRPREFIX}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 -initialize_executive 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. - -@subsection TCB Extension Area - -@cindex TCB extension 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. 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. - -The TCB extension is an array of pointers in the TCB. The -index into the table can be obtained from the extension id -returned when the extension is created: - -@findex rtems extensions table index -@ifset is-C -@example -@group -index = rtems_object_id_get_index(extension_id); -@end group -@end example -@end ifset - -@ifset is-Ada -@example -There is currently no example for Ada. -@end example -@end ifset - -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. - -@subsection Extensions - -The sections that follow will contain a description -of each extension. Each section will contain a prototype of a -function with the appropriate calling sequence for the -corresponding extension. The names given for the @value{LANGUAGE} -@value{ROUTINE} and -its arguments are all defined by the user. The names used in -the examples were arbitrarily chosen and impose no naming -conventions on the user. - -@subsubsection TASK_CREATE Extension - -The TASK_CREATE extension directly corresponds to the -@code{@value{DIRPREFIX}task_create} directive. If this extension -is defined in any -static or dynamic extension set and a task is being created, -then the extension routine will automatically be invoked by -RTEMS. The extension should have a prototype similar to the -following: - -@findex rtems_task_create_extension -@findex rtems_extension -@ifset is-C -@example -bool user_task_create( - rtems_tcb *current_task, - rtems_tcb *new_task -); -@end example -@end ifset - -@ifset is-Ada -@example -function User_Task_Create ( - Current_Task : in RTEMS.TCB_Pointer; - New_Task : in RTEMS.TCB_Pointer -) returns Boolean; -@end example -@end ifset - -where @code{current_task} can be used to access the TCB for -the currently executing task, and new_task can be used to access -the TCB for the new task being created. This extension is -invoked from the @code{@value{DIRPREFIX}task_create} -directive after @code{new_task} has been -completely initialized, but before it is placed on a ready TCB -chain. - -The user extension is expected to return the boolean -value @code{true} if it successfully executed and -@code{false} otherwise. A task create user extension -will frequently attempt to allocate resources. If this -allocation fails, then the extension should return -@code{false} and the entire task create operation -will fail. - -@subsubsection TASK_START Extension - -The TASK_START extension directly corresponds to the -task_start directive. If this extension is defined in any -static or dynamic extension set and a task is being started, -then the extension routine will automatically be invoked by -RTEMS. The extension should have a prototype similar to the -following: - -@findex rtems_task_start_extension -@ifset is-C -@example -void user_task_start( - rtems_tcb *current_task, - rtems_tcb *started_task -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Task_Start ( - Current_Task : in RTEMS.TCB_Pointer; - Started_Task : in RTEMS.TCB_Pointer -); -@end example -@end ifset - -where current_task can be used to access the TCB for -the currently executing task, and started_task can be used to -access the TCB for the dormant task being started. This -extension is invoked from the task_start directive after -started_task has been made ready to start execution, but before -it is placed on a ready TCB chain. - -@subsubsection TASK_RESTART Extension - -The TASK_RESTART extension directly corresponds to -the task_restart directive. If this extension is defined in any -static or dynamic extension set and a task is being restarted, -then the extension should have a prototype similar to the -following: - -@findex rtems_task_restart_extension -@ifset is-C -@example -void user_task_restart( - rtems_tcb *current_task, - rtems_tcb *restarted_task -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Task_Restart ( - Current_Task : in RTEMS.TCB_Pointer; - Restarted_Task : in RTEMS.TCB_Pointer -); -@end example -@end ifset - -where current_task can be used to access the TCB for -the currently executing task, and restarted_task can be used to -access the TCB for the task being restarted. This extension is -invoked from the task_restart directive after restarted_task has -been made ready to start execution, but before it is placed on a -ready TCB chain. - -@subsubsection TASK_DELETE Extension - -The TASK_DELETE extension is associated with the -task_delete directive. If this extension is defined in any -static or dynamic extension set and a task is being deleted, -then the extension routine will automatically be invoked by -RTEMS. The extension should have a prototype similar to the -following: - -@findex rtems_task_delete_extension -@ifset is-C -@example -void user_task_delete( - rtems_tcb *current_task, - rtems_tcb *deleted_task -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Task_Delete ( - Current_Task : in RTEMS.TCB_Pointer; - Deleted_Task : in RTEMS.TCB_Pointer -); -@end example -@end ifset - -where current_task can be used to access the TCB for -the currently executing task, and deleted_task can be used to -access the TCB for the task being deleted. This extension is -invoked from the task_delete directive after the TCB has been -removed from a ready TCB chain, but before all its resources -including the TCB have been returned to their respective free -pools. This extension should not call any RTEMS directives if a -task is deleting itself (current_task is equal to deleted_task). - -@subsubsection TASK_SWITCH Extension - -The TASK_SWITCH extension corresponds to a task -context switch. If this extension is defined in any static or -dynamic extension set and a task context switch is in progress, -then the extension routine will automatically be invoked by -RTEMS. The extension should have a prototype similar to the -following: - -@findex rtems_task_switch_extension -@ifset is-C -@example -void user_task_switch( - rtems_tcb *current_task, - rtems_tcb *heir_task -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Task_Switch ( - Current_Task : in RTEMS.TCB_Pointer; - Heir_Task : in RTEMS.TCB_Pointer -); -@end example -@end ifset - -where current_task can be used to access the TCB for -the task that is being swapped out, and heir_task can be used to -access the TCB for the task being swapped in. This extension is -invoked from RTEMS' dispatcher routine after the current_task -context has been saved, but before the heir_task context has -been restored. This extension should not call any RTEMS -directives. - -@subsubsection TASK_BEGIN Extension - -The TASK_BEGIN extension is invoked when a task -begins execution. It is invoked immediately before the body of -the starting procedure and executes in the context in the task. -This user extension have a prototype similar to the following: - -@findex rtems_task_begin_extension -@ifset is-C -@example -void user_task_begin( - rtems_tcb *current_task -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Task_Begin ( - Current_Task : in RTEMS.TCB_Pointer -); -@end example -@end ifset - -where current_task can be used to access the TCB for -the currently executing task which has begun. The distinction -between the TASK_BEGIN and TASK_START extension is that the -TASK_BEGIN extension is executed in the context of the actual -task while the TASK_START extension is executed in the context -of the task performing the task_start directive. For most -extensions, this is not a critical distinction. - -@subsubsection TASK_EXITTED Extension - -The TASK_EXITTED extension is invoked when a task -exits the body of the starting procedure by either an implicit -or explicit return statement. This user extension have a -prototype similar to the following: - -@findex rtems_task_exitted_extension -@ifset is-C -@example -void user_task_exitted( - rtems_tcb *current_task -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Task_Exitted ( - Current_Task : in RTEMS.TCB_Pointer -); -@end example -@end ifset - -where current_task can be used to access the TCB for -the currently executing task which has just exitted. - -Although exiting of task is often considered to be a -fatal error, this extension allows recovery by either restarting -or deleting the exiting task. If the user does not wish to -recover, then a fatal error may be reported. If the user does -not provide a TASK_EXITTED extension or the provided handler -returns control to RTEMS, then the RTEMS default handler will be -used. This default handler invokes the directive -fatal_error_occurred with the @code{@value{RPREFIX}TASK_EXITTED} directive status. - -@subsubsection FATAL Error Extension - -The FATAL error extension is associated with the -fatal_error_occurred directive. If this extension is defined in -any static or dynamic extension set and the fatal_error_occurred -directive has been invoked, then this extension will be called. -This extension should have a prototype similar to the following: - -@findex rtems_fatal_extension -@ifset is-C -@example -void user_fatal_error( - Internal_errors_Source the_source, - bool is_internal, - uint32_t the_error -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure User_Fatal_Error ( - Error : in RTEMS.Unsigned32 -); -@end example -@end ifset - -where the_error is the error code passed to the -fatal_error_occurred directive. This extension is invoked from -the fatal_error_occurred directive. - -If defined, the user's FATAL error extension is -invoked before RTEMS' default fatal error routine is invoked and -the processor is stopped. For example, this extension could be -used to pass control to a debugger when a fatal error occurs. -This extension should not call any RTEMS directives. - -@subsection Order of Invocation - -When one of the critical system events occur, the -user extensions are invoked in either "forward" or "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: - -@itemize @bullet -@item Task creation -@item Task initiation -@item Task reinitiation -@item Task deletion -@item Task context switch -@item Post task context switch -@item Task begins to execute -@end itemize - - -At the following system events, the extensions are -invoked in reverse order: - -@itemize @bullet -@item Task deletion -@item Fatal error detection -@end itemize - -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. - -@section Operations - -@subsection Creating an Extension Set - -The @code{@value{DIRPREFIX}extension_create} directive creates and installs -an extension set by allocating a Extension Set Control Block -(ESCB), assigning the extension set a user-specified name, and -assigning it an extension set ID. Newly created extension sets -are immediately installed and are invoked upon the next system -even supporting an extension. - -@subsection Obtaining Extension Set IDs - -When an extension set is created, RTEMS generates a -unique extension set ID and assigns it to the created extension -set until it is deleted. The extension ID may be obtained by -either of two methods. First, as the result of an invocation of -the @code{@value{DIRPREFIX}extension_create} -directive, the extension set ID is stored -in a user provided location. Second, the extension set ID may -be obtained later using the @code{@value{DIRPREFIX}extension_ident} -directive. The extension set ID is used by other directives -to manipulate this extension set. - -@subsection Deleting an Extension Set - -The @code{@value{DIRPREFIX}extension_delete} directive is used to delete an -extension set. The extension set's control block is returned to -the ESCB free list when it is deleted. An extension set can be -deleted by a task other than the task which created the -extension set. Any subsequent references to the extension's -name and ID are invalid. - -@section Directives - -This section details the user extension manager's -directives. A subsection is dedicated to each of this manager's -directives and describes the calling sequence, related -constants, usage, and status codes. - -@c -@c -@c -@page -@subsection EXTENSION_CREATE - Create a extension set - -@cindex create an extension set - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_extension_create -@example -rtems_status_code rtems_extension_create( - rtems_name name, - rtems_extensions_table *table, - rtems_id *id -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Extension_Create ( - Name : in RTEMS.Name; - Table : in RTEMS.Extensions_Table_Pointer; - ID : out RTEMS.ID; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - extension set created successfully@* -@code{@value{RPREFIX}INVALID_NAME} - invalid extension set name@* -@code{@value{RPREFIX}TOO_MANY} - too many extension sets created - -@subheading DESCRIPTION: - -This directive creates a extension set. The assigned -extension set id is returned in id. This id is used to access -the extension set with other user extension manager directives. -For control and maintenance of the extension set, RTEMS -allocates an ESCB from the local ESCB free pool and initializes -it. - -@subheading NOTES: - -This directive will not cause the calling task to be -preempted. - -@c -@c -@c -@page -@subsection EXTENSION_IDENT - Get ID of a extension set - -@cindex get ID of an extension set -@cindex obtain ID of an extension set - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_extension_ident -@example -rtems_status_code rtems_extension_ident( - rtems_name name, - rtems_id *id -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Extension_Ident ( - Name : in RTEMS.Name; - ID : out RTEMS.ID; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - extension set identified successfully@* -@code{@value{RPREFIX}INVALID_NAME} - extension set name not found - -@subheading DESCRIPTION: - -This directive obtains the extension set id -associated with the extension set name to be acquired. If the -extension set name is not unique, then the extension set id will -match one of the extension sets with that name. However, this -extension set id is not guaranteed to correspond to the desired -extension set. The extension set id is used to access this -extension set in other extension set related directives. - -@subheading NOTES: - -This directive will not cause the running task to be -preempted. - -@c -@c -@c -@page -@subsection EXTENSION_DELETE - Delete a extension set - -@cindex delete an extension set - -@subheading CALLING SEQUENCE: - -@ifset is-C -@findex rtems_extension_delete -@example -rtems_status_code rtems_extension_delete( - rtems_id id -); -@end example -@end ifset - -@ifset is-Ada -@example -procedure Extension_Delete ( - ID : in RTEMS.ID; - Result : out RTEMS.Status_Codes -); -@end example -@end ifset - -@subheading DIRECTIVE STATUS CODES: -@code{@value{RPREFIX}SUCCESSFUL} - extension set deleted successfully@* -@code{@value{RPREFIX}INVALID_ID} - invalid extension set id - -@subheading DESCRIPTION: - -This directive deletes the extension set specified by -id. If the extension set is running, it is automatically -canceled. The ESCB for the deleted extension set is reclaimed -by RTEMS. - -@subheading NOTES: - -This directive will not cause the running task to be -preempted. - -A extension set can be deleted by a task other than -the task which created the extension set. - -@subheading NOTES: - -This directive will not cause the running task to be -preempted. |