mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-15 03:57:14 +08:00
c-user: Split up user extensions manager
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
This commit is contained in:
Sebastian Huber
parent
a99bbaec5f
commit
80df4d6a47
@ -46,7 +46,7 @@ RTEMS Classic API Guide (|version|).
|
||||
io/index
|
||||
fatal_error
|
||||
board_support_packages
|
||||
user_extensions
|
||||
user-extensions/index
|
||||
config/index
|
||||
self_contained_objects
|
||||
multiprocessing
|
||||
|
||||
@ -2,27 +2,6 @@
|
||||
|
||||
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
.. index:: user extensions
|
||||
|
||||
.. _User Extensions Manager:
|
||||
|
||||
User Extensions Manager
|
||||
***********************
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
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. The directives provided by the user extensions manager
|
||||
are:
|
||||
|
||||
- rtems_extension_create_ - Create an extension set
|
||||
|
||||
- rtems_extension_ident_ - Get ID of an extension set
|
||||
|
||||
- rtems_extension_delete_ - Delete an extension set
|
||||
|
||||
Background
|
||||
==========
|
||||
|
||||
@ -431,143 +410,3 @@ It is strongly advised to use initial extension sets to install a fatal error
|
||||
extension. Usually, the initial extension set of board support package
|
||||
provides a fatal error extension which resets the board. In this case, the
|
||||
dynamic fatal error extensions are not invoked.
|
||||
|
||||
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.
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\clearpage
|
||||
|
||||
.. index:: create an extension set
|
||||
.. index:: rtems_extension_create
|
||||
|
||||
.. _rtems_extension_create:
|
||||
|
||||
EXTENSION_CREATE - Create a extension set
|
||||
-----------------------------------------
|
||||
|
||||
CALLING SEQUENCE:
|
||||
.. code-block:: c
|
||||
|
||||
rtems_status_code rtems_extension_create(
|
||||
rtems_name name,
|
||||
const rtems_extensions_table *table,
|
||||
rtems_id *id
|
||||
);
|
||||
|
||||
DIRECTIVE STATUS CODES:
|
||||
.. list-table::
|
||||
:class: rtems-table
|
||||
|
||||
* - ``RTEMS_SUCCESSFUL``
|
||||
- extension set created successfully
|
||||
* - ``RTEMS_INVALID_ADDRESS``
|
||||
- ``table`` or ``id`` are NULL
|
||||
* - ``RTEMS_INVALID_NAME``
|
||||
- invalid extension set name
|
||||
* - ``RTEMS_TOO_MANY``
|
||||
- too many extension sets created
|
||||
|
||||
DESCRIPTION:
|
||||
|
||||
This directive creates an extension set object and initializes it using the
|
||||
specified extension set table. The assigned extension set identifier is
|
||||
returned in :c:data:`id`. This identifier is used to access the extension
|
||||
set with other user extension manager directives. For control and
|
||||
maintenance of the extension set, RTEMS allocates an Extension Set Control
|
||||
Block (ESCB) from the local ESCB free pool and initializes it. The
|
||||
user-specified :c:data:`name` is assigned to the ESCB and may be used to
|
||||
identify the extension set via
|
||||
:ref:`rtems_extension_ident() <rtems_extension_ident>`. The extension set
|
||||
specified by :c:data:`table` is copied to the ESCB.
|
||||
|
||||
NOTES:
|
||||
This directive may cause the calling task to be preempted due to an
|
||||
obtain and release of the object allocator mutex.
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\clearpage
|
||||
|
||||
.. index:: get ID of an extension set
|
||||
.. index:: obtain ID of an extension set
|
||||
.. index:: rtems_extension_ident
|
||||
|
||||
.. _rtems_extension_ident:
|
||||
|
||||
EXTENSION_IDENT - Get ID of a extension set
|
||||
-------------------------------------------
|
||||
|
||||
CALLING SEQUENCE:
|
||||
.. code-block:: c
|
||||
|
||||
rtems_status_code rtems_extension_ident(
|
||||
rtems_name name,
|
||||
rtems_id *id
|
||||
);
|
||||
|
||||
DIRECTIVE STATUS CODES:
|
||||
.. list-table::
|
||||
:class: rtems-table
|
||||
|
||||
* - ``RTEMS_SUCCESSFUL``
|
||||
- extension set identified successfully
|
||||
* - ``RTEMS_INVALID_NAME``
|
||||
- extension set name not found
|
||||
|
||||
DESCRIPTION:
|
||||
This directive obtains the extension set identifier associated with the
|
||||
extension set :c:data:`name` to be acquired and returns it in :c:data:`id`.
|
||||
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.
|
||||
|
||||
NOTES:
|
||||
This directive will not cause the running task to be preempted.
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\clearpage
|
||||
|
||||
.. index:: delete an extension set
|
||||
.. index:: rtems_extension_delete
|
||||
|
||||
.. _rtems_extension_delete:
|
||||
|
||||
EXTENSION_DELETE - Delete a extension set
|
||||
-----------------------------------------
|
||||
|
||||
CALLING SEQUENCE:
|
||||
.. code-block:: c
|
||||
|
||||
rtems_status_code rtems_extension_delete(
|
||||
rtems_id id
|
||||
);
|
||||
|
||||
DIRECTIVE STATUS CODES:
|
||||
.. list-table::
|
||||
:class: rtems-table
|
||||
|
||||
* - ``RTEMS_SUCCESSFUL``
|
||||
- extension set deleted successfully
|
||||
* - ``RTEMS_INVALID_ID``
|
||||
- invalid extension set id
|
||||
|
||||
DESCRIPTION:
|
||||
This directive deletes the extension set specified by :c:data:`id`. If the
|
||||
extension set is running, it is automatically canceled. The ESCB for the
|
||||
deleted extension set is reclaimed by RTEMS.
|
||||
|
||||
NOTES:
|
||||
This directive may cause the calling task to be preempted due to an
|
||||
obtain and release of the object allocator mutex.
|
||||
|
||||
A extension set can be deleted by a task other than the task which created
|
||||
the extension set.
|
||||
143
c-user/user-extensions/directives.rst
Normal file
143
c-user/user-extensions/directives.rst
Normal file
@ -0,0 +1,143 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
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.
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\clearpage
|
||||
|
||||
.. index:: create an extension set
|
||||
.. index:: rtems_extension_create
|
||||
|
||||
.. _rtems_extension_create:
|
||||
|
||||
EXTENSION_CREATE - Create a extension set
|
||||
-----------------------------------------
|
||||
|
||||
CALLING SEQUENCE:
|
||||
.. code-block:: c
|
||||
|
||||
rtems_status_code rtems_extension_create(
|
||||
rtems_name name,
|
||||
const rtems_extensions_table *table,
|
||||
rtems_id *id
|
||||
);
|
||||
|
||||
DIRECTIVE STATUS CODES:
|
||||
.. list-table::
|
||||
:class: rtems-table
|
||||
|
||||
* - ``RTEMS_SUCCESSFUL``
|
||||
- extension set created successfully
|
||||
* - ``RTEMS_INVALID_ADDRESS``
|
||||
- ``table`` or ``id`` are NULL
|
||||
* - ``RTEMS_INVALID_NAME``
|
||||
- invalid extension set name
|
||||
* - ``RTEMS_TOO_MANY``
|
||||
- too many extension sets created
|
||||
|
||||
DESCRIPTION:
|
||||
|
||||
This directive creates an extension set object and initializes it using the
|
||||
specified extension set table. The assigned extension set identifier is
|
||||
returned in :c:data:`id`. This identifier is used to access the extension
|
||||
set with other user extension manager directives. For control and
|
||||
maintenance of the extension set, RTEMS allocates an Extension Set Control
|
||||
Block (ESCB) from the local ESCB free pool and initializes it. The
|
||||
user-specified :c:data:`name` is assigned to the ESCB and may be used to
|
||||
identify the extension set via
|
||||
:ref:`rtems_extension_ident() <rtems_extension_ident>`. The extension set
|
||||
specified by :c:data:`table` is copied to the ESCB.
|
||||
|
||||
NOTES:
|
||||
This directive may cause the calling task to be preempted due to an
|
||||
obtain and release of the object allocator mutex.
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\clearpage
|
||||
|
||||
.. index:: get ID of an extension set
|
||||
.. index:: obtain ID of an extension set
|
||||
.. index:: rtems_extension_ident
|
||||
|
||||
.. _rtems_extension_ident:
|
||||
|
||||
EXTENSION_IDENT - Get ID of a extension set
|
||||
-------------------------------------------
|
||||
|
||||
CALLING SEQUENCE:
|
||||
.. code-block:: c
|
||||
|
||||
rtems_status_code rtems_extension_ident(
|
||||
rtems_name name,
|
||||
rtems_id *id
|
||||
);
|
||||
|
||||
DIRECTIVE STATUS CODES:
|
||||
.. list-table::
|
||||
:class: rtems-table
|
||||
|
||||
* - ``RTEMS_SUCCESSFUL``
|
||||
- extension set identified successfully
|
||||
* - ``RTEMS_INVALID_NAME``
|
||||
- extension set name not found
|
||||
|
||||
DESCRIPTION:
|
||||
This directive obtains the extension set identifier associated with the
|
||||
extension set :c:data:`name` to be acquired and returns it in :c:data:`id`.
|
||||
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.
|
||||
|
||||
NOTES:
|
||||
This directive will not cause the running task to be preempted.
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\clearpage
|
||||
|
||||
.. index:: delete an extension set
|
||||
.. index:: rtems_extension_delete
|
||||
|
||||
.. _rtems_extension_delete:
|
||||
|
||||
EXTENSION_DELETE - Delete a extension set
|
||||
-----------------------------------------
|
||||
|
||||
CALLING SEQUENCE:
|
||||
.. code-block:: c
|
||||
|
||||
rtems_status_code rtems_extension_delete(
|
||||
rtems_id id
|
||||
);
|
||||
|
||||
DIRECTIVE STATUS CODES:
|
||||
.. list-table::
|
||||
:class: rtems-table
|
||||
|
||||
* - ``RTEMS_SUCCESSFUL``
|
||||
- extension set deleted successfully
|
||||
* - ``RTEMS_INVALID_ID``
|
||||
- invalid extension set id
|
||||
|
||||
DESCRIPTION:
|
||||
This directive deletes the extension set specified by :c:data:`id`. If the
|
||||
extension set is running, it is automatically canceled. The ESCB for the
|
||||
deleted extension set is reclaimed by RTEMS.
|
||||
|
||||
NOTES:
|
||||
This directive may cause the calling task to be preempted due to an
|
||||
obtain and release of the object allocator mutex.
|
||||
|
||||
A extension set can be deleted by a task other than the task which created
|
||||
the extension set.
|
||||
16
c-user/user-extensions/index.rst
Normal file
16
c-user/user-extensions/index.rst
Normal file
@ -0,0 +1,16 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
|
||||
|
||||
.. index:: user extensions
|
||||
|
||||
.. _User Extensions Manager:
|
||||
|
||||
User Extensions Manager
|
||||
***********************
|
||||
|
||||
.. toctree::
|
||||
|
||||
introduction
|
||||
background
|
||||
directives
|
||||
17
c-user/user-extensions/introduction.rst
Normal file
17
c-user/user-extensions/introduction.rst
Normal file
@ -0,0 +1,17 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
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. The directives provided by the user extensions manager
|
||||
are:
|
||||
|
||||
- :ref:`rtems_extension_create`
|
||||
|
||||
- :ref:`rtems_extension_ident`
|
||||
|
||||
- :ref:`rtems_extension_delete`
|
||||
Loading…
x
Reference in New Issue
Block a user