c-user: Generate fatal error manager docs

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.
This commit is contained in:
Sebastian Huber 2021-04-21 10:50:00 +02:00
parent 5a3cb76d38
commit d946f307e9
2 changed files with 306 additions and 145 deletions

View File

@ -1,226 +1,355 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. 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) .. 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 Directives
========== ==========
This section details the fatal error manager's directives. A subsection is This section details the directives of the Fatal Error Manager. A subsection is
dedicated to each of this manager's directives and describes the calling dedicated to each of this manager's directives and lists the calling sequence,
sequence, related constants, usage, and status codes. parameters, description, return values, and notes of the directive.
.. Generated from spec:/rtems/fatal/if/fatal
.. raw:: latex .. raw:: latex
\clearpage \clearpage
.. index:: rtems_fatal()
.. index:: announce fatal error .. index:: announce fatal error
.. index:: fatal error, announce .. index:: fatal error, announce
.. index:: rtems_fatal
.. _rtems_fatal: .. _InterfaceRtemsFatal:
FATAL - Invoke the fatal error handler rtems_fatal()
-------------------------------------- -------------
CALLING SEQUENCE: Invokes the fatal error handler.
.. code-block:: c
void rtems_fatal( .. rubric:: CALLING SEQUENCE:
rtems_fatal_source fatal_source,
rtems_fatal_code error_code
) RTEMS_NO_RETURN;
DIRECTIVE STATUS CODES: .. code-block:: c
NONE - This function will not return to the caller.
DESCRIPTION: void rtems_fatal(
This directive terminates the system. rtems_fatal_source fatal_source,
rtems_fatal_code fatal_code
);
NOTE: .. rubric:: PARAMETERS:
Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
called. Use :c:func:`exit()` in case these handlers should be invoked. ``fatal_source``
This parameter is the fatal source.
``fatal_code``
This parameter is the fatal code.
.. rubric:: DESCRIPTION:
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.
.. 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/panic
.. raw:: latex .. raw:: latex
\clearpage \clearpage
.. index:: rtems_panic()
.. index:: panic .. index:: panic
.. index:: rtems_panic
.. _rtems_panic: .. _InterfaceRtemsPanic:
PANIC - Print a message and invoke the fatal error handler rtems_panic()
---------------------------------------------------------- -------------
CALLING SEQUENCE: Prints the message and invokes the fatal error handler.
.. code-block:: c
void rtems_panic( .. rubric:: CALLING SEQUENCE:
const char *fmt,
...
) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 );
DIRECTIVE STATUS CODES: .. code-block:: c
NONE - This function will not return to the caller.
DESCRIPTION: void rtems_panic( const char *fmt, ... );
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: .. rubric:: PARAMETERS:
Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not
called. Use :c:func:`exit()` in case these handlers should be invoked. ``fmt``
This parameter is the message format.
``...``
This parameter is a list of optional parameters required by the message
format.
.. rubric:: DESCRIPTION:
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 .. raw:: latex
\clearpage \clearpage
.. index:: rtems_shutdown_executive()
.. index:: shutdown RTEMS .. index:: shutdown RTEMS
.. index:: rtems_shutdown_executive
.. _rtems_shutdown_executive: .. _InterfaceRtemsShutdownExecutive:
SHUTDOWN_EXECUTIVE - Shutdown RTEMS rtems_shutdown_executive()
----------------------------------- --------------------------
CALLING SEQUENCE: Invokes the fatal error handler.
.. code-block:: c
void rtems_shutdown_executive( .. rubric:: CALLING SEQUENCE:
uint32_t result
);
DIRECTIVE STATUS CODES: .. code-block:: c
NONE - This function will not return to the caller.
DESCRIPTION: void rtems_shutdown_executive( uint32_t fatal_code );
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: .. rubric:: PARAMETERS:
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. ``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.
.. 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/exception-frame-print
.. raw:: latex .. raw:: latex
\clearpage \clearpage
.. index:: rtems_exception_frame_print()
.. index:: exception frame .. index:: exception frame
.. index:: rtems_exception_frame_print
.. _rtems_exception_frame_print: .. _InterfaceRtemsExceptionFramePrint:
EXCEPTION_FRAME_PRINT - Prints the exception frame rtems_exception_frame_print()
-------------------------------------------------- -----------------------------
CALLING SEQUENCE: Prints the exception frame.
.. code-block:: c
void rtems_exception_frame_print( .. rubric:: CALLING SEQUENCE:
const rtems_exception_frame *frame
);
DIRECTIVE STATUS CODES: .. code-block:: c
NONE
DESCRIPTION: void rtems_exception_frame_print( const rtems_exception_frame *frame );
Prints the exception frame via ``printk()``.
.. rubric:: PARAMETERS:
``frame``
This parameter is the reference to the exception frame to print.
.. rubric:: DESCRIPTION:
The exception frame is printed in an architecture-dependent format using
:c:func:`printk`.
.. Generated from spec:/rtems/fatal/if/source-text
.. raw:: latex .. raw:: latex
\clearpage \clearpage
.. index:: rtems_fatal_source_text()
.. index:: fatal error .. index:: fatal error
.. index:: rtems_fatal_source_text
.. _rtems_fatal_source_text: .. _InterfaceRtemsFatalSourceText:
FATAL_SOURCE_TEXT - Returns a text for a fatal source rtems_fatal_source_text()
----------------------------------------------------- -------------------------
CALLING SEQUENCE: Returns a descriptive text for the fatal source.
.. code-block:: c
const char *rtems_fatal_source_text( .. rubric:: CALLING SEQUENCE:
rtems_fatal_source source
);
DIRECTIVE STATUS CODES: .. code-block:: c
The fatal source text or "?" in case the passed fatal source is invalid.
DESCRIPTION: const char *rtems_fatal_source_text( rtems_fatal_source fatal_source );
Returns a text for a fatal source. The text for fatal source is the
enumerator constant. .. rubric:: PARAMETERS:
``fatal_source``
This parameter is the fatal source.
.. 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 .. raw:: latex
\clearpage \clearpage
.. index:: rtems_internal_error_text()
.. index:: fatal error .. index:: fatal error
.. index:: rtems_internal_error_text
.. _rtems_internal_error_text: .. _InterfaceRtemsInternalErrorText:
INTERNAL_ERROR_TEXT - Returns a text for an internal error code rtems_internal_error_text()
--------------------------------------------------------------- ---------------------------
CALLING SEQUENCE: Returns a descriptive text for the internal error code.
.. code-block:: c
const char *rtems_internal_error_text( .. rubric:: CALLING SEQUENCE:
rtems_fatal_code error
);
DIRECTIVE STATUS CODES: .. code-block:: c
The error code text or "?" in case the passed error code is invalid.
DESCRIPTION: const char *rtems_internal_error_text( rtems_fatal_code internal_error_code );
Returns a text for an internal error code. The text for each internal
error code is the enumerator constant. .. rubric:: PARAMETERS:
``internal_error_code``
This parameter is the internal error code.
.. 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 .. raw:: latex
\clearpage \clearpage
.. index:: announce fatal error .. index:: rtems_fatal_error_occurred()
.. index:: fatal error, announce
.. index:: rtems_fatal_error_occurred
.. _rtems_fatal_error_occurred: .. _InterfaceRtemsFatalErrorOccurred:
FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated) rtems_fatal_error_occurred()
------------------------------------------------------------------ ----------------------------
CALLING SEQUENCE: Invokes the fatal error handler.
.. code-block:: c
void rtems_fatal_error_occurred( .. rubric:: CALLING SEQUENCE:
uint32_t the_error
) RTEMS_NO_RETURN;
DIRECTIVE STATUS CODES: .. code-block:: c
NONE - This function will not return to the caller.
DESCRIPTION: void rtems_fatal_error_occurred( uint32_t fatal_code );
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: .. rubric:: PARAMETERS:
This directive is deprecated and should not be used in new code.
This directive supports local operations only. ``fatal_code``
This parameter is the fatal code.
Unless the user-defined error extension takes special actions such as .. rubric:: DESCRIPTION:
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 This directive processes fatal errors. The fatal source is set to
shutdown. :c:macro:`INTERNAL_ERROR_RTEMS_API`. The fatal code is set to the value of the
``fatal_code`` parameter.
.. rubric:: NOTES:
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`.
.. 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.

View File

@ -1,25 +1,57 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. 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) .. 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 Introduction
============ ============
The fatal error manager processes all fatal or irrecoverable errors and other .. The following list was generated from:
sources of system termination (for example after :c:func:`exit()`). Fatal .. spec:/rtems/fatal/if/fatal
errors are identified by the (fatal source, error code) pair. The directives .. spec:/rtems/fatal/if/panic
provided by the fatal error manager are: .. 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
- :ref:`rtems_fatal` 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_panic` * :ref:`InterfaceRtemsFatal` - Invokes the fatal error handler.
- :ref:`rtems_shutdown_executive` * :ref:`InterfaceRtemsPanic` - Prints the message and invokes the fatal error
handler.
- :ref:`rtems_exception_frame_print` * :ref:`InterfaceRtemsShutdownExecutive` - Invokes the fatal error handler.
- :ref:`rtems_fatal_source_text` * :ref:`InterfaceRtemsExceptionFramePrint` - Prints the exception frame.
- :ref:`rtems_internal_error_text` * :ref:`InterfaceRtemsFatalSourceText` - Returns a descriptive text for the
fatal source.
- :ref:`rtems_fatal_error_occurred` * :ref:`InterfaceRtemsInternalErrorText` - Returns a descriptive text for the
internal error code.
* :ref:`InterfaceRtemsFatalErrorOccurred` - Invokes the fatal error handler.