From 64dc49a0fc35ff34b2d86416ee42b8dca9d5c4b5 Mon Sep 17 00:00:00 2001 From: Sean McBride Date: Sat, 18 Jul 2020 09:41:27 -0400 Subject: [PATCH] docs: Justify additional common.h file --- runtime/include/arch/common.h | 7 ++++++- runtime/include/arch/context.h | 15 ++++++++++++--- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/runtime/include/arch/common.h b/runtime/include/arch/common.h index f694647..f1a0e48 100644 --- a/runtime/include/arch/common.h +++ b/runtime/include/arch/common.h @@ -9,7 +9,12 @@ #include "software_interrupt.h" /* - * This file contains the common dependencies of the architecture-dependent code + * This file contains the common dependencies of the architecture-dependent code. + * + * While all of the content in this file could alternatively be placed in context.h + * above the conditional preprocessor includes, IDEs generally assume each file includes + * their own dependent headers directly and form a clean independent subtree that + * can be walked to resolve all symbols when the file is active */ typedef uint64_t reg_t; diff --git a/runtime/include/arch/context.h b/runtime/include/arch/context.h index 14cffac..aa90bb3 100644 --- a/runtime/include/arch/context.h +++ b/runtime/include/arch/context.h @@ -2,12 +2,21 @@ /* * This header is the single entry point into the arch_context code. - * This includes both dependent and independent code + * It includes processor independent code and conditionally includes architecture + * dependent code. */ /* - * Conditionally load architecture-dependent code - * Each of these headers include common.h + * These preprocessor conditionals load architecture-dependent code. + * + * Each of these headers include common.h, a sibling header that contains common + * structures, enums, and externs used by the processor independent code. Those + * definitions are thus transitively loaded here with the appropriate architecture + * specific code. + * + * While the code in common.h could be located in this file above the conditionals, + * structuring the code as such prevents IDEs from knowing how to resolve the + * symbols when aarch64/context.h or x86_64/context is the active file. */ #if defined(AARCH64) || defined(aarch64) #include "aarch64/context.h"