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>

4 files changed, 32 insertions, 280 deletions

diff --git a/include/common/bl_common.h b/include/common/bl_common.h
index 457dc2a1..eb96df0b 100644
--- a/include/common/bl_common.h
+++ b/include/common/bl_common.h
@@ -11,6 +11,14 @@
 #include <common/param_header.h>
 #include <lib/utils_def.h>
 
+#ifndef __ASSEMBLY__
+#include <stddef.h>
+#include <stdint.h>
+#include <lib/cassert.h>
+#endif /* __ASSEMBLY__ */
+
+#include <export/common/bl_common_exp.h>
+
 #define UP	U(1)
 #define DOWN	U(0)
 
@@ -21,22 +29,6 @@
 #define TOP	U(0x1)
 #define BOTTOM	U(0x0)
 
-/*
- * The following are used for image state attributes.
- * Image can only be in one of the following state.
- */
-#define IMAGE_STATE_RESET		U(0)
-#define IMAGE_STATE_COPIED		U(1)
-#define IMAGE_STATE_COPYING		U(2)
-#define IMAGE_STATE_AUTHENTICATED	U(3)
-#define IMAGE_STATE_EXECUTED		U(4)
-#define IMAGE_STATE_INTERRUPTED		U(5)
-
-#define IMAGE_ATTRIB_SKIP_LOADING	U(0x02)
-#define IMAGE_ATTRIB_PLAT_SETUP		U(0x04)
-
-#define INVALID_IMAGE_ID		U(0xFFFFFFFF)
-
 /*******************************************************************************
  * Constants to indicate type of exception to the common exception handler.
  ******************************************************************************/
@@ -101,11 +93,6 @@
 
 #ifndef __ASSEMBLY__
 
-#include <stddef.h>
-#include <stdint.h>
-
-#include <lib/cassert.h>
-
 /*
  * Declarations of linker defined symbols to help determine memory layout of
  * BL images
@@ -165,66 +152,6 @@ typedef struct meminfo {
 	size_t total_size;
 } meminfo_t;
 
-/*****************************************************************************
- * Image info binary provides information from the image loader that
- * can be used by the firmware to manage available trusted RAM.
- * More advanced firmware image formats can provide additional
- * information that enables optimization or greater flexibility in the
- * common firmware code
- *****************************************************************************/
-typedef struct image_info {
-	param_header_t h;
-	uintptr_t image_base;   /* physical address of base of image */
-	uint32_t image_size;    /* bytes read from image file */
-	uint32_t image_max_size;
-} image_info_t;
-
-/*****************************************************************************
- * The image descriptor struct definition.
- *****************************************************************************/
-typedef struct image_desc {
-	/* Contains unique image id for the image. */
-	unsigned int image_id;
-	/*
-	 * This member contains Image state information.
-	 * Refer IMAGE_STATE_XXX defined above.
-	 */
-	unsigned int state;
-	uint32_t copied_size;	/* image size copied in blocks */
-	image_info_t image_info;
-	entry_point_info_t ep_info;
-} image_desc_t;
-
-/* BL image node in the BL image loading sequence */
-typedef struct bl_load_info_node {
-	unsigned int image_id;
-	image_info_t *image_info;
-	struct bl_load_info_node *next_load_info;
-} bl_load_info_node_t;
-
-/* BL image head node in the BL image loading sequence */
-typedef struct bl_load_info {
-	param_header_t h;
-	bl_load_info_node_t *head;
-} bl_load_info_t;
-
-/* BL image node in the BL image execution sequence */
-typedef struct bl_params_node {
-	unsigned int image_id;
-	image_info_t *image_info;
-	entry_point_info_t *ep_info;
-	struct bl_params_node *next_params_info;
-} bl_params_node_t;
-
-/*
- * BL image head node in the BL image execution sequence
- * It is also used to pass information to next BL image.
- */
-typedef struct bl_params {
-	param_header_t h;
-	bl_params_node_t *head;
-} bl_params_t;
-
 /*******************************************************************************
  * Function & variable prototypes
  ******************************************************************************/
diff --git a/include/common/ep_info.h b/include/common/ep_info.h
index 97df52b3..6cb903ef 100644
--- a/include/common/ep_info.h
+++ b/include/common/ep_info.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017-2018, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2017-2019, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -8,105 +8,30 @@
 #define EP_INFO_H
 
 #include <common/param_header.h>
-#include <lib/utils_def.h>
 
-#define SECURE		U(0x0)
-#define NON_SECURE	U(0x1)
+#ifndef __ASSEMBLY__
+#include <stdint.h>
+#include <lib/cassert.h>
+#endif /* __ASSEMBLY__ */
+
+#include <export/common/ep_info_exp.h>
+
+#define SECURE		EP_SECURE
+#define NON_SECURE	EP_NON_SECURE
 #define sec_state_is_valid(s) (((s) == SECURE) || ((s) == NON_SECURE))
 
