rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-24 00:49:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

c-user: Clarify user extensions

Browse Source 
Close #2367.
This commit is contained in:
Sebastian Huber 2017-08-24 09:56:37 +02:00
parent b6977f7909
commit 6eef7a4b15
1 changed files with 66 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
c-user/user_extensions.rst
View File

@ -28,7 +28,8 @@ are:
Background Background
========== ==========
User extensions are invoked when the following system events occur User extensions (call-back functions) are invoked by the system when the
following events occur
- thread creation, - thread creation,
@ -48,27 +49,27 @@ User extensions are invoked when the following system events occur
- fatal error detection (system termination). - fatal error detection (system termination).
The extensions have event-specific arguments, invocation orders and execution The user extensions have event-specific arguments, invocation orders and
contexts. Extension sets can be installed at run-time via execution contexts. Extension sets can be installed at run-time via
:ref:`rtems_extension_create() <rtems_extension_create>` (dynamic extension :ref:`rtems_extension_create() <rtems_extension_create>` (dynamic extension
sets) or at link-time via the application configuration option sets) or at link-time via the application configuration option
:ref:`CONFIGURE_INITIAL_EXTENSIONS <CONFIGURE_INITIAL_EXTENSIONS>` (initial :ref:`CONFIGURE_INITIAL_EXTENSIONS <CONFIGURE_INITIAL_EXTENSIONS>` (initial
extension sets). extension sets).
The execution context of extensions varies. Some extensions are invoked with The execution context of user extensions varies. Some user extensions are
ownership of the allocator mutex. The allocator mutex protects dynamic memory invoked with ownership of the allocator mutex. The allocator mutex protects
allocations and object creation/deletion. Some extensions are invoked with dynamic memory allocations and object creation/deletion. Some user extensions
thread dispatching disabled. The fatal error extension is invoked in an are invoked with thread dispatching disabled. The fatal error extension is
arbitrary context. invoked in an arbitrary context.
Extension Sets Extension Sets
-------------- --------------
.. index:: user extension set .. index:: user extension set
.. index:: rtems_extensions_table .. index:: rtems_extensions_table
User extensions are maintained as a set. All extensions are optional and may User extensions are maintained as a set. All user extensions are optional and
be `NULL`. Together a set of these extensions typically performs a specific may be `NULL`. Together a set of these user extensions typically performs a
functionality such as performance monitoring or debugger support. The user specific functionality such as performance monitoring or debugger support. The
extension set is defined via the following structure. extension set is defined via the following structure.
.. code-block:: c .. code-block:: c
@ -129,14 +130,15 @@ and release the extension buffers.
Order of Invocation Order of Invocation
------------------- -------------------
The extensions are invoked in either `forward` or `reverse` order. In forward The user extensions are invoked in either `forward` or `reverse` order. In
order the initial extensions are invoked before the dynamic extensions. The forward order, the user extensions of initial extension sets are invoked before
forward order of initial extensions is defined by the initial extensions table the user extensions of the dynamic extension sets. The forward order of
index. The forward order of dynamic extensions is defined by the order in initial extension sets is defined by the initial extension sets table index.
which the dynamic extensions were created. The reverse order is defined The forward order of dynamic extension sets is defined by the order in which
accordingly. By invoking the dynamic extensions in this order, extensions can the dynamic extension sets were created. The reverse order is defined
be built upon one another. At the following system events, the extensions are accordingly. By invoking the user extensions in this order, extensions can be
invoked in `forward` order built upon one another. At the following system events, the user extensions
are invoked in `forward` order
- thread creation, - thread creation,
@ -152,19 +154,20 @@ invoked in `forward` order
- fatal error detection. - fatal error detection.
At the following system events, the extensions are invoked in `reverse` order: At the following system events, the user extensions are invoked in `reverse`
order:
- thread termination, and - thread termination, and
- thread deletion. - thread deletion.
At these system events, the extensions are invoked in reverse order to insure At these system events, the user extensions are invoked in reverse order to insure
that if an extension set is built upon another, the more complicated extension that if an extension set is built upon another, the more complicated user extension
is invoked before the extension set it is built upon. An example is use of the is invoked before the user extension it is built upon. An example is use of the
thread delete extension by the Standard C Library. Extension sets which are thread delete extension by the Standard C Library. Extension sets which are
installed after the Standard C Library will operate correctly even if they installed after the Standard C Library will operate correctly even if they
utilize the C Library because the C Library's thread delete extension is utilize the C Library because the C Library's thread delete extension is
invoked after that of the other extensions. invoked after that of the other thread delete extensions.
Thread Create Extension Thread Create Extension
----------------------- -----------------------
@ -191,13 +194,13 @@ The executing thread is the owner of the allocator mutex except during creation
of the idle threads. Since the allocator mutex allows nesting the normal of the idle threads. Since the allocator mutex allows nesting the normal
memory allocation routines can be used. memory allocation routines can be used.
A thread create user extension will frequently attempt to allocate resources. A thread create extension will frequently attempt to allocate resources. If
If this allocation fails, then the extension must return :c:data:`false` and this allocation fails, then the thread create extension must return
the entire thread create operation will fail, otherwise it must return :c:data:`false` and the entire thread create operation will fail, otherwise it
:c:data:`true`. must return :c:data:`true`.
This extension is invoked in forward order with thread dispatching enabled The thread create extension is invoked in forward order with thread dispatching
(except during system initialization). enabled (except during system initialization).
Thread Start Extension Thread Start Extension
---------------------- ----------------------
@ -222,7 +225,8 @@ started thread has been made ready. So, in SMP configurations, the thread may
already run on another processor before the thread start extension is actually already run on another processor before the thread start extension is actually
invoked. invoked.
This extension is invoked in forward order with thread dispatching disabled. The thread start extension is invoked in forward order with thread dispatching
disabled.
Thread Restart Extension Thread Restart Extension
------------------------ ------------------------
@ -245,9 +249,10 @@ currently executing thread. It is invoked in the context of the executing
thread right before the execution context is reloaded. The thread stack thread right before the execution context is reloaded. The thread stack
reflects the previous execution context. reflects the previous execution context.
This extension is invoked in forward order with thread dispatching enabled The thread restart extension is invoked in forward order with thread
(except during system initialization). The thread life is protected. Thread dispatching enabled (except during system initialization). The thread life is
restart and delete requests issued by restart extensions lead to recursion. protected. Thread restart and delete requests issued by thread restart
extensions lead to recursion.
Thread Switch Extension Thread Switch Extension
----------------------- -----------------------
@ -268,12 +273,12 @@ defined as follows.
The :c:data:`executing` is a pointer to the TCB of the currently executing The :c:data:`executing` is a pointer to the TCB of the currently executing
thread. The :c:data:`heir` is a pointer to the TCB of the heir thread. thread. The :c:data:`heir` is a pointer to the TCB of the heir thread.
This extension is invoked in forward order with thread dispatching disabled. The thread switch extension is invoked in forward order with thread dispatching
In SMP configurations, interrupts are disabled and the per-processor SMP lock disabled. In SMP configurations, interrupts are disabled and the per-processor
is owned. SMP lock is owned.
The context switches initiated through the multitasking start are not covered The context switches initiated through the multitasking start are not covered
by this extension. by the thread switch extension.
Thread Begin Extension Thread Begin Extension
---------------------- ----------------------
@ -294,9 +299,9 @@ thread. The thread begin extension executes in a normal thread context and may
allocate resources for the thread. In particular it has access to thread-local allocate resources for the thread. In particular it has access to thread-local
storage of the thread. storage of the thread.
This extension is invoked in forward order with thread dispatching enabled. The thread begin extension is invoked in forward order with thread dispatching
The thread switch extension may be called multiple times for this thread before enabled. The thread switch extension may be called multiple times for this
the thread begin extension is invoked. thread before the thread begin extension is invoked.
Thread Exitted Extension Thread Exitted Extension
------------------------ ------------------------
@ -342,9 +347,9 @@ thread dispatch to the heir thread. The POSIX cleanup and key destructors
execute in this context. The thread termination extension has access to execute in this context. The thread termination extension has access to
thread-local storage and thread-specific data of POSIX keys. thread-local storage and thread-specific data of POSIX keys.
This extension is invoked in reverse order with thread dispatching enabled. The thread terminate extension is invoked in reverse order with thread
The thread life is protected. Thread restart and delete requests issued by dispatching enabled. The thread life is protected. Thread restart and delete
terminate extensions lead to recursion. requests issued by thread terminate extensions lead to recursion.
Thread Delete Extension Thread Delete Extension
----------------------- -----------------------
@ -369,7 +374,8 @@ The :c:data:`executing` and :c:data:`deleted` pointers are never equal.
The executing thread is the owner of the allocator mutex. Since the allocator The executing thread is the owner of the allocator mutex. Since the allocator
mutex allows nesting the normal memory allocation routines can be used. mutex allows nesting the normal memory allocation routines can be used.
This extension is invoked in reverse order with thread dispatching enabled. The thread delete extension is invoked in reverse order with thread dispatching
enabled.
Please note that a thread delete extension is not immediately invoked with a Please note that a thread delete extension is not immediately invoked with a
call to :ref:`rtems_task_delete() <rtems_task_delete>` or similar. The thread call to :ref:`rtems_task_delete() <rtems_task_delete>` or similar. The thread
@ -399,12 +405,12 @@ always set to :c:data:`false` and provided only for backward compatibility
reasons. The :c:data:`code` parameter is the fatal error code. This value reasons. The :c:data:`code` parameter is the fatal error code. This value
must be interpreted with respect to the source. must be interpreted with respect to the source.
This extension is invoked in forward order. The fatal error extension is invoked in forward order.
It is strongly advised to use initial extensions to install a fatal error It is strongly advised to use initial extension sets to install a fatal error
extension. Usually, the initial extensions of board support package provides a extension. Usually, the initial extension set of board support package
fatal error extension which resets the board. In this case, the dynamic fatal provides a fatal error extension which resets the board. In this case, the
error extensions are not invoked. dynamic fatal error extensions are not invoked.
Directives Directives
========== ==========
@ -446,15 +452,16 @@ DIRECTIVE STATUS CODES:
DESCRIPTION: DESCRIPTION:
This directive creates an extension set. The assigned extension set This directive creates an extension set object and initializes it using the
identifier is returned in :c:data:`id`. This identifier is used to access specified extension set table. The assigned extension set identifier is
the extension set with other user extension manager directives. For returned in :c:data:`id`. This identifier is used to access the extension
control and maintenance of the extension set, RTEMS allocates an Extension set with other user extension manager directives. For control and
Set Control Block (ESCB) from the local ESCB free pool and initializes it. maintenance of the extension set, RTEMS allocates an Extension Set Control
The user-specified :c:data:`name` is assigned to the ESCB and may be used Block (ESCB) from the local ESCB free pool and initializes it. The
to identify the extension set via :ref:`rtems_extension_ident() user-specified :c:data:`name` is assigned to the ESCB and may be used to
<rtems_extension_ident>`. The extension set specified by :c:data:`table` identify the extension set via
is copied to the ESCB. :ref:`rtems_extension_ident() <rtems_extension_ident>`. The extension set
specified by :c:data:`table` is copied to the ESCB.
NOTES: NOTES: