Rename all manuals with an _ to have a -. It helps released naming of files.

1 files changed, 0 insertions, 563 deletions

diff --git a/c_user/user_extensions.rst b/c_user/user_extensions.rst
deleted file mode 100644
index 664d70a..0000000
--- a/c_user/user_extensions.rst
+++ /dev/null
@@ -1,563 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-.. COMMENT: All rights reserved.
-
-.. _User Extensions Manager:
-
-User Extensions Manager
-#######################
-
-.. index:: user extensions
-
-Introduction
-============
-
-The RTEMS 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
-==========
-
-User extension routines are invoked when the following system events occur:
-
-- Task creation
-
-- Task initiation
-
-- Task reinitiation
-
-- Task deletion
-
-- Task context switch
-
-- Post task context switch
-
-- Task begin
-
-- Task exits
-
-- Fatal error detection
-
-These extensions are invoked as a function with arguments that are appropriate
-to the system event.
-
-Extension Sets
---------------
-.. index:: extension set
-
-An extension set is defined as a set of routines which are invoked at each of
-the critical system events at which user extension routines are invoked.
-Together a set of these routines typically perform a specific functionality
-such as performance monitoring or debugger support.  RTEMS is informed of the
-entry points which constitute an extension set via the following
-structure:.. index:: rtems_extensions_table
-
-.. code-block:: c
-
-    typedef struct {
-        rtems_task_create_extension      thread_create;
-        rtems_task_start_extension       thread_start;
-        rtems_task_restart_extension     thread_restart;
-        rtems_task_delete_extension      thread_delete;
-        rtems_task_switch_extension      thread_switch;
-        rtems_task_begin_extension       thread_begin;
-        rtems_task_exitted_extension     thread_exitted;
-        rtems_fatal_extension            fatal;
-    } rtems_extensions_table;
-
-RTEMS allows the user to have multiple extension sets active at the same time.
-First, a single static extension set may be defined as the application's User
-Extension Table which is included as part of the Configuration Table.  This
-extension set is active for the entire life of the system and may not be
-deleted.  This extension set is especially important because it is the only way
-the application can provided a FATAL error extension which is invoked if RTEMS
-fails during the initialize_executive directive.  The static extension set is
-optional and may be configured as NULL if no static extension set is required.
-
-Second, the user can install dynamic extensions using the
-``rtems_extension_create`` directive.  These extensions are RTEMS objects in
-that they have a name, an ID, and can be dynamically created and deleted.  In
-contrast to the static extension set, these extensions can only be created and
-installed after the initialize_executive directive successfully completes
-execution.  Dynamic extensions are useful for encapsulating the functionality
-of an extension set.  For example, the application could use extensions to
-manage a special coprocessor, do performance monitoring, and to do stack bounds
-checking.  Each of these extension sets could be written and installed
-independently of the others.
-
-All user extensions are optional and RTEMS places no naming restrictions on the
-user. The user extension entry points are copied into an internal RTEMS
-structure. This means the user does not need to keep the table after creating
-it, and changing the handler entry points dynamically in a table once created
-has no effect. Creating a table local to a function can save space in space
-limited applications.
-
-Extension switches do not effect the context switch overhead if no switch
-handler is installed.
-
-TCB Extension Area
-------------------
-.. index:: TCB extension area
-
-RTEMS provides for a pointer to a user-defined data 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 be used to store additional data required by the
-user's extension functions.
-
-The TCB extension is an array of pointers in the TCB. The index into the table
-can be obtained from the extension id returned when the extension is
-created:
-
-.. index:: rtems extensions table index
-
-.. code-block:: c
-
-    index = rtems_object_id_get_index(extension_id);
-
-The number of pointers in the area is the same as the number of user extension
-sets configured.  This allows an application to augment the TCB with
-user-defined information.  For example, an application could implement task
-profiling by storing timing statistics in the TCB's extended memory area.  When
-a task context switch is being executed, the ``TASK_SWITCH`` extension could
-read a real-time clock to calculate how long the task being swapped out has run
-as well as timestamp the starting time for the task being swapped in.
-
-If used, the extended memory area for the TCB should 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 ``TASK_START`` extension.  The application is
-responsible for managing this extended memory area for the TCBs.  The memory
-may be reinitialized by the ``TASK_RESTART`` extension and should be
-deallocated by the ``TASK_DELETE`` extension when the task is deleted.  Since
-the TCB extension buffers would most likely be of a fixed size, the RTEMS
-partition manager could be used to manage the application's extended memory
-area.  The application could create a partition of fixed size TCB extension
-buffers and use the partition manager's allocation and deallocation directives
-to obtain and release the extension buffers.
-
-Extensions
-----------
-
-The sections that follow will contain a description of each extension.  Each
-section will contain a prototype of a function with the appropriate calling
-sequence for the corresponding extension.  The names given for the C function
-and its arguments are all defined by the user.  The names used in the examples
-were arbitrarily chosen and impose no naming conventions on the user.
-
-TASK_CREATE Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The TASK_CREATE extension directly corresponds to the ``rtems_task_create``
-directive.  If this extension is defined in any static or dynamic extension set
-and a task is being created, then the extension routine will automatically be
-invoked by RTEMS.  The extension should have a prototype similar to the
-following:
-
-.. index:: rtems_task_create_extension
-.. index:: rtems_extension
-
-.. code-block:: c
-
-    bool user_task_create(
-       rtems_tcb *current_task,
-       rtems_tcb *new_task
-    );
-
-where ``current_task`` can be used to access the TCB for the currently
-executing task, and new_task can be used to access the TCB for the new task
-being created.  This extension is invoked from the ``rtems_task_create``
-directive after ``new_task`` has been completely initialized, but before it is
-placed on a ready TCB chain.
-
-The user extension is expected to return the boolean value ``true`` if it
-successfully executed and ``false`` otherwise.  A task create user extension
-will frequently attempt to allocate resources.  If this allocation fails, then
-the extension should return ``false`` and the entire task create operation will
-fail.
-
-TASK_START Extension
-~~~~~~~~~~~~~~~~~~~~
-
-The ``TASK_START`` extension directly corresponds to the task_start directive.
-If this extension is defined in any static or dynamic extension set and a task
-is being started, then the extension routine will automatically be invoked by
-RTEMS.  The extension should have a prototype similar to the following:
-
-.. index:: rtems_task_start_extension
-
-.. code-block:: c
-
-    void user_task_start(
-        rtems_tcb *current_task,
-        rtems_tcb *started_task
-    );
-
-where current_task can be used to access the TCB for the currently executing
-task, and started_task can be used to access the TCB for the dormant task being
-started. This extension is invoked from the task_start directive after
-started_task has been made ready to start execution, but before it is placed on
-a ready TCB chain.
-
-TASK_RESTART Extension
-~~~~~~~~~~~~~~~~~~~~~~
-
-The ``TASK_RESTART`` extension directly corresponds to the task_restart
-directive.  If this extension is defined in any static or dynamic extension set
-and a task is being restarted, then the extension should have a prototype
-similar to the following:
-
-.. index:: rtems_task_restart_extension
-
-.. code-block:: c
-
-    void user_task_restart(
-        rtems_tcb *current_task,
-        rtems_tcb *restarted_task
-    );
-
-where current_task can be used to access the TCB for the currently executing
-task, and restarted_task can be used to access the TCB for the task being
-restarted. This extension is invoked from the task_restart directive after
-restarted_task has been made ready to start execution, but before it is placed
-on a ready TCB chain.
-
-TASK_DELETE Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The ``TASK_DELETE`` extension is associated with the task_delete directive.  If
-this extension is defined in any static or dynamic extension set and a task is
-being deleted, then the extension routine will automatically be invoked by
-RTEMS.  The extension should have a prototype similar to the
-following:
-
-.. index:: rtems_task_delete_extension
-
-.. code-block:: c
-
-    void user_task_delete(
-        rtems_tcb *current_task,
-        rtems_tcb *deleted_task
-    );
-
-where current_task can be used to access the TCB for the currently executing
-task, and deleted_task can be used to access the TCB for the task being
-deleted. This extension is invoked from the task_delete directive after the TCB
-has been removed from a ready TCB chain, but before all its resources including
-the TCB have been returned to their respective free pools.  This extension
-should not call any RTEMS directives if a task is deleting itself (current_task
-is equal to deleted_task).
-
-TASK_SWITCH Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The ``TASK_SWITCH`` extension corresponds to a task context switch.  If this
-extension is defined in any static or dynamic extension set and a task context
-switch is in progress, then the extension routine will automatically be invoked
-by RTEMS.  The extension should have a prototype similar to the following:
-
-.. index:: rtems_task_switch_extension
-
-.. code-block:: c
-
-    void user_task_switch(
-        rtems_tcb *current_task,
-        rtems_tcb *heir_task
-    );
-
-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 access the TCB for the task being
-swapped in.  This extension is invoked from RTEMS' dispatcher routine after the
-current_task context has been saved, but before the heir_task context has been
-restored.  This extension should not call any RTEMS directives.
-
-TASK_BEGIN Extension
-~~~~~~~~~~~~~~~~~~~~
-
-The ``TASK_BEGIN`` extension is invoked when a task begins execution.  It is
-invoked immediately before the body of the starting procedure and executes in
-the context in the task.  This user extension have a prototype similar to the
-following:
-
-.. index:: rtems_task_begin_extension
-
-.. code-block:: c
-
-    void user_task_begin(
-        rtems_tcb *current_task
-    );
-
-where current_task can be used to access the TCB for the currently executing
-task which has begun.  The distinction between the ``TASK_BEGIN`` and
-TASK_START extension is that the ``TASK_BEGIN`` extension is executed in the
-context of the actual task while the TASK_START extension is executed in the
-context of the task performing the task_start directive.  For most extensions,
-this is not a critical distinction.
-
-TASK_EXITTED Extension
-~~~~~~~~~~~~~~~~~~~~~~
-
-The ``TASK_EXITTED`` extension is invoked when a task exits the body of the
-starting procedure by either an implicit or explicit return statement.  This
-user extension have a prototype similar to the following:
-
-.. index:: rtems_task_exitted_extension
-
-.. code-block:: c
-
-    void user_task_exitted(
-        rtems_tcb *current_task
-    );
-
-where current_task can be used to access the TCB for the currently executing
-task which has just exitted.
-
-Although exiting of task is often considered to be a fatal error, this
-extension allows recovery by either restarting or deleting the exiting task.
-If the user does not wish to recover, then a fatal error may be reported.  If
-the user does not provide a ``TASK_EXITTED`` extension or the provided handler
-returns control to RTEMS, then the RTEMS default handler will be used.  This
-default handler invokes the directive fatal_error_occurred with the
-``RTEMS_TASK_EXITTED`` directive status.
-
-FATAL Error Extension
-~~~~~~~~~~~~~~~~~~~~~
-
-The ``FATAL`` error extension is associated with the fatal_error_occurred
-directive.  If this extension is defined in any static or dynamic extension set
-and the fatal_error_occurred directive has been invoked, then this extension
-will be called.  This extension should have a prototype similar to the
-following:
-
-.. index:: rtems_fatal_extension
-
-.. code-block:: c
-
-    void user_fatal_error(
-        Internal_errors_Source  the_source,
-        bool                    is_internal,
-        uint32_t                the_error
-    );
-
-where the_error is the error code passed to the fatal_error_occurred
-directive. This extension is invoked from the fatal_error_occurred directive.
-
-If defined, the user's ``FATAL`` error extension is invoked before RTEMS'
-default fatal error routine is invoked and the processor is stopped.  For
-example, this extension could be used to pass control to a debugger when a
-fatal error occurs.  This extension should not call any RTEMS directives.
-
-Order of Invocation
--------------------
-
-When one of the critical system events occur, the user extensions are invoked
-in either "forward" or "reverse" order.  Forward order indicates that the
-static extension set is invoked followed by the dynamic extension sets in the
-order in which they were created.  Reverse order means that the dynamic
-extension sets are invoked in the opposite of the order in which they were
-created followed by the static extension set.  By invoking the extension sets
-in this order, extensions can be built upon one another.  At the following
-system events, the extensions are invoked in forward order:
-
-#. Task creation
-
-#. Task initiation
-
-#. Task reinitiation
-
-#. Task deletion
-
-#. Task context switch
-
-#. Post task context switch
-
-#. Task begins to execute
-
-At the following system events, the extensions are invoked in reverse order:
-
-#. Task deletion
-
-#. Fatal error detection
-
-At these system events, the extensions are invoked in reverse order to insure
-that if an extension set is built upon another, the more complicated extension
-is invoked before the extension set it is built upon.  For example, by invoking
-the static extension set last it is known that the "system" fatal error
-extension will be the last fatal error extension executed.  Another example is
-use of the task delete extension by the Standard C Library.  Extension sets
-which are installed after the Standard C Library will operate correctly even if
-they utilize the C Library because the C Library's ``TASK_DELETE`` extension is
-invoked after that of the other extensions.
-
-Operations
-==========
-
-Creating an Extension Set
--------------------------
-
-The ``rtems_extension_create`` directive creates and installs an extension set
-by allocating a Extension Set Control Block (ESCB), assigning the extension set
-a user-specified name, and assigning it an extension set ID.  Newly created
-extension sets are immediately installed and are invoked upon the next system
-even supporting an extension.
-
-Obtaining Extension Set IDs
----------------------------
-
-When an extension set is created, RTEMS generates a unique extension set ID and
-assigns it to the created extension set until it is deleted.  The extension ID
-may be obtained by either of two methods.  First, as the result of an
-invocation of the ``rtems_extension_create`` directive, the extension set ID is
-stored in a user provided location.  Second, the extension set ID may be
-obtained later using the ``rtems_extension_ident`` directive.  The extension
-set ID is used by other directives to manipulate this extension set.
-
-Deleting an Extension Set
--------------------------
-
-The ``rtems_extension_delete`` directive is used to delete an extension set.
-The extension set's control block is returned to the ESCB free list when it is
-deleted.  An extension set can be deleted by a task other than the task which
-created the extension set.  Any subsequent references to the extension's name
-and ID are invalid.
-
-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.
-
-.. _rtems_extension_create:
-
-EXTENSION_CREATE - Create a extension set
------------------------------------------
-.. index:: create an extension set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_extension_create
-
-.. code-block:: c
-
-    rtems_status_code rtems_extension_create(
-        rtems_name              name,
-        rtems_extensions_table *table,
-        rtems_id               *id
-    );
-
-**DIRECTIVE STATUS CODES:**
-
-.. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
-   - extension set created successfully
- * - ``RTEMS_INVALID_NAME``
-   - invalid extension set name
- * - ``RTEMS_TOO_MANY``
-   - too many extension sets created
-
-**DESCRIPTION:**
-
-This directive creates a extension set.  The assigned extension set id is
-returned in id.  This id is used to access the extension set with other user
-extension manager directives.  For control and maintenance of the extension
-set, RTEMS allocates an ESCB from the local ESCB free pool and initializes it.
-
-**NOTES:**
-
-This directive will not cause the calling task to be
-preempted.
-
-.. _rtems_extension_ident:
-
-EXTENSION_IDENT - Get ID of a extension set
--------------------------------------------
-.. index:: get ID of an extension set
-.. index:: obtain ID of an extension set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_extension_ident
-
-.. 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 id associated with the extension set
-name to be acquired.  If the extension set name is not unique, then the
-extension set id will match one of the extension sets with that name.  However,
-this extension set id is not guaranteed to correspond to the desired extension
-set.  The extension set id 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.
-
-.. _rtems_extension_delete:
-
-EXTENSION_DELETE - Delete a extension set
------------------------------------------
-.. index:: delete an extension set
-
-**CALLING SEQUENCE:**
-
-.. index:: rtems_extension_delete
-
-.. 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 ``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 will not cause the running task to be preempted.
-
-A extension set can be deleted by a task other than the task which created the
-extension set.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.