From 2bd18edc84b4d9be3a251880d4921f58b0f11d5f Mon Sep 17 00:00:00 2001 From: Julius Werner Date: Thu, 15 Dec 2022 08:56:14 -0800 Subject: coding_style: Add more guidelines on error handling, die() and assert() This patch adds a new section to the coding style which codifies existing practices about how to handle errors and how to use the die() and assert() macros. Also clean up some references to Linux-specific facilities that do not exist in coreboot in the adjacent function return type guidelines, and add a small blurb of documentation to the definition of the assert() macro itself. Signed-off-by: Julius Werner Change-Id: Ice37ed9f995a56d69476e95a352209041b337284 Reviewed-on: https://review.coreboot.org/c/coreboot/+/70775 Reviewed-by: Elyes Haouas Tested-by: build bot (Jenkins) Reviewed-by: Martin L Roth --- src/include/assert.h | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'src/include') diff --git a/src/include/assert.h b/src/include/assert.h index 93d6bfc412..8729bef9f7 100644 --- a/src/include/assert.h +++ b/src/include/assert.h @@ -40,7 +40,18 @@ void mock_assert(const int result, const char *const expression, #define MOCK_ASSERT(result, expression) #endif -/* GCC and CAR versions */ +/* + * assert() should be used to test stuff that the programmer *knows* to be true. + * It should not be used to test something that may actually change at runtime + * (e.g. anything involving hardware accesses). For example, testing whether + * function parameters match the documented requirements is a good use of + * assert() (where it is still the responsibility of the caller to ensure it + * passes valid values, and the callee is just double-checking). + * + * Depending on CONFIG(FATAL_ASSERTS), assert() will either halt execution or + * just print an error message and continue. For more guidelines on error + * handling, see Documentation/contributing/coding_style.md. + */ #define ASSERT(x) { \ if (!__build_time_assert(x) && !(x)) { \ printk(BIOS_EMERG, \ -- cgit v1.2.3