diff options
Diffstat (limited to '')
| -rw-r--r-- | c-user/fatal-error/background.rst (renamed from c-user/fatal_error.rst) | 300 |
1 files changed, 0 insertions, 300 deletions
diff --git a/c-user/fatal_error.rst b/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. |