[rtems-docs commit] Improve fatal error chapter
Sebastian Huber
sebh at rtems.org
Mon Dec 12 07:07:45 UTC 2016
Module: rtems-docs
Branch: master
Commit: 00ffe1fa6ba775628014b68b93e42722b36a742a
Changeset: http://git.rtems.org/rtems-docs/commit/?id=00ffe1fa6ba775628014b68b93e42722b36a742a
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Dec 9 10:55:29 2016 +0100
Improve fatal error chapter
Update #2825.
---
c-user/fatal_error.rst | 148 +++++++++++++++++++++++++++++++++++----------
c-user/initialization.rst | 31 +---------
c-user/user_extensions.rst | 2 +-
3 files changed, 117 insertions(+), 64 deletions(-)
diff --git a/c-user/fatal_error.rst b/c-user/fatal_error.rst
index e401db2..df8294b 100644
--- a/c-user/fatal_error.rst
+++ b/c-user/fatal_error.rst
@@ -128,70 +128,120 @@ fatal source. Each symbolic name has the corresponding numeric error code in
parenthesis.
INTERNAL_ERROR_TOO_LITTLE_WORKSPACE (2)
- Document me.
+ There is not enough memory for the workspace. This fatal error may occur
+ during system initialization. It is an application configuration error.
INTERNAL_ERROR_WORKSPACE_ALLOCATION (3)
- Document me.
+ An allocation from the workspace failed. This fatal error may occur during
+ system initialization. It is an application configuration error.
INTERNAL_ERROR_INTERRUPT_STACK_TOO_SMALL (4)
- Document me.
+ The configured interrupt stack size is too small. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
INTERNAL_ERROR_THREAD_EXITTED (5)
- Document me.
+ A non-POSIX thread entry function returned. This is an API usage error.
+
+ An example code to provoke this fatal error is:
+
+ .. code-block:: c
+
+ void task( rtems_arg arg )
+ {
+ /* Classic API tasks must not return */
+ }
+
+ void create_bad_task( void )
+ {
+ rtems_status_code sc;
+ rtems_id task_id;
+
+ sc = rtems_task_create(
+ rtems_build_name('T', 'A', 'S', 'K'),
+ 1,
+ RTEMS_DEFAULT_MODES,
+ RTEMS_DEFAULT_ATTRIBUTES,
+ &task_id
+ );
+ assert( sc == RTEMS_SUCCESSFUL );
+
+ sc = rtems_task_start( task_id, task, 0 );
+ assert( sc == RTEMS_SUCCESSFUL );
+ }
INTERNAL_ERROR_INCONSISTENT_MP_INFORMATION (6)
- Document me.
+ This fatal error can only occur on MPCI configurations. The MPCI nodes or
+ global objects configuration is inconsistent. This fatal error may occur
+ during system initialization. It is an application configuration error.
INTERNAL_ERROR_INVALID_NODE (7)
- Document me.
+ This fatal error can only occur on MPCI configurations. The own MPCI node
+ number is invalid. This fatal error may occur during system
+ initialization. It is an application configuration error.
INTERNAL_ERROR_NO_MPCI (8)
- Document me.
+ This fatal error can only occur on MPCI configurations. There is no MPCI
+ configuration table. This fatal error may occur during system
+ initialization. It is an application configuration error.
INTERNAL_ERROR_BAD_PACKET (9)
- Document me.
+ This fatal error can only occur on MPCI configurations. The MPCI server
+ thread received a bad packet.
INTERNAL_ERROR_OUT_OF_PACKETS (10)
- Document me.
+ This fatal error can only occur on MPCI configurations. The MPCI packet
+ pool is empty. It is an application configuration error.
INTERNAL_ERROR_OUT_OF_GLOBAL_OBJECTS (11)
- Document me.
+ This fatal error can only occur on MPCI configurations. The MPCI global
+ objects pool is empty. It is an application configuration error.
INTERNAL_ERROR_OUT_OF_PROXIES (12)
- Document me.
+ This fatal error can only occur on MPCI configurations. The MPCI thread
+ proxy pool is empty. It is an application configuration error.
INTERNAL_ERROR_INVALID_GLOBAL_ID (13)
- Document me.
+ This fatal error can only occur on MPCI configurations. The system cannot
+ find the global object for a specific object identifier. In case this
+ happens, then this is probably an operating system bug.
INTERNAL_ERROR_BAD_STACK_HOOK (14)
- Document me.
+ The stack allocator hook or stack free hook is NULL. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
INTERNAL_ERROR_UNLIMITED_AND_MAXIMUM_IS_0 (19)
- Document me.
-
-INTERNAL_ERROR_GXX_KEY_ADD_FAILED (21)
- Document me.
-
-INTERNAL_ERROR_GXX_MUTEX_INIT_FAILED (22)
- Document me.
+ An object class is configured to use the unlimited objects option, however,
+ the count of objects for each extension is zero. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
INTERNAL_ERROR_NO_MEMORY_FOR_HEAP (23)
- Document me.
+ There is not enough memory for the C program heap. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
INTERNAL_ERROR_CPU_ISR_INSTALL_VECTOR (24)
- Document me.
+ The use of :c:func:`_CPU_ISR_install_vector()` is illegal on this system.
INTERNAL_ERROR_RESOURCE_IN_USE (25)
- Document me.
+ This fatal error can only occur on debug configurations. It happens in
+ case a thread which owns mutexes is deleted. Mutexes owned by a deleted
+ thread are in an inconsistent state.
INTERNAL_ERROR_RTEMS_INIT_TASK_ENTRY_IS_NULL (26)
- Document me.
+ An RTEMS initialization task entry function is NULL. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
INTERNAL_ERROR_POSIX_INIT_THREAD_ENTRY_IS_NULL (27)
- Document me.
+ A POSIX initialization thread entry function is NULL. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
INTERNAL_ERROR_THREAD_QUEUE_DEADLOCK (28)
- Document me.
+ A deadlock was detected during a thread queue enqueue operation.
INTERNAL_ERROR_THREAD_QUEUE_ENQUEUE_STICKY_FROM_BAD_STATE (29)
This fatal error can only happen on SMP configurations. It is not allowed
@@ -258,10 +308,10 @@ INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL (30)
assert( 0 );
}
- void fire_bad_timer()
+ void fire_bad_timer( void )
{
rtems_status_code sc;
- rtems_id id;
+ rtems_id id;
sc = rtems_timer_create(
rtems_build_name( 'E', 'V', 'I', 'L' ),
@@ -301,6 +351,35 @@ INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT (31)
rtems_interrupt_local_enable( level );
}
+INTERNAL_ERROR_RTEMS_INIT_TASK_CREATE_FAILED (32)
+ Creation of an RTEMS initialization task failed. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
+
+INTERNAL_ERROR_POSIX_INIT_THREAD_CREATE_FAILED (33)
+ Creation of a POSIX initialization thread failed. This fatal error may
+ occur during system initialization. It is an application configuration
+ error.
+
+INTERNAL_ERROR_LIBIO_USER_ENV_KEY_CREATE_FAILED (34)
+ Creation of the IO library user environment POSIX key failed. This fatal
+ error may occur during system initialization. It is an application
+ configuration error.
+
+INTERNAL_ERROR_LIBIO_SEM_CREATE_FAILED (35)
+ Creation of the IO library semaphore failed. This fatal error may occur
+ during system initialization. It is an application configuration error.
+
+INTERNAL_ERROR_LIBIO_STDOUT_FD_OPEN_FAILED (36)
+ Open of the standard output file descriptor failed or resulted in an
+ unexpected file descriptor number. This fatal error may occur during
+ system initialization. It is an application configuration error.
+
+INTERNAL_ERROR_LIBIO_STDERR_FD_OPEN_FAILED (37)
+ Open of the standard error file descriptor failed or resulted in an
+ unexpected file descriptor number. This fatal error may occur during
+ system initialization. It is an application configuration error.
+
Operations
==========
@@ -338,7 +417,7 @@ The fatal handler are called with three parameters:
- the fatal source,
-- a legacy parameter, the internal error indicator, and
+- a legacy parameter which is always false, and
- an error code with a fatal source dependent content.
@@ -371,16 +450,19 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_fatal(
- rtems_fatal_source source,
- rtems_fatal_code error
+ 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 invokes the internal error handler with is internal set to
- false.
+ 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
diff --git a/c-user/initialization.rst b/c-user/initialization.rst
index 27dc148..4be322a 100644
--- a/c-user/initialization.rst
+++ b/c-user/initialization.rst
@@ -77,36 +77,7 @@ of any application.
Initialization Manager Failure
------------------------------
-The ``rtems_fatal_error_occurred`` directive will be invoked from
-``rtems_initialize_executive`` for any of the following reasons:
-
-- If either the Configuration Table or the CPU Dependent Information Table is
- not provided.
-
-- If the starting address of the RTEMS RAM Workspace, supplied by the
- application in the Configuration Table, is NULL or is not aligned on a
- four-byte boundary.
-
-- If the size of the RTEMS RAM Workspace is not large enough to initialize and
- configure the system.
-
-- If the interrupt stack size specified is too small.
-
-- If multiprocessing is configured and the node entry in the Multiprocessor
- Configuration Table is not between one and the maximum_nodes entry.
-
-- If a multiprocessor system is being configured and no Multiprocessor
- Communications Interface is specified.
-
-- If no user initialization tasks are configured. At least one initialization
- task must be configured to allow RTEMS to pass control to the application at
- the end of the executive initialization sequence.
-
-- If any of the user initialization tasks cannot be created or started
- successfully.
-
-A discussion of RTEMS actions when a fatal error occurs may be found
-:ref:`Announcing a Fatal Error`.
+System initialization errors are fatal. See :ref:`internal_errors`.
Operations
==========
diff --git a/c-user/user_extensions.rst b/c-user/user_extensions.rst
index 662ddf4..2b36afd 100644
--- a/c-user/user_extensions.rst
+++ b/c-user/user_extensions.rst
@@ -343,7 +343,7 @@ following:
void user_fatal_error(
Internal_errors_Source the_source,
- bool is_internal,
+ bool always_set_to_false,
uint32_t the_error
);
More information about the vc
mailing list