score: Add rtems_fatal()

cpukit/sapi/Makefile.am

@@ -37,7 +37,8 @@ libsapi_a_SOURCES = src/debug.c src/extension.c src/extensioncreate.c \
     src/iounregisterdriver.c src/iowrite.c src/posixapi.c  \
     src/rtemsapi.c src/extensiondata.c src/getversionstring.c \
     src/chainappendnotify.c src/chaingetnotify.c src/chaingetwait.c \
-    src/chainprependnotify.c src/rbheap.c src/interrdesc.c
+    src/chainprependnotify.c src/rbheap.c src/interrdesc.c \
+    src/fatal2.c
 libsapi_a_CPPFLAGS = $(AM_CPPFLAGS)
 
 include $(srcdir)/preinstall.am

cpukit/sapi/include/rtems/fatal.h

@@ -1,13 +1,9 @@
 /**
- * @file rtems/fatal.h
+ * @file
  *
- * This include file contains constants and prototypes related
- * to the Fatal Error Manager.  This manager processes all fatal or
- * irrecoverable errors.
+ * @ingroup ClassicFatal
  *
- * This manager provides directives to:
- *
- *   - announce a fatal error has occurred
+ * @brief Fatal API.
  */
 
 /*
@@ -29,20 +25,46 @@
 extern "C" {
 #endif
 
-/*
- *  rtems_fatal_error_occurred
+/**
+ * @defgroup ClassicFatal Fatal
  *
- *  DESCRIPTION:
+ * @ingroup ClassicRTEMS
  *
- *  This is the routine which implements the rtems_fatal_error_occurred
- *  directive.  It is invoked when the application or RTEMS
- *  determines that a fatal error has occurred.
+ * @brief The Fatal Manager provides functions for fatal system states and or
+ * irrecoverable errors.
+ *
+ * @{
  */
 
+/**
+ * @brief Invokes the internal error handler with a source of
+ * INTERNAL_ERROR_RTEMS_API and is internal set to false.
+ *
+ * @param[in] the_error A 32-bit fatal error code.
+ *
+ * @return This function will not return.
+ *
+ * @see _Internal_error_Occurred().
+ */
 void rtems_fatal_error_occurred(
   uint32_t   the_error
 ) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
+/**
+ * @brief Invokes the internal error handler with is internal set to false.
+ *
+ * @param[in] source The fatal source.
+ * @param[in] error The fatal code.
+ *
+ * @return This function will not return.
+ *
+ * @see _Internal_error_Occurred().
+ */
+void rtems_fatal(
+  rtems_fatal_source source,
+  rtems_fatal_code error
+) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
+
 /**
  * @brief Returns a description for an internal error code.
  *
@@ -53,6 +75,8 @@ void rtems_fatal_error_occurred(
  */
 const char *rtems_internal_error_description( rtems_fatal_code error );
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

cpukit/sapi/src/fatal2.c

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
+ *
+ *  embedded brains GmbH
+ *  Obere Lagerstr. 30
+ *  82178 Puchheim
+ *  Germany
+ *  <rtems@embedded-brains.de>
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.com/license/LICENSE.
+ */
+
+#if HAVE_CONFIG_H
+  #include "config.h"
+#endif
+
+#include <rtems/fatal.h>
+
+void rtems_fatal(
+  rtems_fatal_source source,
+  rtems_fatal_code error
+)
+{
+  _Internal_error_Occurred( source, false, error );
+}

doc/user/fatal.t

@@ -15,6 +15,7 @@ manager is:
 
 @itemize @bullet
 @item @code{@value{DIRPREFIX}fatal_error_occurred} - Invoke the fatal error handler
+@item @code{@value{DIRPREFIX}fatal} - Invoke the fatal error handler with error source
 @end itemize
 
 @section Background
@@ -168,6 +169,36 @@ NOT RETURN to the caller.
 The user-defined extension for this directive may
 wish to initiate a global shutdown.
 
+@c
+@c
+@c
+@page
+@subsection FATAL - Invoke the fatal error handler with error source
+
+@cindex announce fatal error
+@cindex fatal error, announce
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_fatal
+@example
+void rtems_fatal(
+  rtems_fatal_source source,
+  rtems_fatal_code error
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive invokes the internal error handler with is internal set to
+false.  See also @code{@value{DIRPREFIX}fatal_error_occurred}.
+
 @c
 @c
 @c