1 /*
2  * Copyright (c) 2019, ARM Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef ARM_TRUSTED_FIRMWARE_EXPORT_LIB_BL_AUX_PARAMS_EXP_H
8 #define ARM_TRUSTED_FIRMWARE_EXPORT_LIB_BL_AUX_PARAMS_EXP_H
9 
10 /* EXPORT HEADER -- See include/export/README for details! -- EXPORT HEADER */
11 
12 #include "../../drivers/gpio_exp.h"
13 
14 /*
15  * This API implements a lightweight parameter passing mechanism that can be
16  * used to pass SoC Firmware configuration data from BL2 to BL31 by platforms or
17  * configurations that do not want to depend on libfdt. It is structured as a
18  * singly-linked list of parameter structures that all share the same common
19  * header but may have different (and differently-sized) structure bodies after
20  * that. The header contains a type field to indicate the parameter type (which
21  * is used to infer the structure length and how to interpret its contents) and
22  * a next pointer which contains the absolute physical address of the next
23  * parameter structure. The next pointer in the last structure block is set to
24  * NULL. The picture below shows how the parameters are kept in memory.
25  *
26  * head of list  ---> +----------------+ --+
27  *                    |      type      |   |
28  *                    +----------------+   |--> struct bl_aux_param
29  *               +----|      next      |   |
30  *               |    +----------------+ --+
31  *               |    | parameter data |
32  *               |    +----------------+
33  *               |
34  *               +--> +----------------+ --+
35  *                    |      type      |   |
36  *                    +----------------+   |--> struct bl_aux_param
37  *           NULL <---|      next      |   |
38  *                    +----------------+ --+
39  *                    | parameter data |
40  *                    +----------------+
41  *
42  * Note: The SCTLR_EL3.A bit (Alignment fault check enable) is set in TF-A, so
43  * BL2 must ensure that each parameter struct starts on a 64-bit aligned address
44  * to avoid alignment faults. Parameters may be allocated in any address range
45  * accessible at the time of BL31 handoff (e.g. SRAM, DRAM, SoC-internal scratch
46  * registers, etc.), in particular address ranges that may not be mapped in
47  * BL31's page tables, so the parameter list must be parsed before the MMU is
48  * enabled and any information that is required at a later point should be
49  * deep-copied out into BL31-internal data structures.
50  */
51 
52 enum bl_aux_param_type {
53 	BL_AUX_PARAM_NONE = 0,
54 	BL_AUX_PARAM_VENDOR_SPECIFIC_FIRST = 0x1,
55 	/* 0x1 - 0x7fffffff can be used by vendor-specific handlers. */
56 	BL_AUX_PARAM_VENDOR_SPECIFIC_LAST = 0x7fffffff,
57 	BL_AUX_PARAM_GENERIC_FIRST = 0x80000001,
58 	BL_AUX_PARAM_COREBOOT_TABLE = BL_AUX_PARAM_GENERIC_FIRST,
59 	/* 0x80000001 - 0xffffffff are reserved for the generic handler. */
60 	BL_AUX_PARAM_GENERIC_LAST = 0xffffffff,
61 	/* Top 32 bits of the type field are reserved for future use. */
62 };
63 
64 /* common header for all BL aux parameters */
65 struct bl_aux_param_header {
66 	uint64_t type;
67 	uint64_t next;
68 };
69 
70 /* commonly useful parameter structures that can be shared by multiple types */
71 struct bl_aux_param_uint64 {
72 	struct bl_aux_param_header h;
73 	uint64_t value;
74 };
75 
76 struct bl_aux_gpio_info {
77 	uint8_t polarity;
78 	uint8_t direction;
79 	uint8_t pull_mode;
80 	uint8_t reserved;
81 	uint32_t index;
82 };
83 
84 struct bl_aux_param_gpio {
85 	struct bl_aux_param_header h;
86 	struct bl_aux_gpio_info gpio;
87 };
88 
89 #endif /* ARM_TRUSTED_FIRMWARE_EXPORT_LIB_BL_AUX_PARAMS_EXP_H */
90