[PATCH 15/16] c-user: Split up user extensions manager

Sebastian Huber sebastian.huber at embedded-brains.de
Thu Aug 20 10:19:04 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/userext/directives.rst                 | 143 ++++++++++++++++
 c-user/userext/index.rst                      |  16 ++
 c-user/userext/introduction.rst               |  17 ++
 5 files changed, 177 insertions(+), 162 deletions(-)
 rename c-user/{user_extensions.rst => userext/background.rst} (77%)
 create mode 100644 c-user/userext/directives.rst
 create mode 100644 c-user/userext/index.rst
 create mode 100644 c-user/userext/introduction.rst

diff --git a/c-user/index.rst b/c-user/index.rst
index ca98118..e13b0fb 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
+	userext/index
 	config/index
 	self_contained_objects
 	multiprocessing
diff --git a/c-user/user_extensions.rst b/c-user/userext/background.rst
similarity index 77%
rename from c-user/user_extensions.rst
rename to c-user/userext/background.rst
index f5318da..2dc2577 100644
--- a/c-user/user_extensions.rst
+++ b/c-user/userext/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/userext/directives.rst b/c-user/userext/directives.rst
new file mode 100644
index 0000000..5c6a0eb
--- /dev/null
+++ b/c-user/userext/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/userext/index.rst b/c-user/userext/index.rst
new file mode 100644
index 0000000..294fcac
--- /dev/null
+++ b/c-user/userext/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/userext/introduction.rst b/c-user/userext/introduction.rst
new file mode 100644
index 0000000..b567c36
--- /dev/null
+++ b/c-user/userext/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