-/*******************************************************************************
- * Constants that allow assembler code to access members of and the
- * 'entry_point_info' structure at their correct offsets.
- ******************************************************************************/
-#define ENTRY_POINT_INFO_PC_OFFSET	U(0x08)
-#ifdef AARCH32
-#define ENTRY_POINT_INFO_LR_SVC_OFFSET	U(0x10)
-#define ENTRY_POINT_INFO_ARGS_OFFSET	U(0x14)
-#else
-#define ENTRY_POINT_INFO_ARGS_OFFSET	U(0x18)
-#endif
+#define PARAM_EP_SECURITY_MASK	EP_SECURITY_MASK
 
-/* The following are used to set/get image attributes. */
-#define PARAM_EP_SECURITY_MASK		U(0x1)
+#define NON_EXECUTABLE	EP_NON_EXECUTABLE
+#define EXECUTABLE	EP_EXECUTABLE
 
 /* Secure or Non-secure image */
-#define GET_SECURITY_STATE(x) ((x) & PARAM_EP_SECURITY_MASK)
+#define GET_SECURITY_STATE(x) ((x) & EP_SECURITY_MASK)
 #define SET_SECURITY_STATE(x, security) \
-			((x) = ((x) & ~PARAM_EP_SECURITY_MASK) | (security))
-
-/* Endianness of the image. */
-#define EP_EE_MASK		U(0x2)
-#define EP_EE_SHIFT		U(1)
-#define EP_EE_LITTLE		U(0x0)
-#define EP_EE_BIG		U(0x2)
-#define EP_GET_EE(x)		((x) & EP_EE_MASK)
-#define EP_SET_EE(x, ee)	((x) = ((x) & ~EP_EE_MASK) | (ee))
-
-/* Enable or disable access to the secure timer from secure images. */
-#define EP_ST_MASK		U(0x4)
-#define EP_ST_DISABLE		U(0x0)
-#define EP_ST_ENABLE		U(0x4)
-#define EP_GET_ST(x)		((x) & EP_ST_MASK)
-#define EP_SET_ST(x, ee)	((x) = ((x) & ~EP_ST_MASK) | (ee))
-
-/* Determine if an image is executable or not. */
-#define EP_EXE_MASK		U(0x8)
-#define NON_EXECUTABLE		U(0x0)
-#define EXECUTABLE		U(0x8)
-#define EP_GET_EXE(x)		((x) & EP_EXE_MASK)
-#define EP_SET_EXE(x, ee)	((x) = ((x) & ~EP_EXE_MASK) | (ee))
-
-/* Flag to indicate the first image that is executed. */
-#define EP_FIRST_EXE_MASK	U(0x10)
-#define EP_FIRST_EXE		U(0x10)
-#define EP_GET_FIRST_EXE(x)	((x) & EP_FIRST_EXE_MASK)
-#define EP_SET_FIRST_EXE(x, ee)	((x) = ((x) & ~EP_FIRST_EXE_MASK) | (ee))
+			((x) = ((x) & ~EP_SECURITY_MASK) | (security))
 
 #ifndef __ASSEMBLY__
 
-#include <stdint.h>
-
-#include <lib/cassert.h>
-
-typedef struct aapcs64_params {
-	uint64_t arg0;
-	uint64_t arg1;
-	uint64_t arg2;
-	uint64_t arg3;
-	uint64_t arg4;
-	uint64_t arg5;
-	uint64_t arg6;
-	uint64_t arg7;
-} aapcs64_params_t;
-
-typedef struct aapcs32_params {
-	uint32_t arg0;
-	uint32_t arg1;
-	uint32_t arg2;
-	uint32_t arg3;
-} aapcs32_params_t;
-
-/*****************************************************************************
- * This structure represents the superset of information needed while
- * switching exception levels. The only two mechanisms to do so are
- * ERET & SMC. Security state is indicated using bit zero of header
- * attribute
- * NOTE: BL1 expects entrypoint followed by spsr at an offset from the start
- * of this structure defined by the macro `ENTRY_POINT_INFO_PC_OFFSET` while
- * processing SMC to jump to BL31.
- *****************************************************************************/
-typedef struct entry_point_info {
-	param_header_t h;
-	uintptr_t pc;
-	uint32_t spsr;
-#ifdef AARCH32
-	uintptr_t lr_svc;
-	aapcs32_params_t args;
-#else
-	aapcs64_params_t args;
-#endif
-} entry_point_info_t;
-
 /*
  * Compile time assertions related to the 'entry_point_info' structure to
  * ensure that the assembler and the compiler view of the offsets of
diff --git a/include/common/param_header.h b/include/common/param_header.h
index 0c1503f1..b8852869 100644
--- a/include/common/param_header.h
+++ b/include/common/param_header.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017-2018, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2017-2019, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -9,20 +9,14 @@
 
 #include <stdbool.h>
 
-#include <lib/utils_def.h>
+#ifndef __ASSEMBLY__
+#include <stdint.h>
+#endif /*__ASSEMBLY__*/
 
-/* Param header types */
-#define PARAM_EP			U(0x01)
-#define PARAM_IMAGE_BINARY		U(0x02)
-#define PARAM_BL31			U(0x03)
-#define PARAM_BL_LOAD_INFO		U(0x04)
-#define PARAM_BL_PARAMS			U(0x05)
-#define PARAM_PSCI_LIB_ARGS		U(0x06)
-#define PARAM_SP_IMAGE_BOOT_INFO	U(0x07)
+#include <export/common/param_header_exp.h>
 
