From 6a0057aa22fedf4d6d39b749923e1d6046803fd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 24 Apr 2023 10:22:47 +0100 Subject: [PATCH] docs/devel: make a statement about includes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While not explicitly disallowing header macro abuse (because that would make us hypocrites) lets at least address some things to think about. Signed-off-by: Alex Bennée Reviewed-by: Juan Quintela Message-Id: <20230424092249.58552-17-alex.bennee@linaro.org> --- docs/devel/style.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 68aa776930..5bc6f2f095 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -300,6 +300,20 @@ putting those into qemu/typedefs.h instead of including the header. Cyclic inclusion is forbidden. +Generative Includes +------------------- + +QEMU makes fairly extensive use of the macro pre-processor to +instantiate multiple similar functions. While such abuse of the macro +processor isn't discouraged it can make debugging and code navigation +harder. You should consider carefully if the same effect can be +achieved by making it easy for the compiler to constant fold or using +python scripting to generate grep friendly code. + +If you do use template header files they should be named with the +``.c.inc`` or ``.h.inc`` suffix to make it clear they are being +included for expansion. + C types =======