Directives

23.4. 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.

23.4.1. rtems_fatal()#

Invokes the fatal error handler.

CALLING SEQUENCE:

void rtems_fatal(
  rtems_fatal_source fatal_source,
  rtems_fatal_code   fatal_code
);

PARAMETERS:

fatal_source

This parameter is the fatal source.

fatal_code

This parameter is the fatal code.

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.

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 extension forward order.

  • The directive does not invoke handlers registered by atexit() or on_exit().

  • The directive may terminate the system.

23.4.2. rtems_panic()#

Prints the message and invokes the fatal error handler.

CALLING SEQUENCE:

void rtems_panic( const char *fmt, ... );

PARAMETERS:

fmt

This parameter is the message format.

...

This parameter is a list of optional parameters required by the message format.

DESCRIPTION:

This directive prints a message via printk() specified by the fmt parameter and optional parameters and then invokes the fatal error handler. The fatal source is set to RTEMS_FATAL_SOURCE_PANIC. The fatal code is set to the value of the fmt parameter value.

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 extension forward order.

  • The directive does not invoke handlers registered by atexit() or on_exit().

  • The directive may terminate the system.

23.4.3. rtems_shutdown_executive()#

Invokes the fatal error handler.

CALLING SEQUENCE:

void rtems_shutdown_executive( uint32_t fatal_code );

PARAMETERS:

fatal_code

This parameter is the fatal code.

DESCRIPTION:

This directive processes fatal errors. The fatal source is set to RTEMS_FATAL_SOURCE_EXIT. The fatal code is set to the value of the fatal_code parameter.

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 extension forward order.

  • The directive does not invoke handlers registered by atexit() or on_exit().

  • The directive may terminate the system.

23.4.4. rtems_exception_frame_print()#

Prints the exception frame.

CALLING SEQUENCE:

void rtems_exception_frame_print( const rtems_exception_frame *frame );

PARAMETERS:

frame

This parameter is the reference to the exception frame to print.

DESCRIPTION:

The exception frame is printed in an architecture-dependent format using printk().

23.4.5. rtems_fatal_source_text()#

Returns a descriptive text for the fatal source.

CALLING SEQUENCE:

const char *rtems_fatal_source_text( rtems_fatal_source fatal_source );

PARAMETERS:

fatal_source

This parameter is the fatal source.

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.

CONSTRAINTS:

The following constraints apply to this directive:

  • The directive may be called from within any runtime context.

23.4.6. rtems_internal_error_text()#

Returns a descriptive text for the internal error code.

CALLING SEQUENCE:

const char *rtems_internal_error_text( rtems_fatal_code internal_error_code );

PARAMETERS:

internal_error_code

This parameter is the internal error code.

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.

CONSTRAINTS:

The following constraints apply to this directive:

  • The directive may be called from within any runtime context.

23.4.7. rtems_fatal_error_occurred()#

Invokes the fatal error handler.

CALLING SEQUENCE:

void rtems_fatal_error_occurred( uint32_t fatal_code );

PARAMETERS:

fatal_code

This parameter is the fatal code.

DESCRIPTION:

This directive processes fatal errors. The fatal source is set to INTERNAL_ERROR_RTEMS_API. The fatal code is set to the value of the fatal_code parameter.

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 rtems_fatal().

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 extension forward order.

  • The directive does not invoke handlers registered by atexit() or on_exit().

  • The directive may terminate the system.