-/* Param header version */
-#define VERSION_1	U(0x01)
-#define VERSION_2	U(0x02)
+#define VERSION_1	PARAM_VERSION_1
+#define VERSION_2	PARAM_VERSION_2
 
 #define SET_PARAM_HEAD(_p, _type, _ver, _attr) do { \
 	(_p)->h.type = (uint8_t)(_type); \
@@ -38,21 +32,4 @@
 	._p.h.size = (uint16_t)sizeof(_p_type), \
 	._p.h.attr = (uint32_t)(_attr)
 
-#ifndef __ASSEMBLY__
-
-#include <stdint.h>
-
-/***************************************************************************
- * This structure provides version information and the size of the
- * structure, attributes for the structure it represents
- ***************************************************************************/
-typedef struct param_header {
-	uint8_t type;		/* type of the structure */
-	uint8_t version;    /* version of this structure */
-	uint16_t size;      /* size of this structure in bytes */
-	uint32_t attr;      /* attributes: unused bits SBZ */
-} param_header_t;
-
-#endif /*__ASSEMBLY__*/
-
 #endif /* PARAM_HEADER_H */
diff --git a/include/common/tbbr/tbbr_img_def.h b/include/common/tbbr/tbbr_img_def.h
index 672886de..1701995a 100644
--- a/include/common/tbbr/tbbr_img_def.h
+++ b/include/common/tbbr/tbbr_img_def.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015-2018, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2015-2019, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -7,83 +7,6 @@
 #ifndef TBBR_IMG_DEF_H
 #define TBBR_IMG_DEF_H
 
-#include <lib/utils_def.h>
-
-/* Firmware Image Package */
-#define FIP_IMAGE_ID			U(0)
-
-/* Trusted Boot Firmware BL2 */
-#define BL2_IMAGE_ID			U(1)
-
-/* SCP Firmware SCP_BL2 */
-#define SCP_BL2_IMAGE_ID		U(2)
-
-/* EL3 Runtime Firmware BL31 */
-#define BL31_IMAGE_ID			U(3)
-
-/* Secure Payload BL32 (Trusted OS) */
-#define BL32_IMAGE_ID			U(4)
-
-/* Non-Trusted Firmware BL33 */
-#define BL33_IMAGE_ID			U(5)
-
-/* Certificates */
-#define TRUSTED_BOOT_FW_CERT_ID		U(6)
-#define TRUSTED_KEY_CERT_ID		U(7)
-
-#define SCP_FW_KEY_CERT_ID		U(8)
-#define SOC_FW_KEY_CERT_ID		U(9)
-#define TRUSTED_OS_FW_KEY_CERT_ID	U(10)
-#define NON_TRUSTED_FW_KEY_CERT_ID	U(11)
-
-#define SCP_FW_CONTENT_CERT_ID		U(12)
-#define SOC_FW_CONTENT_CERT_ID		U(13)
-#define TRUSTED_OS_FW_CONTENT_CERT_ID	U(14)
-#define NON_TRUSTED_FW_CONTENT_CERT_ID	U(15)
-
-/* Non-Trusted ROM Firmware NS_BL1U */
-#define NS_BL1U_IMAGE_ID		U(16)
-
-/* Trusted FWU Certificate */
-#define FWU_CERT_ID			U(17)
-
-/* Trusted FWU SCP Firmware SCP_BL2U */
-#define SCP_BL2U_IMAGE_ID		U(18)
-
-/* Trusted FWU Boot Firmware BL2U */
-#define BL2U_IMAGE_ID			U(19)
-
-/* Non-Trusted FWU Firmware NS_BL2U */
-#define NS_BL2U_IMAGE_ID		U(20)
-
-/* Secure Payload BL32_EXTRA1 (Trusted OS Extra1) */
-#define BL32_EXTRA1_IMAGE_ID		U(21)
-
-/* Secure Payload BL32_EXTRA2 (Trusted OS Extra2) */
-#define BL32_EXTRA2_IMAGE_ID		U(22)
-
-/* HW_CONFIG (e.g. Kernel DT) */
-#define HW_CONFIG_ID			U(23)
-
-/* TB_FW_CONFIG */
-#define TB_FW_CONFIG_ID			U(24)
-
-/* SOC_FW_CONFIG */
-#define SOC_FW_CONFIG_ID		U(25)
-
-/* TOS_FW_CONFIG */
-#define TOS_FW_CONFIG_ID		U(26)
-
-/* NT_FW_CONFIG */
-#define NT_FW_CONFIG_ID			U(27)
-
-/* GPT Partition */
-#define GPT_IMAGE_ID			U(28)
-
-/* Binary with STM32 header */
-#define STM32_IMAGE_ID			U(29)
-
-/* Define size of the array */
-#define MAX_NUMBER_IDS			U(30)
+#include <export/common/tbbr/tbbr_img_def_exp.h>
 
 #endif /* TBBR_IMG_DEF_H */