Kernel: Includes: fatal.h does not include a header file that defines z_arch_esf_t

[Thalley]

Describe the bug
fatal.h has 2 functions that use the z_arch_esf_t type:

void k_sys_fatal_error_handler(unsigned int reason, const z_arch_esf_t *esf);
void z_fatal_error(unsigned int reason, const z_arch_esf_t *esf);

but the type is not defined by any header files in the file.

The type seems to rely on the specific architecture, and have multiple different definitions:
https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/arch/arc/v2/exception.h#L23
https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/arch/arm/cortex_a_r/exception.h#L78
https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/arch/arm/cortex_m/exception.h#L122
https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/arch/posix/arch.h#L45

and several others.
Due to the different architectures, and due to the type not even being defined in similarly named files, it seems non-trivial to find the right header file to include.

The main issue about this bug is that it will cause issues with certain tools such as clangd that cannot find the right includes for static analysis.

Ideally fatal.h should include the files that it uses, and not rely on some specific header files being included before it.

To Reproduce
N/A

Expected behavior
fatal.h should include a header file that defines the types that it use.
Alternatively, fatal.h should not depend on any specific types for these functions.

Impact
Annoynace

Logs and console output
From clangd:

Unknown type name 'z_arch_esf_t'

Environment (please complete the following information):

• Commit SHA or Version used: c140053

Additional context
N/A

[andyross]

Agreed. The fatal.h APIs are very old and really not well standardized. There's a strong need for a rework and normalization. @ycsin just submitted a PR in this space (doing kconfig cleanup, not C, but both need attention) and might be interested?

[ycsin]

Sounds more like enhancements than bug - we probably just need to create something like include/zephyr/exception.h and include arch-specific exception.h based on precompiler macros from there, similar to how the zephyr/include/zephyr/arch/cpu.h is done?

#if defined(CONFIG_X86)
#include <zephyr/arch/x86/exception.h>
#elif defined(CONFIG_ARM64)
#include <zephyr/arch/arm64/exception.h>
#elif defined(CONFIG_ARM)
#include <zephyr/arch/arm/exception.h>
#elif defined(CONFIG_ARC)
#include <zephyr/arch/arc/exception.h>
#elif defined(CONFIG_NIOS2)
#include <zephyr/arch/nios2/exception.h>
#elif defined(CONFIG_RISCV)
#include <zephyr/arch/riscv/exception.h>
#elif defined(CONFIG_XTENSA)
#include <zephyr/arch/xtensa/exception.h>
#elif defined(CONFIG_MIPS)
#include <zephyr/arch/mips/exception.h>
#elif defined(CONFIG_ARCH_POSIX)
#include <zephyr/arch/posix/exception.h>
#elif defined(CONFIG_SPARC)
#include <zephyr/arch/sparc/exception.h>
#else
#error "Unknown Architecture"
#endif

[Thalley]

Sounds more like enhancements than bug - we probably just need to create something like include/zephyr/exception.h and include arch-specific exception.h based on precompiler macros from there, similar to how the zephyr/include/zephyr/arch/cpu.h is done?

Probably.
It's not completely ideal, as ideally you'd directly include the header file that defines the things you use (rather than a proxy), but may be the best option

[andyross]

Yeah, exactly. There should be a single API exposed and documented in arch_interface.h which everyone implements (whether by that particular #if chain or by putting a known header name in the arch/ tree or whatever seems like an implementation detail). Just putting the esf in there as a named struct type would be good for a start, but almost all platforms have some level of introspection support on it for stack traces, etc... and it would be nice to unify those with the same API.