arm-trusted-firmware

History

Julius Werner 57bf605772 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>		2019-07-23 20:25:34 -07:00
..
common	Factor out cross-BL API into export headers suitable for 3rd party code	2019-07-23 20:25:34 -07:00
drivers	Factor out cross-BL API into export headers suitable for 3rd party code	2019-07-23 20:25:34 -07:00
lib	Factor out cross-BL API into export headers suitable for 3rd party code	2019-07-23 20:25:34 -07:00
plat/rockchip/common	Factor out cross-BL API into export headers suitable for 3rd party code	2019-07-23 20:25:34 -07:00
README	Factor out cross-BL API into export headers suitable for 3rd party code	2019-07-23 20:25:34 -07:00

README

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.)