[PATCH 6/8] c-user: Generate fatal error manager docs
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Apr 21 13:50:04 UTC 2021
The documentation is a consolidation of the comments in Doxygen markup
and the documentation sources in Sphinx markup. The documentation was
transfered to interface specification items. The documentation source
files were generated from the items by a script.
Update #3993.
---
c-user/fatal-error/directives.rst | 397 ++++++++++++++++++----------
c-user/fatal-error/introduction.rst | 54 +++-
2 files changed, 306 insertions(+), 145 deletions(-)
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst
index 2d9a476..98ce209 100644
--- a/c-user/fatal-error/directives.rst
+++ b/c-user/fatal-error/directives.rst
@@ -1,226 +1,355 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. _FatalErrorManagerDirectives:
+
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.
+This section details the directives of the Fatal Error Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/fatal/if/fatal
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_fatal()
.. index:: announce fatal error
.. index:: fatal error, announce
-.. index:: rtems_fatal
-.. _rtems_fatal:
+.. _InterfaceRtemsFatal:
+
+rtems_fatal()
+-------------
+
+Invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_fatal(
+ rtems_fatal_source fatal_source,
+ rtems_fatal_code fatal_code
+ );
+
+.. rubric:: PARAMETERS:
+
+``fatal_source``
+ This parameter is the fatal source.
-FATAL - Invoke the fatal error handler
---------------------------------------
+``fatal_code``
+ This parameter is the fatal code.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: DESCRIPTION:
- void rtems_fatal(
- rtems_fatal_source fatal_source,
- rtems_fatal_code error_code
- ) RTEMS_NO_RETURN;
+This directive processes fatal errors. The fatal source is set to the value of
+the ``fatal_source`` parameter. The fatal code is set to the value of the
+``fatal_code`` parameter.
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
+.. rubric:: CONSTRAINTS:
-DESCRIPTION:
- This directive terminates the system.
+The following constraints apply to this directive:
-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.
+* The directive may be called from within any runtime context.
+
+* The directive will not return to the caller.
+
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
+
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
+
+* The directive may terminate the system.
+
+.. Generated from spec:/rtems/fatal/if/panic
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_panic()
.. index:: panic
-.. index:: rtems_panic
-.. _rtems_panic:
+.. _InterfaceRtemsPanic:
+
+rtems_panic()
+-------------
+
+Prints the message and invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-PANIC - Print a message and invoke the fatal error handler
-----------------------------------------------------------
+ void rtems_panic( const char *fmt, ... );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- void rtems_panic(
- const char *fmt,
- ...
- ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
+``fmt``
+ This parameter is the message format.
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
+``...``
+ This parameter is a list of optional parameters required by the message
+ format.
-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.
+.. rubric:: DESCRIPTION:
-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.
+This directive prints a message via :c:func:`printk` specified by the ``fmt``
+parameter and optional parameters and then invokes the fatal error handler.
+The fatal source is set to :c:macro:`RTEMS_FATAL_SOURCE_PANIC`. The fatal code
+is set to the value of the ``fmt`` parameter value.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not return to the caller.
+
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
+
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
+
+* The directive may terminate the system.
+
+.. Generated from spec:/rtems/fatal/if/shutdown-executive
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_shutdown_executive()
.. index:: shutdown RTEMS
-.. index:: rtems_shutdown_executive
-.. _rtems_shutdown_executive:
+.. _InterfaceRtemsShutdownExecutive:
+
+rtems_shutdown_executive()
+--------------------------
+
+Invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_shutdown_executive( uint32_t fatal_code );
+
+.. rubric:: PARAMETERS:
+
+``fatal_code``
+ This parameter is the fatal code.
+
+.. rubric:: DESCRIPTION:
+
+This directive processes fatal errors. The fatal source is set to
+:c:macro:`RTEMS_FATAL_SOURCE_EXIT`. The fatal code is set to the value of the
+``fatal_code`` parameter.
-SHUTDOWN_EXECUTIVE - Shutdown RTEMS
------------------------------------
+.. rubric:: CONSTRAINTS:
-CALLING SEQUENCE:
- .. code-block:: c
+The following constraints apply to this directive:
- void rtems_shutdown_executive(
- uint32_t result
- );
+* The directive may be called from within any runtime context.
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
+* The directive 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.
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
-NOTES:
- This directive *must* be the last RTEMS directive invoked by an application
- and it *does not return* to the caller.
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
- This directive may be called any time.
+* The directive may terminate the system.
+
+.. Generated from spec:/rtems/fatal/if/exception-frame-print
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_exception_frame_print()
.. index:: exception frame
-.. index:: rtems_exception_frame_print
-.. _rtems_exception_frame_print:
+.. _InterfaceRtemsExceptionFramePrint:
+
+rtems_exception_frame_print()
+-----------------------------
+
+Prints the exception frame.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
-EXCEPTION_FRAME_PRINT - Prints the exception frame
---------------------------------------------------
+ void rtems_exception_frame_print( const rtems_exception_frame *frame );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- void rtems_exception_frame_print(
- const rtems_exception_frame *frame
- );
+``frame``
+ This parameter is the reference to the exception frame to print.
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: DESCRIPTION:
-DESCRIPTION:
- Prints the exception frame via ``printk()``.
+The exception frame is printed in an architecture-dependent format using
+:c:func:`printk`.
+
+.. Generated from spec:/rtems/fatal/if/source-text
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_fatal_source_text()
.. index:: fatal error
-.. index:: rtems_fatal_source_text
-.. _rtems_fatal_source_text:
+.. _InterfaceRtemsFatalSourceText:
+
+rtems_fatal_source_text()
+-------------------------
+
+Returns a descriptive text for the fatal source.
+
+.. rubric:: CALLING SEQUENCE:
-FATAL_SOURCE_TEXT - Returns a text for a fatal source
------------------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ const char *rtems_fatal_source_text( rtems_fatal_source fatal_source );
- const char *rtems_fatal_source_text(
- rtems_fatal_source source
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- The fatal source text or "?" in case the passed fatal source is invalid.
+``fatal_source``
+ This parameter is the fatal source.
-DESCRIPTION:
- Returns a text for a fatal source. The text for fatal source is the
- enumerator constant.
+.. rubric:: RETURN VALUES:
+
+"?"
+ The ``fatal_source`` parameter value was not a fatal source.
+
+Returns a descriptive text for the fatal source. The text for the fatal source
+is the enumerator constant name.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+.. Generated from spec:/rtems/fatal/if/internal-error-text
.. raw:: latex
- \clearpage
+ \clearpage
+.. index:: rtems_internal_error_text()
.. index:: fatal error
-.. index:: rtems_internal_error_text
-.. _rtems_internal_error_text:
+.. _InterfaceRtemsInternalErrorText:
+
+rtems_internal_error_text()
+---------------------------
+
+Returns a descriptive text for the internal error code.
+
+.. rubric:: CALLING SEQUENCE:
-INTERNAL_ERROR_TEXT - Returns a text for an internal error code
----------------------------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ const char *rtems_internal_error_text( rtems_fatal_code internal_error_code );
- const char *rtems_internal_error_text(
- rtems_fatal_code error
- );
+.. rubric:: PARAMETERS:
-DIRECTIVE STATUS CODES:
- The error code text or "?" in case the passed error code is invalid.
+``internal_error_code``
+ This parameter is the internal error code.
-DESCRIPTION:
- Returns a text for an internal error code. The text for each internal
- error code is the enumerator constant.
+.. rubric:: RETURN VALUES:
+
+"?"
+ The ``internal_error_code`` parameter value was not an internal error code.
+
+Returns a descriptive text for the internal error code. The text for the
+internal error code is the enumerator constant name.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+.. Generated from spec:/rtems/fatal/if/error-occurred
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: announce fatal error
-.. index:: fatal error, announce
-.. index:: rtems_fatal_error_occurred
+.. index:: rtems_fatal_error_occurred()
+
+.. _InterfaceRtemsFatalErrorOccurred:
+
+rtems_fatal_error_occurred()
+----------------------------
+
+Invokes the fatal error handler.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ void rtems_fatal_error_occurred( uint32_t fatal_code );
+
+.. rubric:: PARAMETERS:
+
+``fatal_code``
+ This parameter is the fatal code.
+
+.. rubric:: DESCRIPTION:
-.. _rtems_fatal_error_occurred:
+This directive processes fatal errors. The fatal source is set to
+:c:macro:`INTERNAL_ERROR_RTEMS_API`. The fatal code is set to the value of the
+``fatal_code`` parameter.
-FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated)
-------------------------------------------------------------------
+.. rubric:: NOTES:
-CALLING SEQUENCE:
- .. code-block:: c
+This directive is deprecated and should not be used in new code. It is
+recommended to not use this directive since error locations cannot be uniquely
+identified. A recommended alternative directive is :ref:`InterfaceRtemsFatal`.
- void rtems_fatal_error_occurred(
- uint32_t the_error
- ) RTEMS_NO_RETURN;
+.. rubric:: CONSTRAINTS:
-DIRECTIVE STATUS CODES:
- NONE - This function will not return to the caller.
+The following constraints apply to this directive:
-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.
+* The directive may be called from within any runtime context.
-NOTES:
- This directive is deprecated and should not be used in new code.
+* The directive will not return to the caller.
- This directive supports local operations only.
+* The directive invokes the fatal error extensions in :term:`extension forward
+ order`.
- Unless the user-defined error extension takes special actions such as
- restarting the calling task, this directive WILL NOT RETURN to the caller.
+* The directive does not invoke handlers registered by :c:func:`atexit` or
+ :c:func:`on_exit`.
- The user-defined extension for this directive may wish to initiate a global
- shutdown.
+* The directive may terminate the system.
diff --git a/c-user/fatal-error/introduction.rst b/c-user/fatal-error/introduction.rst
index d862d4e..ff86922 100644
--- a/c-user/fatal-error/introduction.rst
+++ b/c-user/fatal-error/introduction.rst
@@ -1,25 +1,57 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+.. This file is part of the RTEMS quality process and was automatically
+.. generated. If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual. The manual is provided as a part of
+.. a release. For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/fatal/if/group
+
+.. _FatalErrorManagerIntroduction:
+
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:
+.. The following list was generated from:
+.. spec:/rtems/fatal/if/fatal
+.. spec:/rtems/fatal/if/panic
+.. spec:/rtems/fatal/if/shutdown-executive
+.. spec:/rtems/fatal/if/exception-frame-print
+.. spec:/rtems/fatal/if/source-text
+.. spec:/rtems/fatal/if/internal-error-text
+.. spec:/rtems/fatal/if/error-occurred
+
+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 and code pair. The directives provided by
+the Fatal Error Manager are:
-- :ref:`rtems_fatal`
+* :ref:`InterfaceRtemsFatal` - Invokes the fatal error handler.
-- :ref:`rtems_panic`
+* :ref:`InterfaceRtemsPanic` - Prints the message and invokes the fatal error
+ handler.
-- :ref:`rtems_shutdown_executive`
+* :ref:`InterfaceRtemsShutdownExecutive` - Invokes the fatal error handler.
-- :ref:`rtems_exception_frame_print`
+* :ref:`InterfaceRtemsExceptionFramePrint` - Prints the exception frame.
-- :ref:`rtems_fatal_source_text`
+* :ref:`InterfaceRtemsFatalSourceText` - Returns a descriptive text for the
+ fatal source.
-- :ref:`rtems_internal_error_text`
+* :ref:`InterfaceRtemsInternalErrorText` - Returns a descriptive text for the
+ internal error code.
-- :ref:`rtems_fatal_error_occurred`
+* :ref:`InterfaceRtemsFatalErrorOccurred` - Invokes the fatal error handler.
--
2.26.2
More information about the devel
mailing list