Factor out cross-BL API into export headers suitable for 3rd party code
This patch adds a new include/export/ directory meant for inclusion in
third-party code. This is useful for cases where third-party code needs
to interact with TF-A interfaces and data structures (such as a custom
BL2-implementation like coreboot handing off to BL31). Directly
including headers from the TF-A repository avoids having to duplicate
all these definitions (and risk them going stale), but with the current
header structure this is not possible because handoff API definitions
are too deeply intertwined with other TF code/headers and chain-include
other headers that will not be available in the other environment.
The new approach aims to solve this by separating only the parts that
are really needed into these special headers that are self-contained and
will not chain-include other (non-export) headers. TF-A code should
never include them directly but should instead always include the
respective wrapper header, which will include the required prerequisites
(like <stdint.h>) before including the export header. Third-party code
can include the export headers via its own wrappers that make sure the
necessary definitions are available in whatever way that environment can
provide them.
Change-Id: Ifd769320ba51371439a8e5dd5b79c2516c3b43ab
Signed-off-by: Julius Werner <jwerner@chromium.org>
diff --git a/include/export/README b/include/export/README
new file mode 100644
index 0000000..2de8d6b
--- /dev/null
+++ b/include/export/README
@@ -0,0 +1,33 @@
+All headers under include/export/ are export headers that are intended for
+inclusion in third-party code which needs to interact with TF-A data structures
+or interfaces. They must follow these special rules:
+
+- Header guards should start with ARM_TRUSTED_FIRMWARE_ to reduce clash risk.
+
+- All definitions should be sufficiently namespaced (e.g. with BL_ or TF_) to
+ make name clashes with third-party code unlikely.
+
+- They must not #include any headers except other export headers, and those
+ includes must use relative paths with "../double_quotes.h" notation.
+
+- They must not rely on any type definitions other that <stdint.h> types defined
+ in the ISO C standard (i.e. uint64_t is fine, but not u_register_t). They
+ should still not #include <stdint.h>. Instead, wrapper headers including
+ export headers need to ensure that they #include <stdint.h> earlier in their
+ include order.
+
+- They must not rely on any macro definitions other than those which are
+ pre-defined by all common compilers (e.g. __ASSEMBLER__ or __aarch64__).
+
+- They must only contain macro, type and structure definitions, no prototypes.
+
+- They should avoid using integer types with architecture-dependent widths
+ (e.g. long, uintptr_t, pointer types) where possible. (Some existing export
+ headers are violating this for now.)
+
+- Their names should always end in "_exp.h".
+
+- Normal TF-A code should never include export headers directly. Instead, it
+ should include a wrapper header that ensures the export header is included in
+ the right manner. (The wrapper header for include/export/x/y/z_exp.h should
+ normally be placed at include/x/y/z.h.)