[PATCH 2/8] c-user: Split up fatal error manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Apr 21 13:50:00 UTC 2021
This makes it easier to automatically generate parts of the module
documentation in the future.
Update #3993.
---
.../background.rst} | 300 ------------------
c-user/fatal-error/directives.rst | 226 +++++++++++++
c-user/fatal-error/index.rst | 17 +
c-user/fatal-error/introduction.rst | 25 ++
c-user/fatal-error/operations.rst | 51 +++
c-user/index.rst | 2 +-
c-user/initialization/introduction.rst | 2 +-
7 files changed, 321 insertions(+), 302 deletions(-)
rename c-user/{fatal_error.rst => fatal-error/background.rst} (62%)
create mode 100644 c-user/fatal-error/directives.rst
create mode 100644 c-user/fatal-error/index.rst
create mode 100644 c-user/fatal-error/introduction.rst
create mode 100644 c-user/fatal-error/operations.rst
diff --git a/c-user/fatal_error.rst b/c-user/fatal-error/background.rst
similarity index 62%
rename from c-user/fatal_error.rst
rename to c-user/fatal-error/background.rst
index 81cfa0c..571da10 100644
--- a/c-user/fatal_error.rst
+++ b/c-user/fatal-error/background.rst
@@ -2,35 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: fatal errors
-
-.. _fatal_error_manager:
-
-Fatal Error Manager
-*******************
-
-Introduction
-============
-
-The fatal error manager processes all fatal or irrecoverable errors and other
-sources of system termination (for example after :c:func:`exit()`). Fatal
-errors are identified by the (fatal source, error code) pair. The directives
-provided by the fatal error manager are:
-
-- rtems_fatal_ - Invoke the fatal error handler
-
-- rtems_panic_ - Print a message and invoke the fatal error handler
-
-- rtems_shutdown_executive_ - Shutdown RTEMS
-
-- rtems_exception_frame_print_ - Print the CPU exception frame
-
-- rtems_fatal_source_text_ - Return the fatal source text
-
-- rtems_internal_error_text_ - Return the error code text
-
-- rtems_fatal_error_occurred_ - Invoke the fatal error handler (deprecated)
-
Background
==========
@@ -383,274 +354,3 @@ INTERNAL_ERROR_TOO_LARGE_TLS_SIZE (41)
:ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE <CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE>`.
You can get the thread-local storage size of an application using the RTEMS
tool ``rtems-execinfo``.
-
-Operations
-==========
-
-.. index:: _Terminate
-
-.. _Terminate:
-
-Announcing a Fatal Error
-------------------------
-
-The :c:func:`_Terminate()` internal error handler is invoked when the
-application or the executive itself determines that a fatal error has occurred
-or a final system state is reached (for example after :c:func:`rtems_fatal()`
-or :c:func:`exit()`).
-
-The first action of the internal error handler is to call the fatal extension of
-the user extensions. For the initial extensions the following conditions are
-required
-
-- a valid stack pointer and enough stack space,
-
-- a valid code memory, and
-
-- valid read-only data.
-
-For the initial extensions the read-write data (including .bss segment) is not
-required on single processor configurations. In SMP configurations, however,
-the read-write data must be initialized since this function must determine the
-state of the other processors and request them to shut-down if necessary.
-
-Non-initial extensions require in addition valid read-write data. The board
-support package (BSP) may install an initial extension that performs a system
-reset. In this case the non-initial extensions will be not called.
-
-The fatal extensions are called with three parameters:
-
-- the fatal source,
-
-- a legacy parameter which is always false, and
-
-- an error code with a fatal source dependent content.
-
-Once all fatal extensions executed, the error information will be stored to
-:c:data:`_Internal_errors_What_happened` and the system state is set to
-:c:macro:`SYSTEM_STATE_TERMINATED`.
-
-The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`.
-
-Directives
-==========
-
-This section details the fatal error 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:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal
-
-.. _rtems_fatal:
-
-FATAL - Invoke the fatal error handler
---------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_fatal(
- rtems_fatal_source fatal_source,
- rtems_fatal_code error_code
- ) RTEMS_NO_RETURN;
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive terminates the system.
-
-NOTE:
- Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
- called. Use :c:func:`exit()` in case these handlers should be invoked.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: panic
-.. index:: rtems_panic
-
-.. _rtems_panic:
-
-PANIC - Print a message and invoke the fatal error handler
-----------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_panic(
- const char *fmt,
- ...
- ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive prints a message via :c:func:`printk` specified by the
- format and optional parameters and then terminates the system with the
- :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source. The fatal code is set to
- the format string address.
-
-NOTE:
- Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
- called. Use :c:func:`exit()` in case these handlers should be invoked.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: shutdown RTEMS
-.. index:: rtems_shutdown_executive
-
-.. _rtems_shutdown_executive:
-
-SHUTDOWN_EXECUTIVE - Shutdown RTEMS
------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_shutdown_executive(
- uint32_t result
- );
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive is called when the application wishes to shutdown RTEMS.
- The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
- and the specified ``result`` code.
-
-NOTES:
- This directive *must* be the last RTEMS directive invoked by an application
- and it *does not return* to the caller.
-
- This directive may be called any time.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: exception frame
-.. index:: rtems_exception_frame_print
-
-.. _rtems_exception_frame_print:
-
-EXCEPTION_FRAME_PRINT - Prints the exception frame
---------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_exception_frame_print(
- const rtems_exception_frame *frame
- );
-
-DIRECTIVE STATUS CODES:
- NONE
-
-DESCRIPTION:
- Prints the exception frame via ``printk()``.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: fatal error
-.. index:: rtems_fatal_source_text
-
-.. _rtems_fatal_source_text:
-
-FATAL_SOURCE_TEXT - Returns a text for a fatal source
------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- const char *rtems_fatal_source_text(
- rtems_fatal_source source
- );
-
-DIRECTIVE STATUS CODES:
- The fatal source text or "?" in case the passed fatal source is invalid.
-
-DESCRIPTION:
- Returns a text for a fatal source. The text for fatal source is the
- enumerator constant.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: fatal error
-.. index:: rtems_internal_error_text
-
-.. _rtems_internal_error_text:
-
-INTERNAL_ERROR_TEXT - Returns a text for an internal error code
----------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- const char *rtems_internal_error_text(
- rtems_fatal_code error
- );
-
-DIRECTIVE STATUS CODES:
- The error code text or "?" in case the passed error code is invalid.
-
-DESCRIPTION:
- Returns a text for an internal error code. The text for each internal
- error code is the enumerator constant.
-
-.. raw:: latex
-
- \clearpage
-
-.. index:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal_error_occurred
-
-.. _rtems_fatal_error_occurred:
-
-FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
-------------------------------------------------------------------
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- void rtems_fatal_error_occurred(
- uint32_t the_error
- ) RTEMS_NO_RETURN;
-
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
-
-DESCRIPTION:
- This directive processes fatal errors. If the FATAL error extension is
- defined in the configuration table, then the user-defined error extension
- is called. If configured and the provided FATAL error extension returns,
- then the RTEMS default error handler is invoked. This directive can be
- invoked by RTEMS or by the user's application code including initialization
- tasks, other tasks, and ISRs.
-
-NOTES:
- This directive is deprecated and should not be used in new code.
-
- This directive supports local operations only.
-
- Unless the user-defined error extension takes special actions such as
- restarting the calling task, this directive WILL NOT RETURN to the caller.
-
- The user-defined extension for this directive may wish to initiate a global
- shutdown.
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst
new file mode 100644
index 0000000..2d9a476
--- /dev/null
+++ b/c-user/fatal-error/directives.rst
@@ -0,0 +1,226 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+This section details the fatal error 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:: announce fatal error
+.. index:: fatal error, announce
+.. index:: rtems_fatal
+
+.. _rtems_fatal:
+
+FATAL - Invoke the fatal error handler
+--------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ void rtems_fatal(
+ rtems_fatal_source fatal_source,
+ rtems_fatal_code error_code
+ ) RTEMS_NO_RETURN;
+
+DIRECTIVE STATUS CODES:
+ NONE - This function will not return to the caller.
+
+DESCRIPTION:
+ This directive terminates the system.
+
+NOTE:
+ Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
+ called. Use :c:func:`exit()` in case these handlers should be invoked.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: panic
+.. index:: rtems_panic
+
+.. _rtems_panic:
+
+PANIC - Print a message and invoke the fatal error handler
+----------------------------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ void rtems_panic(
+ const char *fmt,
+ ...
+ ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
+
+DIRECTIVE STATUS CODES:
+ NONE - This function will not return to the caller.
+
+DESCRIPTION:
+ This directive prints a message via :c:func:`printk` specified by the
+ format and optional parameters and then terminates the system with the
+ :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source. The fatal code is set to
+ the format string address.
+
+NOTE:
+ Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
+ called. Use :c:func:`exit()` in case these handlers should be invoked.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: shutdown RTEMS
+.. index:: rtems_shutdown_executive
+
+.. _rtems_shutdown_executive:
+
+SHUTDOWN_EXECUTIVE - Shutdown RTEMS
+-----------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ void rtems_shutdown_executive(
+ uint32_t result
+ );
+
+DIRECTIVE STATUS CODES:
+ NONE - This function will not return to the caller.
+
+DESCRIPTION:
+ This directive is called when the application wishes to shutdown RTEMS.
+ The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT``
+ and the specified ``result`` code.
+
+NOTES:
+ This directive *must* be the last RTEMS directive invoked by an application
+ and it *does not return* to the caller.
+
+ This directive may be called any time.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: exception frame
+.. index:: rtems_exception_frame_print
+
+.. _rtems_exception_frame_print:
+
+EXCEPTION_FRAME_PRINT - Prints the exception frame
+--------------------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ void rtems_exception_frame_print(
+ const rtems_exception_frame *frame
+ );
+
+DIRECTIVE STATUS CODES:
+ NONE
+
+DESCRIPTION:
+ Prints the exception frame via ``printk()``.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: fatal error
+.. index:: rtems_fatal_source_text
+
+.. _rtems_fatal_source_text:
+
+FATAL_SOURCE_TEXT - Returns a text for a fatal source
+-----------------------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ const char *rtems_fatal_source_text(
+ rtems_fatal_source source
+ );
+
+DIRECTIVE STATUS CODES:
+ The fatal source text or "?" in case the passed fatal source is invalid.
+
+DESCRIPTION:
+ Returns a text for a fatal source. The text for fatal source is the
+ enumerator constant.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: fatal error
+.. index:: rtems_internal_error_text
+
+.. _rtems_internal_error_text:
+
+INTERNAL_ERROR_TEXT - Returns a text for an internal error code
+---------------------------------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ const char *rtems_internal_error_text(
+ rtems_fatal_code error
+ );
+
+DIRECTIVE STATUS CODES:
+ The error code text or "?" in case the passed error code is invalid.
+
+DESCRIPTION:
+ Returns a text for an internal error code. The text for each internal
+ error code is the enumerator constant.
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: announce fatal error
+.. index:: fatal error, announce
+.. index:: rtems_fatal_error_occurred
+
+.. _rtems_fatal_error_occurred:
+
+FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
+------------------------------------------------------------------
+
+CALLING SEQUENCE:
+ .. code-block:: c
+
+ void rtems_fatal_error_occurred(
+ uint32_t the_error
+ ) RTEMS_NO_RETURN;
+
+DIRECTIVE STATUS CODES:
+ NONE - This function will not return to the caller.
+
+DESCRIPTION:
+ This directive processes fatal errors. If the FATAL error extension is
+ defined in the configuration table, then the user-defined error extension
+ is called. If configured and the provided FATAL error extension returns,
+ then the RTEMS default error handler is invoked. This directive can be
+ invoked by RTEMS or by the user's application code including initialization
+ tasks, other tasks, and ISRs.
+
+NOTES:
+ This directive is deprecated and should not be used in new code.
+
+ This directive supports local operations only.
+
+ Unless the user-defined error extension takes special actions such as
+ restarting the calling task, this directive WILL NOT RETURN to the caller.
+
+ The user-defined extension for this directive may wish to initiate a global
+ shutdown.
diff --git a/c-user/fatal-error/index.rst b/c-user/fatal-error/index.rst
new file mode 100644
index 0000000..89cbe30
--- /dev/null
+++ b/c-user/fatal-error/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: fatal errors
+
+.. _RTEMSAPIClassicFatal:
+
+Fatal Error Manager
+*******************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst
new file mode 100644
index 0000000..d862d4e
--- /dev/null
+++ b/c-user/fatal-error/introduction.rst
@@ -0,0 +1,25 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The fatal error manager processes all fatal or irrecoverable errors and other
+sources of system termination (for example after :c:func:`exit()`). Fatal
+errors are identified by the (fatal source, error code) pair. The directives
+provided by the fatal error manager are:
+
+- :ref:`rtems_fatal`
+
+- :ref:`rtems_panic`
+
+- :ref:`rtems_shutdown_executive`
+
+- :ref:`rtems_exception_frame_print`
+
+- :ref:`rtems_fatal_source_text`
+
+- :ref:`rtems_internal_error_text`
+
+- :ref:`rtems_fatal_error_occurred`
diff --git a/c-user/fatal-error/operations.rst b/c-user/fatal-error/operations.rst
new file mode 100644
index 0000000..77753d6
--- /dev/null
+++ b/c-user/fatal-error/operations.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+.. index:: _Terminate
+
+.. _Terminate:
+
+Announcing a Fatal Error
+------------------------
+
+The :c:func:`_Terminate()` internal error handler is invoked when the
+application or the executive itself determines that a fatal error has occurred
+or a final system state is reached (for example after :c:func:`rtems_fatal()`
+or :c:func:`exit()`).
+
+The first action of the internal error handler is to call the fatal extension of
+the user extensions. For the initial extensions the following conditions are
+required
+
+- a valid stack pointer and enough stack space,
+
+- a valid code memory, and
+
+- valid read-only data.
+
+For the initial extensions the read-write data (including .bss segment) is not
+required on single processor configurations. In SMP configurations, however,
+the read-write data must be initialized since this function must determine the
+state of the other processors and request them to shut-down if necessary.
+
+Non-initial extensions require in addition valid read-write data. The board
+support package (BSP) may install an initial extension that performs a system
+reset. In this case the non-initial extensions will be not called.
+
+The fatal extensions are called with three parameters:
+
+- the fatal source,
+
+- a legacy parameter which is always false, and
+
+- an error code with a fatal source dependent content.
+
+Once all fatal extensions executed, the error information will be stored to
+:c:data:`_Internal_errors_What_happened` and the system state is set to
+:c:macro:`SYSTEM_STATE_TERMINATED`.
+
+The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`.
diff --git a/c-user/index.rst b/c-user/index.rst
index 0a05c75..267d56c 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -44,7 +44,7 @@ RTEMS Classic API Guide (|version|).
region/index
dual-ported-memory/index
io/index
- fatal_error
+ fatal-error/index
board_support_packages
user-extensions/index
config/index
diff --git a/c-user/initialization/introduction.rst b/c-user/initialization/introduction.rst
index ae14fb0..88805f2 100644
--- a/c-user/initialization/introduction.rst
+++ b/c-user/initialization/introduction.rst
@@ -7,7 +7,7 @@ Introduction
The Initialization Manager is responsible for initializing the Board Support
Package, RTEMS, device drivers, the root filesystem and the application. The
-:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
+:ref:`RTEMSAPIClassicFatal` is responsible for the system
shutdown.
The Initialization Manager provides only one directive:
--
2.26.2
More information about the devel
mailing list