blob: c80aef6dd7af91833fe6c5e99987c05c313b59dc [file] [log] [blame]
Yann Gautier4b0c72a2018-07-16 10:54:09 +02001/*
Lionel Debieve7bd96f42019-09-03 12:22:23 +02002 * Copyright (c) 2017-2019, STMicroelectronics - All Rights Reserved
Yann Gautier4b0c72a2018-07-16 10:54:09 +02003 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
Antonio Nino Diaz5eb88372018-11-08 10:20:19 +00007#ifndef BOOT_API_H
8#define BOOT_API_H
Yann Gautier4b0c72a2018-07-16 10:54:09 +02009
10#include <stdint.h>
Yann Gautier8244e1d2018-10-15 09:36:58 +020011#include <stdio.h>
Yann Gautier4b0c72a2018-07-16 10:54:09 +020012
13/*
Lionel Debieve7bd96f42019-09-03 12:22:23 +020014 * Possible value of boot context field 'auth_status'
15 */
16/* No authentication done */
17#define BOOT_API_CTX_AUTH_NO 0x0U
18/* Authentication done and failed */
19#define BOOT_API_CTX_AUTH_FAILED 0x1U
20/* Authentication done and succeeded */
21#define BOOT_API_CTX_AUTH_SUCCESS 0x2U
22
23/*
Yann Gautier4b0c72a2018-07-16 10:54:09 +020024 * Possible value of boot context field 'boot_interface_sel'
25 */
26
27/* Value of field 'boot_interface_sel' when no boot occurred */
28#define BOOT_API_CTX_BOOT_INTERFACE_SEL_NO 0x0U
29
30/* Boot occurred on SD */
31#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_SD 0x1U
32
33/* Boot occurred on EMMC */
34#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_EMMC 0x2U
35
36/**
37 * @brief Possible value of boot context field 'EmmcXferStatus'
38 */
39/*
40 * Possible value of boot context field 'emmc_xfer_status'
41 */
42#define BOOT_API_CTX_EMMC_XFER_STATUS_NOT_STARTED 0x0U
43#define BOOT_API_CTX_EMMC_XFER_STATUS_DATAEND_DETECTED 0x1U
44#define BOOT_API_CTX_EMMC_XFER_STATUS_XFER_OVERALL_TIMEOUT_DETECTED 0x2U
45#define BOOT_API_CTX_EMMC_XFER_STATUS_XFER_DATA_TIMEOUT 0x3U
46
47/*
48 * Possible value of boot context field 'emmc_error_status'
49 */
50#define BOOT_API_CTX_EMMC_ERROR_STATUS_NONE 0x0U
51#define BOOT_API_CTX_EMMC_ERROR_STATUS_CMD_TIMEOUT 0x1U
52#define BOOT_API_CTX_EMMC_ERROR_STATUS_ACK_TIMEOUT 0x2U
53#define BOOT_API_CTX_EMMC_ERROR_STATUS_DATA_CRC_FAIL 0x3U
54#define BOOT_API_CTX_EMMC_ERROR_STATUS_NOT_ENOUGH_BOOT_DATA_RX 0x4U
55#define BOOT_API_CTX_EMMC_ERROR_STATUS_HEADER_NOT_FOUND 0x5U
56#define BOOT_API_CTX_EMMC_ERROR_STATUS_HEADER_SIZE_ZERO 0x6U
57#define BOOT_API_CTX_EMMC_ERROR_STATUS_IMAGE_NOT_COMPLETE 0x7U
58
59/* Image Header related definitions */
60
61/* Definition of header version */
62#define BOOT_API_HEADER_VERSION 0x00010000U
63
64/*
65 * Magic number used to detect header in memory
66 * Its value must be 'S' 'T' 'M' 0x32, i.e 0x324D5453 as field
67 * 'bootapi_image_header_t.magic'
68 * This identifies the start of a boot image.
69 */
70#define BOOT_API_IMAGE_HEADER_MAGIC_NB 0x324D5453U
71
72/* Definitions related to Authentication used in image header structure */
73#define BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES 64
74#define BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES 64
75#define BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES 32
76
77/* Possible values of the field 'boot_api_image_header_t.ecc_algo_type' */
78#define BOOT_API_ECDSA_ALGO_TYPE_P256NIST 1
79#define BOOT_API_ECDSA_ALGO_TYPE_BRAINPOOL256 2
80
81/*
82 * Cores secure magic numbers
83 * Constant to be stored in bakcup register
84 * BOOT_API_MAGIC_NUMBER_TAMP_BCK_REG_IDX
85 */
86#define BOOT_API_A7_CORE0_MAGIC_NUMBER 0xCA7FACE0U
87#define BOOT_API_A7_CORE1_MAGIC_NUMBER 0xCA7FACE1U
88
89/*
90 * TAMP_BCK4R register index
91 * This register is used to write a Magic Number in order to restart
92 * Cortex A7 Core 1 and make it execute @ branch address from TAMP_BCK5R
93 */
94#define BOOT_API_CORE1_MAGIC_NUMBER_TAMP_BCK_REG_IDX 4U
95
96/*
97 * TAMP_BCK5R register index
98 * This register is used to contain the branch address of
99 * Cortex A7 Core 1 when restarted by a TAMP_BCK4R magic number writing
100 */
101#define BOOT_API_CORE1_BRANCH_ADDRESS_TAMP_BCK_REG_IDX 5U
102
103/*
104 * Possible value of boot context field 'hse_clock_value_in_hz'
105 */
106#define BOOT_API_CTX_HSE_CLOCK_VALUE_UNDEFINED 0U
107#define BOOT_API_CTX_HSE_CLOCK_VALUE_24_MHZ 24000000U
108#define BOOT_API_CTX_HSE_CLOCK_VALUE_25_MHZ 25000000U
109#define BOOT_API_CTX_HSE_CLOCK_VALUE_26_MHZ 26000000U
110
111/*
112 * Possible value of boot context field 'boot_partition_used_toboot'
113 */
114#define BOOT_API_CTX_BOOT_PARTITION_UNDEFINED 0U
115
116/* Used FSBL1 to boot */
117#define BOOT_API_CTX_BOOT_PARTITION_FSBL1 1U
118
119/* Used FSBL2 to boot */
120#define BOOT_API_CTX_BOOT_PARTITION_FSBL2 2U
121
122/* OTP_CFG0 */
123#define BOOT_API_OTP_MODE_WORD_NB 0
124/* Closed = OTP_CFG0[6] */
125#define BOOT_API_OTP_MODE_CLOSED_BIT_POS 6
126
Lionel Debieve978b7462019-11-18 15:52:13 +0100127#define BOOT_API_RETURN_OK 0x77U
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200128
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200129/*
130 * Boot Context related definitions
131 */
132
133/*
134 * Boot core boot configuration structure
135 * Specifies all items of the cold boot configuration
136 * Memory and peripheral part.
137 */
138typedef struct {
139 /*
140 * Boot interface used to boot : take values from defines
141 * BOOT_API_CTX_BOOT_INTERFACE_SEL_XXX above
142 */
143 uint16_t boot_interface_selected;
144 uint16_t boot_interface_instance;
145 uint32_t reserved1[13];
146 uint32_t otp_afmux_values[3];
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200147 uint32_t reserved[5];
148 uint32_t auth_status;
149
150 /*
151 * Pointers to bootROM External Secure Services
152 * - ECDSA check key
153 * - ECDSA verify signature
154 * - ECDSA verify signature and go
155 */
156 uint32_t (*bootrom_ecdsa_check_key)(uint8_t *pubkey_in,
157 uint8_t *pubkey_out);
158 uint32_t (*bootrom_ecdsa_verify_signature)(uint8_t *hash_in,
159 uint8_t *pubkey_in,
160 uint8_t *signature,
161 uint32_t ecc_algo);
162 uint32_t (*bootrom_ecdsa_verify_and_go)(uint8_t *hash_in,
163 uint8_t *pub_key_in,
164 uint8_t *signature,
165 uint32_t ecc_algo,
166 uint32_t *entry_in);
167
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200168 /*
169 * Information specific to an SD boot
170 * Updated each time an SD boot is at least attempted,
171 * even if not successful
172 * Note : This is useful to understand why an SD boot failed
173 * in particular
174 */
175 uint32_t sd_err_internal_timeout_cnt;
176 uint32_t sd_err_dcrc_fail_cnt;
177 uint32_t sd_err_dtimeout_cnt;
178 uint32_t sd_err_ctimeout_cnt;
179 uint32_t sd_err_ccrc_fail_cnt;
180 uint32_t sd_overall_retry_cnt;
181 /*
182 * Information specific to an eMMC boot
183 * Updated each time an eMMC boot is at least attempted,
184 * even if not successful
185 * Note : This is useful to understand why an eMMC boot failed
186 * in particular
187 */
188 uint32_t emmc_xfer_status;
189 uint32_t emmc_error_status;
190 uint32_t emmc_nbbytes_rxcopied_tosysram_download_area;
191 uint32_t hse_clock_value_in_hz;
192 /*
193 * Boot partition :
194 * ie FSBL partition on which the boot was successful
195 */
196 uint32_t boot_partition_used_toboot;
197
198} __packed boot_api_context_t;
199
200/*
201 * Image Header related definitions
202 */
203
204/*
205 * Structure used to define the common Header format used for FSBL, xloader,
206 * ... and in particular used by bootROM for FSBL header readout.
207 * FSBL header size is 256 Bytes = 0x100
208 */
209typedef struct {
210 /* BOOT_API_IMAGE_HEADER_MAGIC_NB */
211 uint32_t magic;
212 uint8_t image_signature[BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES];
213 /*
214 * Checksum of payload
215 * 32-bit sum all all payload bytes considered as 8 bit unigned numbers,
216 * discarding any overflow bits.
217 * Use to check UART/USB downloaded image integrity when signature
218 * is not used (i.e bit 0 : 'No_sig_check' = 1 in option flags)
219 */
220 uint32_t payload_checksum;
221 /* Image header version : should have value BOOT_API_HEADER_VERSION */
222 uint32_t header_version;
223 /* Image length in bytes */
224 uint32_t image_length;
225 /*
226 * Image Entry point address : should be in the SYSRAM area
227 * and at least within the download area range
228 */
229 uint32_t image_entry_point;
230 /* Reserved */
231 uint32_t reserved1;
232 /*
233 * Image load address : not used by bootROM but to be consistent
234 * with header format for other packages (xloader, ...)
235 */
236 uint32_t load_address;
237 /* Reserved */
238 uint32_t reserved2;
239 /* Image version to be compared by bootROM with monotonic
240 * counter value in OTP_CFG4 prior executing the downloaded image
241 */
242 uint32_t image_version;
243 /*
244 * Option flags:
245 * Bit 0 : No signature check request : 'No_sig_check'
246 * value 1 : for No signature check request
247 * value 0 : No request to bypass the signature check
248 * Note : No signature check is never allowed on a Secured chip
249 */
250 uint32_t option_flags;
251 /*
252 * Type of ECC algorithm to use :
253 * value 1 : for P-256 NIST algorithm
254 * value 2 : for Brainpool 256 algorithm
255 * See definitions 'BOOT_API_ECDSA_ALGO_TYPE_XXX' above.
256 */
257 uint32_t ecc_algo_type;
258 /*
259 * OEM ECC Public Key (aka Root pubk) provided in header on 512 bits.
260 * The SHA-256 hash of the OEM ECC pubk must match the one stored
261 * in OTP cells.
262 */
263 uint8_t ecc_pubk[BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES];
264 /* Pad up to 256 byte total size */
Yann Gautier8244e1d2018-10-15 09:36:58 +0200265 uint8_t pad[83];
266 /* Add binary type information */
267 uint8_t binary_type;
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200268} __packed boot_api_image_header_t;
269
Antonio Nino Diaz5eb88372018-11-08 10:20:19 +0000270#endif /* BOOT_API_H */