@c
|
@c
|
@c COPYRIGHT (c) 1988-2002.
|
@c COPYRIGHT (c) 1988-2002.
|
@c On-Line Applications Research Corporation (OAR).
|
@c On-Line Applications Research Corporation (OAR).
|
@c All rights reserved.
|
@c All rights reserved.
|
@c
|
@c
|
@c userext.t,v 1.17 2002/06/28 13:57:18 joel Exp
|
@c userext.t,v 1.17 2002/06/28 13:57:18 joel Exp
|
@c
|
@c
|
|
|
@chapter User Extensions Manager
|
@chapter User Extensions Manager
|
|
|
@cindex user extensions
|
@cindex user extensions
|
|
|
@section Introduction
|
@section Introduction
|
|
|
The RTEMS User Extensions Manager allows the
|
The RTEMS User Extensions Manager allows the
|
application developer to augment the executive by allowing them
|
application developer to augment the executive by allowing them
|
to supply extension routines which are invoked at critical
|
to supply extension routines which are invoked at critical
|
system events. The directives provided by the user extensions
|
system events. The directives provided by the user extensions
|
manager are:
|
manager are:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item @code{@value{DIRPREFIX}extension_create} - Create an extension set
|
@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_ident} - Get ID of an extension set
|
@item @code{@value{DIRPREFIX}extension_delete} - Delete an extension set
|
@item @code{@value{DIRPREFIX}extension_delete} - Delete an extension set
|
@end itemize
|
@end itemize
|
|
|
@section Background
|
@section Background
|
|
|
User extension routines are invoked when the
|
User extension routines are invoked when the
|
following system events occur:
|
following system events occur:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item Task creation
|
@item Task creation
|
@item Task initiation
|
@item Task initiation
|
@item Task reinitiation
|
@item Task reinitiation
|
@item Task deletion
|
@item Task deletion
|
@item Task context switch
|
@item Task context switch
|
@item Post task context switch
|
@item Post task context switch
|
@item Task begin
|
@item Task begin
|
@item Task exits
|
@item Task exits
|
@item Fatal error detection
|
@item Fatal error detection
|
@end itemize
|
@end itemize
|
|
|
These extensions are invoked as a function with
|
These extensions are invoked as a function with
|
arguments that are appropriate to the system event.
|
arguments that are appropriate to the system event.
|
|
|
@subsection Extension Sets
|
@subsection Extension Sets
|
|
|
@cindex extension set
|
@cindex extension set
|
|
|
An extension set is defined as a set of routines
|
An extension set is defined as a set of routines
|
which are invoked at each of the critical system events at which
|
which are invoked at each of the critical system events at which
|
user extension routines are invoked. Together a set of these
|
user extension routines are invoked. Together a set of these
|
routines typically perform a specific functionality such as
|
routines typically perform a specific functionality such as
|
performance monitoring or debugger support. RTEMS is informed of
|
performance monitoring or debugger support. RTEMS is informed of
|
the entry points which constitute an extension set via the
|
the entry points which constitute an extension set via the
|
following @value{STRUCTURE}:
|
following @value{STRUCTURE}:
|
|
|
@findex rtems_extensions_table
|
@findex rtems_extensions_table
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
@group
|
@group
|
typedef struct @{
|
typedef struct @{
|
rtems_task_create_extension thread_create;
|
rtems_task_create_extension thread_create;
|
rtems_task_start_extension thread_start;
|
rtems_task_start_extension thread_start;
|
rtems_task_restart_extension thread_restart;
|
rtems_task_restart_extension thread_restart;
|
rtems_task_delete_extension thread_delete;
|
rtems_task_delete_extension thread_delete;
|
rtems_task_switch_extension thread_switch;
|
rtems_task_switch_extension thread_switch;
|
rtems_task_begin_extension thread_begin;
|
rtems_task_begin_extension thread_begin;
|
rtems_task_exitted_extension thread_exitted;
|
rtems_task_exitted_extension thread_exitted;
|
rtems_fatal_extension fatal;
|
rtems_fatal_extension fatal;
|
@} rtems_extensions_table;
|
@} rtems_extensions_table;
|
@end group
|
@end group
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
type Extensions_Table is
|
type Extensions_Table is
|
record
|
record
|
Task_Create : RTEMS.Task_Create_Extension;
|
Task_Create : RTEMS.Task_Create_Extension;
|
Task_Start : RTEMS.Task_Start_Extension;
|
Task_Start : RTEMS.Task_Start_Extension;
|
Task_Restart : RTEMS.Task_Restart_Extension;
|
Task_Restart : RTEMS.Task_Restart_Extension;
|
Task_Delete : RTEMS.Task_Delete_Extension;
|
Task_Delete : RTEMS.Task_Delete_Extension;
|
Task_Switch : RTEMS.Task_Switch_Extension;
|
Task_Switch : RTEMS.Task_Switch_Extension;
|
Task_Post_Switch : RTEMS.Task_Post_Switch_Extension;
|
Task_Post_Switch : RTEMS.Task_Post_Switch_Extension;
|
Task_Begin : RTEMS.Task_Begin_Extension;
|
Task_Begin : RTEMS.Task_Begin_Extension;
|
Task_Exitted : RTEMS.Task_Exitted_Extension;
|
Task_Exitted : RTEMS.Task_Exitted_Extension;
|
Fatal : RTEMS.Fatal_Error_Extension;
|
Fatal : RTEMS.Fatal_Error_Extension;
|
end record;
|
end record;
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
|
|
RTEMS allows the user to have multiple extension sets
|
RTEMS allows the user to have multiple extension sets
|
active at the same time. First, a single static extension set
|
active at the same time. First, a single static extension set
|
may be defined as the application's User Extension Table which
|
may be defined as the application's User Extension Table which
|
is included as part of the Configuration Table. This extension
|
is included as part of the Configuration Table. This extension
|
set is active for the entire life of the system and may not be
|
set is active for the entire life of the system and may not be
|
deleted. This extension set is especially important because it
|
deleted. This extension set is especially important because it
|
is the only way the application can provided a FATAL error
|
is the only way the application can provided a FATAL error
|
extension which is invoked if RTEMS fails during the
|
extension which is invoked if RTEMS fails during the
|
initialize_executive directive. The static extension set is
|
initialize_executive directive. The static extension set is
|
optional and may be configured as NULL if no static extension
|
optional and may be configured as NULL if no static extension
|
set is required.
|
set is required.
|
|
|
Second, the user can install dynamic extensions using
|
Second, the user can install dynamic extensions using
|
the @code{@value{DIRPREFIX}extension_create}
|
the @code{@value{DIRPREFIX}extension_create}
|
directive. These extensions are RTEMS
|
directive. These extensions are RTEMS
|
objects in that they have a name, an ID, and can be dynamically
|
objects in that they have a name, an ID, and can be dynamically
|
created and deleted. In contrast to the static extension set,
|
created and deleted. In contrast to the static extension set,
|
these extensions can only be created and installed after the
|
these extensions can only be created and installed after the
|
initialize_executive directive successfully completes execution.
|
initialize_executive directive successfully completes execution.
|
Dynamic extensions are useful for encapsulating the
|
Dynamic extensions are useful for encapsulating the
|
functionality of an extension set. For example, the application
|
functionality of an extension set. For example, the application
|
could use extensions to manage a special coprocessor, do
|
could use extensions to manage a special coprocessor, do
|
performance monitoring, and to do stack bounds checking. Each
|
performance monitoring, and to do stack bounds checking. Each
|
of these extension sets could be written and installed
|
of these extension sets could be written and installed
|
independently of the others.
|
independently of the others.
|
|
|
All user extensions are optional and RTEMS places no
|
All user extensions are optional and RTEMS places no
|
naming restrictions on the user. The user extension entry points
|
naming restrictions on the user. The user extension entry points
|
are copied into an internal RTEMS structure. This means the user
|
are copied into an internal RTEMS structure. This means the user
|
does not need to keep the table after creating it, and changing the
|
does not need to keep the table after creating it, and changing the
|
handler entry points dynamically in a table once created has no
|
handler entry points dynamically in a table once created has no
|
effect. Creating a table local to a function can save space in
|
effect. Creating a table local to a function can save space in
|
space limited applications.
|
space limited applications.
|
|
|
Extension switches do not effect the context switch overhead if
|
Extension switches do not effect the context switch overhead if
|
no switch handler is installed.
|
no switch handler is installed.
|
|
|
@subsection TCB Extension Area
|
@subsection TCB Extension Area
|
|
|
@cindex TCB extension area
|
@cindex TCB extension area
|
|
|
RTEMS provides for a pointer to a user-defined data
|
RTEMS provides for a pointer to a user-defined data
|
area for each extension set to be linked to each task's control
|
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
|
block. This set of pointers is an extension of the TCB and can
|
be used to store additional data required by the user's
|
be used to store additional data required by the user's
|
extension functions. It is also possible for a user extension
|
extension functions. It is also possible for a user extension
|
to utilize the notepad locations associated with each task
|
to utilize the notepad locations associated with each task
|
although this may conflict with application usage of those
|
although this may conflict with application usage of those
|
particular notepads.
|
particular notepads.
|
|
|
The TCB extension is an array of pointers in the TCB. The
|
The TCB extension is an array of pointers in the TCB. The
|
index into the table can be obtained from the extension id
|
index into the table can be obtained from the extension id
|
returned when the extension is created:
|
returned when the extension is created:
|
|
|
@findex rtems extensions table index
|
@findex rtems extensions table index
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
@group
|
@group
|
index = rtems_get_index(extension_id);
|
index = rtems_get_index(extension_id);
|
@end group
|
@end group
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
There is currently no example for Ada.
|
There is currently no example for Ada.
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
The number of pointers in the area is the same as the number of
|
The number of pointers in the area is the same as the number of
|
user extension sets configured. This allows an application to
|
user extension sets configured. This allows an application to
|
augment the TCB with user-defined information. For example, an
|
augment the TCB with user-defined information. For example, an
|
application could implement task profiling by storing timing
|
application could implement task profiling by storing timing
|
statistics in the TCB's extended memory area. When a task
|
statistics in the TCB's extended memory area. When a task
|
context switch is being executed, the TASK_SWITCH extension
|
context switch is being executed, the TASK_SWITCH extension
|
could read a real-time clock to calculate how long the task
|
could read a real-time clock to calculate how long the task
|
being swapped out has run as well as timestamp the starting time
|
being swapped out has run as well as timestamp the starting time
|
for the task being swapped in.
|
for the task being swapped in.
|
|
|
If used, the extended memory area for the TCB should
|
If used, the extended memory area for the TCB should
|
be allocated and the TCB extension pointer should be set at the
|
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
|
time the task is created or started by either the TASK_CREATE or
|
TASK_START extension. The application is responsible for
|
TASK_START extension. The application is responsible for
|
managing this extended memory area for the TCBs. The memory may
|
managing this extended memory area for the TCBs. The memory may
|
be reinitialized by the TASK_RESTART extension and should be
|
be reinitialized by the TASK_RESTART extension and should be
|
deallocated by the TASK_DELETE extension when the task is
|
deallocated by the TASK_DELETE extension when the task is
|
deleted. Since the TCB extension buffers would most likely be
|
deleted. Since the TCB extension buffers would most likely be
|
of a fixed size, the RTEMS partition manager could be used to
|
of a fixed size, the RTEMS partition manager could be used to
|
manage the application's extended memory area. The application
|
manage the application's extended memory area. The application
|
could create a partition of fixed size TCB extension buffers and
|
could create a partition of fixed size TCB extension buffers and
|
use the partition manager's allocation and deallocation
|
use the partition manager's allocation and deallocation
|
directives to obtain and release the extension buffers.
|
directives to obtain and release the extension buffers.
|
|
|
@subsection Extensions
|
@subsection Extensions
|
|
|
The sections that follow will contain a description
|
The sections that follow will contain a description
|
of each extension. Each section will contain a prototype of a
|
of each extension. Each section will contain a prototype of a
|
function with the appropriate calling sequence for the
|
function with the appropriate calling sequence for the
|
corresponding extension. The names given for the @value{LANGUAGE}
|
corresponding extension. The names given for the @value{LANGUAGE}
|
@value{ROUTINE} and
|
@value{ROUTINE} and
|
its arguments are all defined by the user. The names used in
|
its arguments are all defined by the user. The names used in
|
the examples were arbitrarily chosen and impose no naming
|
the examples were arbitrarily chosen and impose no naming
|
conventions on the user.
|
conventions on the user.
|
|
|
@subsubsection TASK_CREATE Extension
|
@subsubsection TASK_CREATE Extension
|
|
|
The TASK_CREATE extension directly corresponds to the
|
The TASK_CREATE extension directly corresponds to the
|
@code{@value{DIRPREFIX}task_create} directive. If this extension
|
@code{@value{DIRPREFIX}task_create} directive. If this extension
|
is defined in any
|
is defined in any
|
static or dynamic extension set and a task is being created,
|
static or dynamic extension set and a task is being created,
|
then the extension routine will automatically be invoked by
|
then the extension routine will automatically be invoked by
|
RTEMS. The extension should have a prototype similar to the
|
RTEMS. The extension should have a prototype similar to the
|
following:
|
following:
|
|
|
@findex rtems_task_create_extension
|
@findex rtems_task_create_extension
|
@findex rtems_extension
|
@findex rtems_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
boolean user_task_create(
|
boolean user_task_create(
|
rtems_tcb *current_task,
|
rtems_tcb *current_task,
|
rtems_tcb *new_task
|
rtems_tcb *new_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
function User_Task_Create (
|
function User_Task_Create (
|
Current_Task : in RTEMS.TCB_Pointer;
|
Current_Task : in RTEMS.TCB_Pointer;
|
New_Task : in RTEMS.TCB_Pointer
|
New_Task : in RTEMS.TCB_Pointer
|
) returns Boolean;
|
) returns Boolean;
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where @code{current_task} can be used to access the TCB for
|
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 currently executing task, and new_task can be used to access
|
the TCB for the new task being created. This extension is
|
the TCB for the new task being created. This extension is
|
invoked from the @code{@value{DIRPREFIX}task_create}
|
invoked from the @code{@value{DIRPREFIX}task_create}
|
directive after @code{new_task} has been
|
directive after @code{new_task} has been
|
completely initialized, but before it is placed on a ready TCB
|
completely initialized, but before it is placed on a ready TCB
|
chain.
|
chain.
|
|
|
The user extension is expected to return the boolean
|
The user extension is expected to return the boolean
|
value @code{TRUE} if it successfully executed and
|
value @code{TRUE} if it successfully executed and
|
@code{FALSE} otherwise. A task create user extension
|
@code{FALSE} otherwise. A task create user extension
|
will frequently attempt to allocate resources. If this
|
will frequently attempt to allocate resources. If this
|
allocation fails, then the extension should return
|
allocation fails, then the extension should return
|
@code{FALSE} and the entire task create operation
|
@code{FALSE} and the entire task create operation
|
will fail.
|
will fail.
|
|
|
@subsubsection TASK_START Extension
|
@subsubsection TASK_START Extension
|
|
|
The TASK_START extension directly corresponds to the
|
The TASK_START extension directly corresponds to the
|
task_start directive. If this extension is defined in any
|
task_start directive. If this extension is defined in any
|
static or dynamic extension set and a task is being started,
|
static or dynamic extension set and a task is being started,
|
then the extension routine will automatically be invoked by
|
then the extension routine will automatically be invoked by
|
RTEMS. The extension should have a prototype similar to the
|
RTEMS. The extension should have a prototype similar to the
|
following:
|
following:
|
|
|
@findex rtems_task_start_extension
|
@findex rtems_task_start_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_task_start(
|
rtems_extension user_task_start(
|
rtems_tcb *current_task,
|
rtems_tcb *current_task,
|
rtems_tcb *started_task
|
rtems_tcb *started_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Task_Start (
|
procedure User_Task_Start (
|
Current_Task : in RTEMS.TCB_Pointer;
|
Current_Task : in RTEMS.TCB_Pointer;
|
Started_Task : in RTEMS.TCB_Pointer
|
Started_Task : in RTEMS.TCB_Pointer
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where current_task can be used to access the TCB for
|
where current_task can be used to access the TCB for
|
the currently executing task, and started_task can be used to
|
the currently executing task, and started_task can be used to
|
access the TCB for the dormant task being started. This
|
access the TCB for the dormant task being started. This
|
extension is invoked from the task_start directive after
|
extension is invoked from the task_start directive after
|
started_task has been made ready to start execution, but before
|
started_task has been made ready to start execution, but before
|
it is placed on a ready TCB chain.
|
it is placed on a ready TCB chain.
|
|
|
@subsubsection TASK_RESTART Extension
|
@subsubsection TASK_RESTART Extension
|
|
|
The TASK_RESTART extension directly corresponds to
|
The TASK_RESTART extension directly corresponds to
|
the task_restart directive. If this extension is defined in any
|
the task_restart directive. If this extension is defined in any
|
static or dynamic extension set and a task is being restarted,
|
static or dynamic extension set and a task is being restarted,
|
then the extension should have a prototype similar to the
|
then the extension should have a prototype similar to the
|
following:
|
following:
|
|
|
@findex rtems_task_restart_extension
|
@findex rtems_task_restart_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_task_restart(
|
rtems_extension user_task_restart(
|
rtems_tcb *current_task,
|
rtems_tcb *current_task,
|
rtems_tcb *restarted_task
|
rtems_tcb *restarted_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Task_Restart (
|
procedure User_Task_Restart (
|
Current_Task : in RTEMS.TCB_Pointer;
|
Current_Task : in RTEMS.TCB_Pointer;
|
Restarted_Task : in RTEMS.TCB_Pointer
|
Restarted_Task : in RTEMS.TCB_Pointer
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where current_task can be used to access the TCB for
|
where current_task can be used to access the TCB for
|
the currently executing task, and restarted_task can be used to
|
the currently executing task, and restarted_task can be used to
|
access the TCB for the task being restarted. This extension is
|
access the TCB for the task being restarted. This extension is
|
invoked from the task_restart directive after restarted_task has
|
invoked from the task_restart directive after restarted_task has
|
been made ready to start execution, but before it is placed on a
|
been made ready to start execution, but before it is placed on a
|
ready TCB chain.
|
ready TCB chain.
|
|
|
@subsubsection TASK_DELETE Extension
|
@subsubsection TASK_DELETE Extension
|
|
|
The TASK_DELETE extension is associated with the
|
The TASK_DELETE extension is associated with the
|
task_delete directive. If this extension is defined in any
|
task_delete directive. If this extension is defined in any
|
static or dynamic extension set and a task is being deleted,
|
static or dynamic extension set and a task is being deleted,
|
then the extension routine will automatically be invoked by
|
then the extension routine will automatically be invoked by
|
RTEMS. The extension should have a prototype similar to the
|
RTEMS. The extension should have a prototype similar to the
|
following:
|
following:
|
|
|
@findex rtems_task_delete_extension
|
@findex rtems_task_delete_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_task_delete(
|
rtems_extension user_task_delete(
|
rtems_tcb *current_task,
|
rtems_tcb *current_task,
|
rtems_tcb *deleted_task
|
rtems_tcb *deleted_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Task_Delete (
|
procedure User_Task_Delete (
|
Current_Task : in RTEMS.TCB_Pointer;
|
Current_Task : in RTEMS.TCB_Pointer;
|
Deleted_Task : in RTEMS.TCB_Pointer
|
Deleted_Task : in RTEMS.TCB_Pointer
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where current_task can be used to access the TCB for
|
where current_task can be used to access the TCB for
|
the currently executing task, and deleted_task can be used to
|
the currently executing task, and deleted_task can be used to
|
access the TCB for the task being deleted. This extension is
|
access the TCB for the task being deleted. This extension is
|
invoked from the task_delete directive after the TCB has been
|
invoked from the task_delete directive after the TCB has been
|
removed from a ready TCB chain, but before all its resources
|
removed from a ready TCB chain, but before all its resources
|
including the TCB have been returned to their respective free
|
including the TCB have been returned to their respective free
|
pools. This extension should not call any RTEMS directives if a
|
pools. This extension should not call any RTEMS directives if a
|
task is deleting itself (current_task is equal to deleted_task).
|
task is deleting itself (current_task is equal to deleted_task).
|
|
|
@subsubsection TASK_SWITCH Extension
|
@subsubsection TASK_SWITCH Extension
|
|
|
The TASK_SWITCH extension corresponds to a task
|
The TASK_SWITCH extension corresponds to a task
|
context switch. If this extension is defined in any static or
|
context switch. If this extension is defined in any static or
|
dynamic extension set and a task context switch is in progress,
|
dynamic extension set and a task context switch is in progress,
|
then the extension routine will automatically be invoked by
|
then the extension routine will automatically be invoked by
|
RTEMS. The extension should have a prototype similar to the
|
RTEMS. The extension should have a prototype similar to the
|
following:
|
following:
|
|
|
@findex rtems_task_switch_extension
|
@findex rtems_task_switch_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_task_switch(
|
rtems_extension user_task_switch(
|
rtems_tcb *current_task,
|
rtems_tcb *current_task,
|
rtems_tcb *heir_task
|
rtems_tcb *heir_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Task_Switch (
|
procedure User_Task_Switch (
|
Current_Task : in RTEMS.TCB_Pointer;
|
Current_Task : in RTEMS.TCB_Pointer;
|
Heir_Task : in RTEMS.TCB_Pointer
|
Heir_Task : in RTEMS.TCB_Pointer
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where current_task can be used to access the TCB for
|
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
|
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
|
access the TCB for the task being swapped in. This extension is
|
invoked from RTEMS' dispatcher routine after the current_task
|
invoked from RTEMS' dispatcher routine after the current_task
|
context has been saved, but before the heir_task context has
|
context has been saved, but before the heir_task context has
|
been restored. This extension should not call any RTEMS
|
been restored. This extension should not call any RTEMS
|
directives.
|
directives.
|
|
|
@subsubsection TASK_BEGIN Extension
|
@subsubsection TASK_BEGIN Extension
|
|
|
The TASK_BEGIN extension is invoked when a task
|
The TASK_BEGIN extension is invoked when a task
|
begins execution. It is invoked immediately before the body of
|
begins execution. It is invoked immediately before the body of
|
the starting procedure and executes in the context in the task.
|
the starting procedure and executes in the context in the task.
|
This user extension have a prototype similar to the following:
|
This user extension have a prototype similar to the following:
|
|
|
@findex rtems_task_begin_extension
|
@findex rtems_task_begin_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_task_begin(
|
rtems_extension user_task_begin(
|
rtems_tcb *current_task
|
rtems_tcb *current_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Task_Begin (
|
procedure User_Task_Begin (
|
Current_Task : in RTEMS.TCB_Pointer
|
Current_Task : in RTEMS.TCB_Pointer
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where current_task can be used to access the TCB for
|
where current_task can be used to access the TCB for
|
the currently executing task which has begun. The distinction
|
the currently executing task which has begun. The distinction
|
between the TASK_BEGIN and TASK_START extension is that the
|
between the TASK_BEGIN and TASK_START extension is that the
|
TASK_BEGIN extension is executed in the context of the actual
|
TASK_BEGIN extension is executed in the context of the actual
|
task while the TASK_START extension is executed in the context
|
task while the TASK_START extension is executed in the context
|
of the task performing the task_start directive. For most
|
of the task performing the task_start directive. For most
|
extensions, this is not a critical distinction.
|
extensions, this is not a critical distinction.
|
|
|
@subsubsection TASK_EXITTED Extension
|
@subsubsection TASK_EXITTED Extension
|
|
|
The TASK_EXITTED extension is invoked when a task
|
The TASK_EXITTED extension is invoked when a task
|
exits the body of the starting procedure by either an implicit
|
exits the body of the starting procedure by either an implicit
|
or explicit return statement. This user extension have a
|
or explicit return statement. This user extension have a
|
prototype similar to the following:
|
prototype similar to the following:
|
|
|
@findex rtems_task_exitted_extension
|
@findex rtems_task_exitted_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_task_exitted(
|
rtems_extension user_task_exitted(
|
rtems_tcb *current_task
|
rtems_tcb *current_task
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Task_Exitted (
|
procedure User_Task_Exitted (
|
Current_Task : in RTEMS.TCB_Pointer
|
Current_Task : in RTEMS.TCB_Pointer
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where current_task can be used to access the TCB for
|
where current_task can be used to access the TCB for
|
the currently executing task which has just exitted.
|
the currently executing task which has just exitted.
|
|
|
Although exiting of task is often considered to be a
|
Although exiting of task is often considered to be a
|
fatal error, this extension allows recovery by either restarting
|
fatal error, this extension allows recovery by either restarting
|
or deleting the exiting task. If the user does not wish to
|
or deleting the exiting task. If the user does not wish to
|
recover, then a fatal error may be reported. If the user does
|
recover, then a fatal error may be reported. If the user does
|
not provide a TASK_EXITTED extension or the provided handler
|
not provide a TASK_EXITTED extension or the provided handler
|
returns control to RTEMS, then the RTEMS default handler will be
|
returns control to RTEMS, then the RTEMS default handler will be
|
used. This default handler invokes the directive
|
used. This default handler invokes the directive
|
fatal_error_occurred with the @code{@value{RPREFIX}TASK_EXITTED} directive status.
|
fatal_error_occurred with the @code{@value{RPREFIX}TASK_EXITTED} directive status.
|
|
|
@subsubsection FATAL Error Extension
|
@subsubsection FATAL Error Extension
|
|
|
The FATAL error extension is associated with the
|
The FATAL error extension is associated with the
|
fatal_error_occurred directive. If this extension is defined in
|
fatal_error_occurred directive. If this extension is defined in
|
any static or dynamic extension set and the fatal_error_occurred
|
any static or dynamic extension set and the fatal_error_occurred
|
directive has been invoked, then this extension will be called.
|
directive has been invoked, then this extension will be called.
|
This extension should have a prototype similar to the following:
|
This extension should have a prototype similar to the following:
|
|
|
@findex rtems_fatal_extension
|
@findex rtems_fatal_extension
|
@ifset is-C
|
@ifset is-C
|
@example
|
@example
|
rtems_extension user_fatal_error(
|
rtems_extension user_fatal_error(
|
Internal_errors_Source the_source,
|
Internal_errors_Source the_source,
|
rtems_boolean is_internal,
|
rtems_boolean is_internal,
|
rtems_unsigned32 the_error
|
rtems_unsigned32 the_error
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure User_Fatal_Error (
|
procedure User_Fatal_Error (
|
Error : in RTEMS.Unsigned32
|
Error : in RTEMS.Unsigned32
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
where the_error is the error code passed to the
|
where the_error is the error code passed to the
|
fatal_error_occurred directive. This extension is invoked from
|
fatal_error_occurred directive. This extension is invoked from
|
the fatal_error_occurred directive.
|
the fatal_error_occurred directive.
|
|
|
If defined, the user's FATAL error extension is
|
If defined, the user's FATAL error extension is
|
invoked before RTEMS' default fatal error routine is invoked and
|
invoked before RTEMS' default fatal error routine is invoked and
|
the processor is stopped. For example, this extension could be
|
the processor is stopped. For example, this extension could be
|
used to pass control to a debugger when a fatal error occurs.
|
used to pass control to a debugger when a fatal error occurs.
|
This extension should not call any RTEMS directives.
|
This extension should not call any RTEMS directives.
|
|
|
@subsection Order of Invocation
|
@subsection Order of Invocation
|
|
|
When one of the critical system events occur, the
|
When one of the critical system events occur, the
|
user extensions are invoked in either "forward" or "reverse"
|
user extensions are invoked in either "forward" or "reverse"
|
order. Forward order indicates that the static extension set is
|
order. Forward order indicates that the static extension set is
|
invoked followed by the dynamic extension sets in the order in
|
invoked followed by the dynamic extension sets in the order in
|
which they were created. Reverse order means that the dynamic
|
which they were created. Reverse order means that the dynamic
|
extension sets are invoked in the opposite of the order in which
|
extension sets are invoked in the opposite of the order in which
|
they were created followed by the static extension set. By
|
they were created followed by the static extension set. By
|
invoking the extension sets in this order, extensions can be
|
invoking the extension sets in this order, extensions can be
|
built upon one another. At the following system events, the
|
built upon one another. At the following system events, the
|
extensions are invoked in forward order:
|
extensions are invoked in forward order:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item Task creation
|
@item Task creation
|
@item Task initiation
|
@item Task initiation
|
@item Task reinitiation
|
@item Task reinitiation
|
@item Task deletion
|
@item Task deletion
|
@item Task context switch
|
@item Task context switch
|
@item Post task context switch
|
@item Post task context switch
|
@item Task begins to execute
|
@item Task begins to execute
|
@end itemize
|
@end itemize
|
|
|
|
|
At the following system events, the extensions are
|
At the following system events, the extensions are
|
invoked in reverse order:
|
invoked in reverse order:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item Task deletion
|
@item Task deletion
|
@item Fatal error detection
|
@item Fatal error detection
|
@end itemize
|
@end itemize
|
|
|
At these system events, the extensions are invoked in
|
At these system events, the extensions are invoked in
|
reverse order to insure that if an extension set is built upon
|
reverse order to insure that if an extension set is built upon
|
another, the more complicated extension is invoked before the
|
another, the more complicated extension is invoked before the
|
extension set it is built upon. For example, by invoking the
|
extension set it is built upon. For example, by invoking the
|
static extension set last it is known that the "system" fatal
|
static extension set last it is known that the "system" fatal
|
error extension will be the last fatal error extension executed.
|
error extension will be the last fatal error extension executed.
|
Another example is use of the task delete extension by the
|
Another example is use of the task delete extension by the
|
Standard C Library. Extension sets which are installed after
|
Standard C Library. Extension sets which are installed after
|
the Standard C Library will operate correctly even if they
|
the Standard C Library will operate correctly even if they
|
utilize the C Library because the C Library's TASK_DELETE
|
utilize the C Library because the C Library's TASK_DELETE
|
extension is invoked after that of the other extensions.
|
extension is invoked after that of the other extensions.
|
|
|
@section Operations
|
@section Operations
|
|
|
@subsection Creating an Extension Set
|
@subsection Creating an Extension Set
|
|
|
The @code{@value{DIRPREFIX}extension_create} directive creates and installs
|
The @code{@value{DIRPREFIX}extension_create} directive creates and installs
|
an extension set by allocating a Extension Set Control Block
|
an extension set by allocating a Extension Set Control Block
|
(ESCB), assigning the extension set a user-specified name, and
|
(ESCB), assigning the extension set a user-specified name, and
|
assigning it an extension set ID. Newly created extension sets
|
assigning it an extension set ID. Newly created extension sets
|
are immediately installed and are invoked upon the next system
|
are immediately installed and are invoked upon the next system
|
even supporting an extension.
|
even supporting an extension.
|
|
|
@subsection Obtaining Extension Set IDs
|
@subsection Obtaining Extension Set IDs
|
|
|
When an extension set is created, RTEMS generates a
|
When an extension set is created, RTEMS generates a
|
unique extension set ID and assigns it to the created extension
|
unique extension set ID and assigns it to the created extension
|
set until it is deleted. The extension ID may be obtained by
|
set until it is deleted. The extension ID may be obtained by
|
either of two methods. First, as the result of an invocation of
|
either of two methods. First, as the result of an invocation of
|
the @code{@value{DIRPREFIX}extension_create}
|
the @code{@value{DIRPREFIX}extension_create}
|
directive, the extension set ID is stored
|
directive, the extension set ID is stored
|
in a user provided location. Second, the extension set ID may
|
in a user provided location. Second, the extension set ID may
|
be obtained later using the @code{@value{DIRPREFIX}extension_ident}
|
be obtained later using the @code{@value{DIRPREFIX}extension_ident}
|
directive. The extension set ID is used by other directives
|
directive. The extension set ID is used by other directives
|
to manipulate this extension set.
|
to manipulate this extension set.
|
|
|
@subsection Deleting an Extension Set
|
@subsection Deleting an Extension Set
|
|
|
The @code{@value{DIRPREFIX}extension_delete} directive is used to delete an
|
The @code{@value{DIRPREFIX}extension_delete} directive is used to delete an
|
extension set. The extension set's control block is returned to
|
extension set. The extension set's control block is returned to
|
the ESCB free list when it is deleted. An extension set can be
|
the ESCB free list when it is deleted. An extension set can be
|
deleted by a task other than the task which created the
|
deleted by a task other than the task which created the
|
extension set. Any subsequent references to the extension's
|
extension set. Any subsequent references to the extension's
|
name and ID are invalid.
|
name and ID are invalid.
|
|
|
@section Directives
|
@section Directives
|
|
|
This section details the user extension manager's
|
This section details the user extension manager's
|
directives. A subsection is dedicated to each of this manager's
|
directives. A subsection is dedicated to each of this manager's
|
directives and describes the calling sequence, related
|
directives and describes the calling sequence, related
|
constants, usage, and status codes.
|
constants, usage, and status codes.
|
|
|
@c
|
@c
|
@c
|
@c
|
@c
|
@c
|
@page
|
@page
|
@subsection EXTENSION_CREATE - Create a extension set
|
@subsection EXTENSION_CREATE - Create a extension set
|
|
|
@cindex create an extension set
|
@cindex create an extension set
|
|
|
@subheading CALLING SEQUENCE:
|
@subheading CALLING SEQUENCE:
|
|
|
@ifset is-C
|
@ifset is-C
|
@findex rtems_extension_create
|
@findex rtems_extension_create
|
@example
|
@example
|
rtems_status_code rtems_extension_create(
|
rtems_status_code rtems_extension_create(
|
rtems_name name,
|
rtems_name name,
|
rtems_extensions_table *table,
|
rtems_extensions_table *table,
|
rtems_id *id
|
rtems_id *id
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure Extension_Create (
|
procedure Extension_Create (
|
Name : in RTEMS.Name;
|
Name : in RTEMS.Name;
|
Table : in RTEMS.Extensions_Table_Pointer;
|
Table : in RTEMS.Extensions_Table_Pointer;
|
ID : out RTEMS.ID;
|
ID : out RTEMS.ID;
|
Result : out RTEMS.Status_Codes
|
Result : out RTEMS.Status_Codes
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
@subheading DIRECTIVE STATUS CODES:
|
@code{@value{RPREFIX}SUCCESSFUL} - extension set created successfully@*
|
@code{@value{RPREFIX}SUCCESSFUL} - extension set created successfully@*
|
@code{@value{RPREFIX}INVALID_NAME} - invalid extension set name@*
|
@code{@value{RPREFIX}INVALID_NAME} - invalid extension set name@*
|
@code{@value{RPREFIX}TOO_MANY} - too many extension sets created
|
@code{@value{RPREFIX}TOO_MANY} - too many extension sets created
|
|
|
@subheading DESCRIPTION:
|
@subheading DESCRIPTION:
|
|
|
This directive creates a extension set. The assigned
|
This directive creates a extension set. The assigned
|
extension set id is returned in id. This id is used to access
|
extension set id is returned in id. This id is used to access
|
the extension set with other user extension manager directives.
|
the extension set with other user extension manager directives.
|
For control and maintenance of the extension set, RTEMS
|
For control and maintenance of the extension set, RTEMS
|
allocates an ESCB from the local ESCB free pool and initializes
|
allocates an ESCB from the local ESCB free pool and initializes
|
it.
|
it.
|
|
|
@subheading NOTES:
|
@subheading NOTES:
|
|
|
This directive will not cause the calling task to be
|
This directive will not cause the calling task to be
|
preempted.
|
preempted.
|
|
|
@c
|
@c
|
@c
|
@c
|
@c
|
@c
|
@page
|
@page
|
@subsection EXTENSION_IDENT - Get ID of a extension set
|
@subsection EXTENSION_IDENT - Get ID of a extension set
|
|
|
@cindex get ID of an extension set
|
@cindex get ID of an extension set
|
@cindex obtain ID of an extension set
|
@cindex obtain ID of an extension set
|
|
|
@subheading CALLING SEQUENCE:
|
@subheading CALLING SEQUENCE:
|
|
|
@ifset is-C
|
@ifset is-C
|
@findex rtems_extension_ident
|
@findex rtems_extension_ident
|
@example
|
@example
|
rtems_status_code rtems_extension_ident(
|
rtems_status_code rtems_extension_ident(
|
rtems_name name,
|
rtems_name name,
|
rtems_id *id
|
rtems_id *id
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure Extension_Ident (
|
procedure Extension_Ident (
|
Name : in RTEMS.Name;
|
Name : in RTEMS.Name;
|
ID : out RTEMS.ID;
|
ID : out RTEMS.ID;
|
Result : out RTEMS.Status_Codes
|
Result : out RTEMS.Status_Codes
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
@subheading DIRECTIVE STATUS CODES:
|
@code{@value{RPREFIX}SUCCESSFUL} - extension set identified successfully@*
|
@code{@value{RPREFIX}SUCCESSFUL} - extension set identified successfully@*
|
@code{@value{RPREFIX}INVALID_NAME} - extension set name not found
|
@code{@value{RPREFIX}INVALID_NAME} - extension set name not found
|
|
|
@subheading DESCRIPTION:
|
@subheading DESCRIPTION:
|
|
|
This directive obtains the extension set id
|
This directive obtains the extension set id
|
associated with the extension set name to be acquired. If the
|
associated with the extension set name to be acquired. If the
|
extension set name is not unique, then the extension set id will
|
extension set name is not unique, then the extension set id will
|
match one of the extension sets with that name. However, this
|
match one of the extension sets with that name. However, this
|
extension set id is not guaranteed to correspond to the desired
|
extension set id is not guaranteed to correspond to the desired
|
extension set. The extension set id is used to access this
|
extension set. The extension set id is used to access this
|
extension set in other extension set related directives.
|
extension set in other extension set related directives.
|
|
|
@subheading NOTES:
|
@subheading NOTES:
|
|
|
This directive will not cause the running task to be
|
This directive will not cause the running task to be
|
preempted.
|
preempted.
|
|
|
@c
|
@c
|
@c
|
@c
|
@c
|
@c
|
@page
|
@page
|
@subsection EXTENSION_DELETE - Delete a extension set
|
@subsection EXTENSION_DELETE - Delete a extension set
|
|
|
@cindex delete an extension set
|
@cindex delete an extension set
|
|
|
@subheading CALLING SEQUENCE:
|
@subheading CALLING SEQUENCE:
|
|
|
@ifset is-C
|
@ifset is-C
|
@findex rtems_extension_delete
|
@findex rtems_extension_delete
|
@example
|
@example
|
rtems_status_code rtems_extension_delete(
|
rtems_status_code rtems_extension_delete(
|
rtems_id id
|
rtems_id id
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@ifset is-Ada
|
@ifset is-Ada
|
@example
|
@example
|
procedure Extension_Delete (
|
procedure Extension_Delete (
|
ID : in RTEMS.ID;
|
ID : in RTEMS.ID;
|
Result : out RTEMS.Status_Codes
|
Result : out RTEMS.Status_Codes
|
);
|
);
|
@end example
|
@end example
|
@end ifset
|
@end ifset
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
@subheading DIRECTIVE STATUS CODES:
|
@code{@value{RPREFIX}SUCCESSFUL} - extension set deleted successfully@*
|
@code{@value{RPREFIX}SUCCESSFUL} - extension set deleted successfully@*
|
@code{@value{RPREFIX}INVALID_ID} - invalid extension set id
|
@code{@value{RPREFIX}INVALID_ID} - invalid extension set id
|
|
|
@subheading DESCRIPTION:
|
@subheading DESCRIPTION:
|
|
|
This directive deletes the extension set specified by
|
This directive deletes the extension set specified by
|
id. If the extension set is running, it is automatically
|
id. If the extension set is running, it is automatically
|
canceled. The ESCB for the deleted extension set is reclaimed
|
canceled. The ESCB for the deleted extension set is reclaimed
|
by RTEMS.
|
by RTEMS.
|
|
|
@subheading NOTES:
|
@subheading NOTES:
|
|
|
This directive will not cause the running task to be
|
This directive will not cause the running task to be
|
preempted.
|
preempted.
|
|
|
A extension set can be deleted by a task other than
|
A extension set can be deleted by a task other than
|
the task which created the extension set.
|
the task which created the extension set.
|
|
|
@subheading NOTES:
|
@subheading NOTES:
|
|
|
This directive will not cause the running task to be
|
This directive will not cause the running task to be
|
preempted.
|
preempted.
|
|
|
