From 97ba94b929cb273efe3227c248c56ae0812b8dc1 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 22 Jun 2020 11:41:37 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/fatal.h | 284 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 229 insertions(+), 55 deletions(-) diff --git a/cpukit/include/rtems/fatal.h b/cpukit/include/rtems/fatal.h index 228e7462e0..0253ab4343 100644 --- a/cpukit/include/rtems/fatal.h +++ b/cpukit/include/rtems/fatal.h @@ -1,132 +1,306 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @brief Fatal API. + * @brief This header file defines the Fatal Error Manager API. */ /* - * COPYRIGHT (c) 1989-2011. - * On-Line Applications Research Corporation (OAR). + * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ +/* + * 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 + */ + +/* Generated from spec:/rtems/fatal/if/header */ + #ifndef _RTEMS_FATAL_H #define _RTEMS_FATAL_H -#include +#include #include +#include +#include +#include #ifdef __cplusplus extern "C" { #endif +/* Generated from spec:/rtems/fatal/if/group */ + /** - * @defgroup ClassicFatal Fatal + * @defgroup RTEMSAPIClassicFatal Fatal Error Manager * * @ingroup RTEMSAPIClassic * - * @brief The Fatal Manager provides functions for fatal system states and or - * irrecoverable errors. + * @brief The Fatal Error Manager processes all fatal or irrecoverable errors + * and other sources of system termination (for example after exit()). Fatal + * errors are identified by the fatal source and code pair. */ -/**@{**/ + +/* Generated from spec:/rtems/fatal/if/assert-context */ /** - * @brief Assert context. + * @ingroup RTEMSAPIClassicFatal + * + * @brief This structure provides the context in which an assertion failed. */ typedef struct { + /** + * @brief This member provides the file name of the source code file containing + * the failed assertion statement. + */ const char *file; - int line; + + /** + * @brief This member provides the line number in the source code file + * containing the failed assertion statement. + */ + int line; + + /** + * @brief This member provides the function name containing the failed + * assertion statement. + */ const char *function; + + /** + * @brief This member provides the expression of the failed assertion + * statement. + */ const char *failed_expression; } rtems_assert_context; +/* Generated from spec:/rtems/fatal/if/exception-frame */ + /** - * @brief Exception frame. + * @ingroup RTEMSAPIClassicFatal + * + * @brief This structure represents an architecture-dependent exception frame. */ typedef CPU_Exception_frame rtems_exception_frame; +/* Generated from spec:/rtems/fatal/if/fatal */ + /** - * @brief Prints the exception frame via printk(). + * @ingroup RTEMSAPIClassicFatal + * + * @brief Invokes the fatal error handler. + * + * @param fatal_source is the fatal source. + * + * @param fatal_code is the fatal code. + * + * 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. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. * - * @see rtems_fatal() and RTEMS_FATAL_SOURCE_EXCEPTION. + * * 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. + * @endparblock */ -static inline void rtems_exception_frame_print( - const rtems_exception_frame *frame +RTEMS_NO_RETURN static inline void rtems_fatal( + rtems_fatal_source fatal_source, + rtems_fatal_code fatal_code ) { - _CPU_Exception_frame_print( frame ); + _Terminate( fatal_source, fatal_code ); } +/* Generated from spec:/rtems/fatal/if/panic */ + /** - * @brief Invokes the internal error handler with a source of - * INTERNAL_ERROR_RTEMS_API and is internal set to false. + * @ingroup RTEMSAPIClassicFatal * - * @param[in] the_error is a 32-bit fatal error code. + * @brief Prints the message and invokes the fatal error handler. * - * @see _Terminate(). + * @param fmt is the message format. + * + * @param ... is a list of optional parameters required by the message format. + * + * 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. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -RTEMS_NO_RETURN void rtems_fatal_error_occurred( uint32_t the_error ); +RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 ) void rtems_panic( + const char *fmt, + ... +); + +/* Generated from spec:/rtems/fatal/if/exception-frame-print */ /** - * @brief Terminates the system. + * @ingroup RTEMSAPIClassicFatal * - * @param[in] fatal_source The fatal source. - * @param[in] error_code The error code. + * @brief Prints the exception frame. * - * @see _Terminate(). + * @param frame is the reference to the exception frame to print. + * + * The exception frame is printed in an architecture-dependent format using + * printk(). */ -RTEMS_NO_RETURN RTEMS_INLINE_ROUTINE void rtems_fatal( - rtems_fatal_source fatal_source, - rtems_fatal_code error_code +static inline void rtems_exception_frame_print( + const rtems_exception_frame *frame ) { - _Terminate( fatal_source, error_code ); + _CPU_Exception_frame_print( frame ); } +/* Generated from spec:/rtems/fatal/if/source-text */ + /** - * @brief Prints the specified message via printk() and terminates the system. + * @ingroup RTEMSAPIClassicFatal + * + * @brief Returns a descriptive text for the fatal source. + * + * @param fatal_source is the fatal source. * - * @param[in] fmt The message format. - * @param[in] ... The message parameters. + * @retval "?" The ``fatal_source`` parameter value was not a fatal source. * - * @see _Terminate(). + * @return Returns a descriptive text for the fatal source. The text for the + * fatal source is the enumerator constant name. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * @endparblock */ -RTEMS_NO_RETURN void rtems_panic( - const char *fmt, ... -) RTEMS_PRINTFLIKE( 1, 2 ); +const char *rtems_fatal_source_text( rtems_fatal_source fatal_source ); + +/* Generated from spec:/rtems/fatal/if/internal-error-text */ /** - * @brief Returns a text for a fatal source. + * @ingroup RTEMSAPIClassicFatal + * + * @brief Returns a descriptive text for the internal error code. * - * The text for each fatal source is the enumerator constant. + * @param internal_error_code is the internal error code. * - * @param[in] source is the fatal source. + * @retval "?" The ``internal_error_code`` parameter value was not an internal + * error code. * - * @retval text The fatal source text. - * @retval "?" The passed fatal source is invalid. + * @return Returns a descriptive text for the internal error code. The text + * for the internal error code is the enumerator constant name. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * @endparblock */ -const char *rtems_fatal_source_text( rtems_fatal_source source ); +const char *rtems_internal_error_text( rtems_fatal_code internal_error_code ); + +/* Generated from spec:/rtems/fatal/if/error-occurred */ /** - * @brief Returns a text for an internal error code. + * @ingroup RTEMSAPIClassicFatal + * + * @brief Invokes the fatal error handler. * - * The text for each internal error code is the enumerator constant. + * @param fatal_code is the fatal code. * - * @param[in] error is the error code. + * 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. * - * @retval text The error code text. - * @retval "?" The passed error code is invalid. + * @par 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -const char *rtems_internal_error_text( rtems_fatal_code error ); - -/** @} */ +RTEMS_NO_RETURN void rtems_fatal_error_occurred( uint32_t fatal_code ); #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_FATAL_H */ -- cgit v1.2.3