diff options
Diffstat (limited to 'c-user/fatal-error/directives.rst')
| -rw-r--r-- | c-user/fatal-error/directives.rst | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/c-user/fatal-error/directives.rst b/c-user/fatal-error/directives.rst new file mode 100644 index 0000000..434172f --- /dev/null +++ b/c-user/fatal-error/directives.rst @@ -0,0 +1,355 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG +.. 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 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 + +.. index:: rtems_fatal() +.. index:: announce fatal error +.. index:: fatal error, announce + +.. _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_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 + + \clearpage + +.. index:: rtems_panic() +.. index:: panic + +.. _InterfaceRtemsPanic: + +rtems_panic() +------------- + +Prints the message and invokes the fatal error handler. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_panic( const char *fmt, ... ); + +.. rubric:: PARAMETERS: + +``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 :ref:`InterfacePrintk` 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 + +.. index:: rtems_shutdown_executive() +.. index:: shutdown RTEMS + +.. _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. + +.. 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 + + \clearpage + +.. index:: rtems_exception_frame_print() +.. index:: exception frame + +.. _InterfaceRtemsExceptionFramePrint: + +rtems_exception_frame_print() +----------------------------- + +Prints the exception frame. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_exception_frame_print( const rtems_exception_frame *frame ); + +.. 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 +:ref:`InterfacePrintk`. + +.. Generated from spec:/rtems/fatal/if/source-text + +.. raw:: latex + + \clearpage + +.. index:: rtems_fatal_source_text() +.. index:: fatal error + +.. _InterfaceRtemsFatalSourceText: + +rtems_fatal_source_text() +------------------------- + +Returns a descriptive text for the fatal source. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_fatal_source_text( rtems_fatal_source fatal_source ); + +.. 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 + + \clearpage + +.. index:: rtems_internal_error_text() +.. index:: fatal error + +.. _InterfaceRtemsInternalErrorText: + +rtems_internal_error_text() +--------------------------- + +Returns a descriptive text for the internal error code. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + const char *rtems_internal_error_text( rtems_fatal_code internal_error_code ); + +.. 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 + + \clearpage + +.. 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: + +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. + +.. 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. |