[PATCH v2 15/16] c-user: Split up user extensions manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:09 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
.../background.rst} | 161 ------------------
c-user/user-extensions/directives.rst | 143 ++++++++++++++++
c-user/user-extensions/index.rst | 16 ++
c-user/user-extensions/introduction.rst | 17 ++
5 files changed, 177 insertions(+), 162 deletions(-)
rename c-user/{user_extensions.rst => user-extensions/background.rst} (77%)
create mode 100644 c-user/user-extensions/directives.rst
create mode 100644 c-user/user-extensions/index.rst
create mode 100644 c-user/user-extensions/introduction.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index 3507947..07f13af 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -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
diff --git a/c-user/user_extensions.rst b/c-user/user-extensions/background.rst
similarity index 77%
rename from c-user/user_extensions.rst
rename to c-user/user-extensions/background.rst
index f5318da..2dc2577 100644
--- a/c-user/user_extensions.rst
+++ b/c-user/user-extensions/background.rst
@@ -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.
diff --git a/c-user/user-extensions/directives.rst b/c-user/user-extensions/directives.rst
new file mode 100644
index 0000000..5c6a0eb
--- /dev/null
+++ b/c-user/user-extensions/directives.rst
@@ -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.
diff --git a/c-user/user-extensions/index.rst b/c-user/user-extensions/index.rst
new file mode 100644
index 0000000..294fcac
--- /dev/null
+++ b/c-user/user-extensions/index.rst
@@ -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
diff --git a/c-user/user-extensions/introduction.rst b/c-user/user-extensions/introduction.rst
new file mode 100644
index 0000000..b567c36
--- /dev/null
+++ b/c-user/user-extensions/introduction.rst
@@ -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`
--
2.26.2
More information about the devel
mailing list