| Julius Werner | 2a231e3 | 2019-05-28 21:03:58 -0700 | [diff] [blame] | 1 | All headers under include/export/ are export headers that are intended for |
| 2 | inclusion in third-party code which needs to interact with TF-A data structures |
| 3 | or interfaces. They must follow these special rules: |
| 4 | |
| 5 | - Header guards should start with ARM_TRUSTED_FIRMWARE_ to reduce clash risk. |
| 6 | |
| 7 | - All definitions should be sufficiently namespaced (e.g. with BL_ or TF_) to |
| 8 | make name clashes with third-party code unlikely. |
| 9 | |
| 10 | - They must not #include any headers except other export headers, and those |
| 11 | includes must use relative paths with "../double_quotes.h" notation. |
| 12 | |
| 13 | - They must not rely on any type definitions other that <stdint.h> types defined |
| 14 | in the ISO C standard (i.e. uint64_t is fine, but not u_register_t). They |
| 15 | should still not #include <stdint.h>. Instead, wrapper headers including |
| 16 | export headers need to ensure that they #include <stdint.h> earlier in their |
| 17 | include order. |
| 18 | |
| 19 | - They must not rely on any macro definitions other than those which are |
| 20 | pre-defined by all common compilers (e.g. __ASSEMBLER__ or __aarch64__). |
| 21 | |
| 22 | - They must only contain macro, type and structure definitions, no prototypes. |
| 23 | |
| 24 | - They should avoid using integer types with architecture-dependent widths |
| 25 | (e.g. long, uintptr_t, pointer types) where possible. (Some existing export |
| 26 | headers are violating this for now.) |
| 27 | |
| 28 | - Their names should always end in "_exp.h". |
| 29 | |
| 30 | - Normal TF-A code should never include export headers directly. Instead, it |
| 31 | should include a wrapper header that ensures the export header is included in |
| 32 | the right manner. (The wrapper header for include/export/x/y/z_exp.h should |
| 33 | normally be placed at include/x/y/z.h.) |