michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: provide error handling documentation

Browse source 
We don't really have docs on how fatal errors are induced
or handled. Provide some documentation that covers:

- Assertions (runtime and build)
- Kernel panic and oops conditions
- Stack overflows
- Other exceptions
- Exception handling policy

Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
This commit is contained in:
Andrew Boie 2019-09-14 23:40:03 -07:00 • committed by Ioannis Glaropoulos
commit 4ce988ab43
5 changed files with 282 additions and 57 deletions
Download patch file Download diff file Expand all files Collapse all files

54
include/sys/__assert.h
View file

@ -4,60 +4,6 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @file
* @brief Debug aid
*
*
* The __ASSERT() macro can be used inside kernel code.
*
* Assertions are enabled by setting the __ASSERT_ON symbol to a non-zero value.
* There are two ways to do this:
* a) Use the ASSERT and ASSERT_LEVEL kconfig options
* b) Add "CFLAGS += -D__ASSERT_ON=<level>" at the end of a project's Makefile
* The Makefile method takes precedence over the kconfig option if both are
* used.
*
* Specifying an assertion level of 1 causes the compiler to issue warnings that
* the kernel contains debug-type __ASSERT() statements; this reminder is issued
* since assertion code is not normally present in a final product. Specifying
* assertion level 2 suppresses these warnings.
*
* The __ASSERT_EVAL() macro can also be used inside kernel code.
*
* It makes use of the __ASSERT() macro, but has some extra flexibility. It
* allows the developer to specify different actions depending whether the
* __ASSERT() macro is enabled or not. This can be particularly useful to
* prevent the compiler from generating comments (errors, warnings or remarks)
* about variables that are only used with __ASSERT() being assigned a value,
* but otherwise unused when the __ASSERT() macro is disabled.
*
* Consider the following example:
*
* int x;
*
* x = foo ();
* __ASSERT (x != 0, "foo() returned zero!");
*
* If __ASSERT() is disabled, then 'x' is assigned a value, but never used.
* This type of situation can be resolved using the __ASSERT_EVAL() macro.
*
* __ASSERT_EVAL ((void) foo(),
* int x = foo(),
* x != 0,
* "foo() returned zero!");
*
* The first parameter tells __ASSERT_EVAL() what to do if __ASSERT() is
* disabled. The second parameter tells __ASSERT_EVAL() what to do if
* __ASSERT() is enabled. The third and fourth parameters are the parameters
* it passes to __ASSERT().
*
* The __ASSERT_NO_MSG() macro can be used to perform an assertion that reports
* the failed test and its location, but lacks additional debugging information
* provided to assist the user in diagnosing the problem; its use is
* discouraged.
*/
#ifndef ZEPHYR_INCLUDE_SYS___ASSERT_H_
#define ZEPHYR_INCLUDE_SYS___ASSERT_H_