From 5784ab34d4ea89bb086af11125caec4af0cf1cd8 Mon Sep 17 00:00:00 2001 From: Julius Werner Date: Fri, 15 Apr 2022 14:26:33 -0700 Subject: [PATCH] docs/coding_style: Clarify use of GCC extensions This patch adds a section to the coding style that explicitly clarifies the use of GCC extensions in coreboot (which has been long-standing practice anyway), and expressly allows their use. See the mailing list discussion for more details: https://mail.coreboot.org/hyperkitty/list/coreboot@coreboot.org/thread/3C2QWAZ5RJ6ME5KXMEOGB5GW62UTXCLS/ Signed-off-by: Julius Werner Change-Id: I0d0eb90d6729fefeb131cdd573ad51f1884afe11 Reviewed-on: https://review.coreboot.org/c/coreboot/+/63660 Tested-by: build bot (Jenkins) Reviewed-by: Krystian Hebel Reviewed-by: Yu-Ping Wu Reviewed-by: Arthur Heymans Reviewed-by: David Hendricks --- Documentation/contributing/coding_style.md | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/Documentation/contributing/coding_style.md b/Documentation/contributing/coding_style.md index 656454545d..3314030df0 100644 --- a/Documentation/contributing/coding_style.md +++ b/Documentation/contributing/coding_style.md @@ -960,6 +960,41 @@ asm ("magic %reg1, #42nt" : /* outputs */ : /* inputs */ : /* clobbers */); ``` +GCC extensions +-------------- + +GCC is the only officially-supported compiler for coreboot, and a +variety of its C language extensions are heavily used throughout the +code base. There have been occasional attempts to add clang as a second +compiler option, which is generally compatible to the same language +extensions that have been long-established by GCC. + +Some GCC extensions (e.g. inline assembly) are basically required for +proper firmware development. Others enable more safe or flexible +coding patterns than can be expressed with standard C (e.g. statement +expressions and `typeof()` to avoid double evaluation in macros like +`MAX()`). Yet others just add some simple convenience and reduce +boilerplate (e.g. `void *` arithmetic). + +Since some GCC extensions are necessary either way, there is no gain +from avoiding other GCC extensions elsewhere. The use of all official +GCC extensions is expressly allowed within coreboot. In cases where an +extension can be replaced by a 100% equivalent C standard feature with +no extra boilerplate or loss of readability, the C standard feature +should be preferred (this usually only happens when GCC retains an +older pre-standardization extension for backwards compatibility, e.g. +the old pre-C99 syntax for designated initializers). But if there is +any advantage offered by the GCC extension (e.g. using GCC zero-length +arrays instead of C99 variable-length arrays because they don't inhibit +`sizeof()`), there is no reason to deprive ourselves of that, and "this +is not C standard compliant" should not be a reason to argue against +its use in reviews. + +This rule only applies to explicit GCC extensions listed in the +"Extensions to the C Language Family" section of the GCC manual. Code +should never rely on incidental GCC translation behavior that is not +explicitly documented as a feature and could change at any moment. + References ----------