blob: 1054609a1e8c915e24951106f459196afd21d56f [file] [log] [blame]
Yann Gautier4b0c72a2018-07-16 10:54:09 +02001/*
Lionel Debieve1e072262020-04-08 12:08:55 +02002 * Copyright (c) 2017-2022, 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 */
Lionel Debieve1e072262020-04-08 12:08:55 +020016#if STM32MP13
17 /* No authentication done */
18#define BOOT_API_CTX_AUTH_NO 0x7CFDD351U
19 /* Authentication done and failed */
20#define BOOT_API_CTX_AUTH_FAILED 0x51330884U
21 /* Authentication done and success */
22#define BOOT_API_CTX_AUTH_SUCCESS 0x67E8CAE1U
23#endif
24#if STM32MP15
Lionel Debieve7bd96f42019-09-03 12:22:23 +020025/* No authentication done */
26#define BOOT_API_CTX_AUTH_NO 0x0U
27/* Authentication done and failed */
28#define BOOT_API_CTX_AUTH_FAILED 0x1U
29/* Authentication done and succeeded */
30#define BOOT_API_CTX_AUTH_SUCCESS 0x2U
Lionel Debieve1e072262020-04-08 12:08:55 +020031#endif
Lionel Debieve7bd96f42019-09-03 12:22:23 +020032
33/*
Yann Gautier4b0c72a2018-07-16 10:54:09 +020034 * Possible value of boot context field 'boot_interface_sel'
35 */
36
37/* Value of field 'boot_interface_sel' when no boot occurred */
38#define BOOT_API_CTX_BOOT_INTERFACE_SEL_NO 0x0U
39
40/* Boot occurred on SD */
41#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_SD 0x1U
42
43/* Boot occurred on EMMC */
44#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_EMMC 0x2U
45
Lionel Debieve402a46b2019-11-04 12:28:15 +010046/* Boot occurred on FMC */
47#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NAND_FMC 0x3U
48
Lionel Debievecb0dbc42019-09-25 09:11:31 +020049/* Boot occurred on QSPI NOR */
50#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NOR_QSPI 0x4U
51
Patrick Delaunaye50571b2021-10-28 13:48:52 +020052/* Boot occurred on UART */
53#define BOOT_API_CTX_BOOT_INTERFACE_SEL_SERIAL_UART 0x5U
54
Patrick Delaunay9c5ee782021-07-06 14:07:56 +020055/* Boot occurred on USB */
56#define BOOT_API_CTX_BOOT_INTERFACE_SEL_SERIAL_USB 0x6U
57
Lionel Debieve186b0462019-09-24 18:30:12 +020058/* Boot occurred on QSPI NAND */
59#define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NAND_QSPI 0x7U
60
Yann Gautier4b0c72a2018-07-16 10:54:09 +020061/**
62 * @brief Possible value of boot context field 'EmmcXferStatus'
63 */
64/*
65 * Possible value of boot context field 'emmc_xfer_status'
66 */
67#define BOOT_API_CTX_EMMC_XFER_STATUS_NOT_STARTED 0x0U
68#define BOOT_API_CTX_EMMC_XFER_STATUS_DATAEND_DETECTED 0x1U
69#define BOOT_API_CTX_EMMC_XFER_STATUS_XFER_OVERALL_TIMEOUT_DETECTED 0x2U
70#define BOOT_API_CTX_EMMC_XFER_STATUS_XFER_DATA_TIMEOUT 0x3U
71
72/*
73 * Possible value of boot context field 'emmc_error_status'
74 */
75#define BOOT_API_CTX_EMMC_ERROR_STATUS_NONE 0x0U
76#define BOOT_API_CTX_EMMC_ERROR_STATUS_CMD_TIMEOUT 0x1U
77#define BOOT_API_CTX_EMMC_ERROR_STATUS_ACK_TIMEOUT 0x2U
78#define BOOT_API_CTX_EMMC_ERROR_STATUS_DATA_CRC_FAIL 0x3U
79#define BOOT_API_CTX_EMMC_ERROR_STATUS_NOT_ENOUGH_BOOT_DATA_RX 0x4U
80#define BOOT_API_CTX_EMMC_ERROR_STATUS_HEADER_NOT_FOUND 0x5U
81#define BOOT_API_CTX_EMMC_ERROR_STATUS_HEADER_SIZE_ZERO 0x6U
82#define BOOT_API_CTX_EMMC_ERROR_STATUS_IMAGE_NOT_COMPLETE 0x7U
Lionel Debieve1e072262020-04-08 12:08:55 +020083#define BOOT_API_CTX_EMMC_ERROR_STATUS_ACK_ERROR 0x8U
Yann Gautier4b0c72a2018-07-16 10:54:09 +020084
85/* Image Header related definitions */
86
87/* Definition of header version */
Lionel Debieve1e072262020-04-08 12:08:55 +020088#if STM32MP13
89#define BOOT_API_HEADER_VERSION 0x00020000U
90#endif
91#if STM32MP15
Yann Gautier4b0c72a2018-07-16 10:54:09 +020092#define BOOT_API_HEADER_VERSION 0x00010000U
Lionel Debieve1e072262020-04-08 12:08:55 +020093#endif
Yann Gautier4b0c72a2018-07-16 10:54:09 +020094
95/*
96 * Magic number used to detect header in memory
97 * Its value must be 'S' 'T' 'M' 0x32, i.e 0x324D5453 as field
98 * 'bootapi_image_header_t.magic'
99 * This identifies the start of a boot image.
100 */
101#define BOOT_API_IMAGE_HEADER_MAGIC_NB 0x324D5453U
102
103/* Definitions related to Authentication used in image header structure */
104#define BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES 64
105#define BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES 64
106#define BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES 32
107
108/* Possible values of the field 'boot_api_image_header_t.ecc_algo_type' */
109#define BOOT_API_ECDSA_ALGO_TYPE_P256NIST 1
110#define BOOT_API_ECDSA_ALGO_TYPE_BRAINPOOL256 2
111
112/*
Lionel Debieve1e072262020-04-08 12:08:55 +0200113 * Extension headers related definitions
114 */
115/* 'bootapi_image_header_t.extension_flag' used for authentication feature */
116#define BOOT_API_AUTHENTICATION_EXTENSION_BIT BIT(0)
117/* 'bootapi_image_header_t.extension_flag' used for FSBL decryption feature */
118#define BOOT_API_FSBL_DECRYPTION_EXTENSION_BIT BIT(1)
119/* 'bootapi_image_header_t.extension_flag' used for padding header feature */
120#define BOOT_API_PADDING_EXTENSION_BIT BIT(31)
121/*
122 * mask of bits of field 'bootapi_image_header_t.extension_flag'
123 * used for extension headers
124 */
125#define BOOT_API_ALL_EXTENSIONS_MASK \
126 (BOOT_API_AUTHENTICATION_EXTENSION_BIT | \
127 BOOT_API_FSBL_DECRYPTION_EXTENSION_BIT | \
128 BOOT_API_PADDING_EXTENSION_BIT)
129/*
130 * Magic number of FSBL decryption extension header
131 * The value shall gives the four bytes 'S','T',0x00,0x01 in memory
132 */
133#define BOOT_API_FSBL_DECRYPTION_HEADER_MAGIC_NB 0x01005453U
134
135/*
136 * Magic number of PKH revocation extension header
137 * The value shall gives the four bytes 'S','T',0x00,0x02 in memory
138 */
139#define BOOT_API_AUTHENTICATION_HEADER_MAGIC_NB 0x02005453U
140
141/* Max number of ECDSA public key hash in table */
142#define BOOT_API_AUTHENTICATION_NB_PKH_MAX 8U
143
144/* ECDSA public key hash table size in bytes */
145#define BOOT_API_AUTHENTICATION_TABLE_SIZE_BYTES \
146 (BOOT_API_AUTHENTICATION_NB_PKH_MAX * \
147 BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES)
148
149/*
150 * Magic number of padding extension header
151 * The value shall gives the four bytes 'S','T',0xFF,0xFF in memory
152 */
153#define BOOT_API_PADDING_HEADER_MAGIC_NB 0xFFFF5453U
154
155/*
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200156 * Cores secure magic numbers
157 * Constant to be stored in bakcup register
158 * BOOT_API_MAGIC_NUMBER_TAMP_BCK_REG_IDX
159 */
160#define BOOT_API_A7_CORE0_MAGIC_NUMBER 0xCA7FACE0U
161#define BOOT_API_A7_CORE1_MAGIC_NUMBER 0xCA7FACE1U
162
163/*
164 * TAMP_BCK4R register index
165 * This register is used to write a Magic Number in order to restart
166 * Cortex A7 Core 1 and make it execute @ branch address from TAMP_BCK5R
167 */
168#define BOOT_API_CORE1_MAGIC_NUMBER_TAMP_BCK_REG_IDX 4U
169
170/*
171 * TAMP_BCK5R register index
172 * This register is used to contain the branch address of
173 * Cortex A7 Core 1 when restarted by a TAMP_BCK4R magic number writing
174 */
175#define BOOT_API_CORE1_BRANCH_ADDRESS_TAMP_BCK_REG_IDX 5U
176
177/*
178 * Possible value of boot context field 'hse_clock_value_in_hz'
179 */
180#define BOOT_API_CTX_HSE_CLOCK_VALUE_UNDEFINED 0U
181#define BOOT_API_CTX_HSE_CLOCK_VALUE_24_MHZ 24000000U
182#define BOOT_API_CTX_HSE_CLOCK_VALUE_25_MHZ 25000000U
183#define BOOT_API_CTX_HSE_CLOCK_VALUE_26_MHZ 26000000U
184
185/*
186 * Possible value of boot context field 'boot_partition_used_toboot'
187 */
188#define BOOT_API_CTX_BOOT_PARTITION_UNDEFINED 0U
189
190/* Used FSBL1 to boot */
191#define BOOT_API_CTX_BOOT_PARTITION_FSBL1 1U
192
193/* Used FSBL2 to boot */
194#define BOOT_API_CTX_BOOT_PARTITION_FSBL2 2U
195
196/* OTP_CFG0 */
197#define BOOT_API_OTP_MODE_WORD_NB 0
198/* Closed = OTP_CFG0[6] */
199#define BOOT_API_OTP_MODE_CLOSED_BIT_POS 6
200
Lionel Debieve978b7462019-11-18 15:52:13 +0100201#define BOOT_API_RETURN_OK 0x77U
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200202
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200203/*
204 * Boot Context related definitions
205 */
206
207/*
208 * Boot core boot configuration structure
209 * Specifies all items of the cold boot configuration
210 * Memory and peripheral part.
211 */
212typedef struct {
213 /*
214 * Boot interface used to boot : take values from defines
215 * BOOT_API_CTX_BOOT_INTERFACE_SEL_XXX above
216 */
217 uint16_t boot_interface_selected;
218 uint16_t boot_interface_instance;
Lionel Debieve1e072262020-04-08 12:08:55 +0200219#if STM32MP13
220 uint32_t reserved1[12];
221#endif
222#if STM32MP15
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200223 uint32_t reserved1[13];
Lionel Debieve1e072262020-04-08 12:08:55 +0200224#endif
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200225 uint32_t otp_afmux_values[3];
Lionel Debieve1e072262020-04-08 12:08:55 +0200226 uint32_t reserved[3];
227#if STM32MP15
228 uint32_t reserved2[2];
229#endif
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200230 uint32_t auth_status;
231
Lionel Debieve1e072262020-04-08 12:08:55 +0200232#if STM32MP15
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200233 /*
234 * Pointers to bootROM External Secure Services
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200235 * - ECDSA verify signature
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200236 */
Lionel Debieve0ae71af2022-10-05 16:29:38 +0200237 uint32_t reserved3;
Lionel Debieve7bd96f42019-09-03 12:22:23 +0200238 uint32_t (*bootrom_ecdsa_verify_signature)(uint8_t *hash_in,
239 uint8_t *pubkey_in,
240 uint8_t *signature,
241 uint32_t ecc_algo);
Lionel Debieve0ae71af2022-10-05 16:29:38 +0200242 uint32_t reserved4;
Lionel Debieve1e072262020-04-08 12:08:55 +0200243#endif
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200244 /*
245 * Information specific to an SD boot
246 * Updated each time an SD boot is at least attempted,
247 * even if not successful
248 * Note : This is useful to understand why an SD boot failed
249 * in particular
250 */
251 uint32_t sd_err_internal_timeout_cnt;
252 uint32_t sd_err_dcrc_fail_cnt;
253 uint32_t sd_err_dtimeout_cnt;
254 uint32_t sd_err_ctimeout_cnt;
255 uint32_t sd_err_ccrc_fail_cnt;
256 uint32_t sd_overall_retry_cnt;
257 /*
258 * Information specific to an eMMC boot
259 * Updated each time an eMMC boot is at least attempted,
260 * even if not successful
261 * Note : This is useful to understand why an eMMC boot failed
262 * in particular
263 */
264 uint32_t emmc_xfer_status;
265 uint32_t emmc_error_status;
266 uint32_t emmc_nbbytes_rxcopied_tosysram_download_area;
267 uint32_t hse_clock_value_in_hz;
268 /*
269 * Boot partition :
270 * ie FSBL partition on which the boot was successful
271 */
272 uint32_t boot_partition_used_toboot;
273
274} __packed boot_api_context_t;
275
276/*
277 * Image Header related definitions
278 */
279
280/*
281 * Structure used to define the common Header format used for FSBL, xloader,
282 * ... and in particular used by bootROM for FSBL header readout.
283 * FSBL header size is 256 Bytes = 0x100
284 */
285typedef struct {
286 /* BOOT_API_IMAGE_HEADER_MAGIC_NB */
287 uint32_t magic;
288 uint8_t image_signature[BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES];
289 /*
290 * Checksum of payload
Lionel Debieve1e072262020-04-08 12:08:55 +0200291 * 32-bit sum all payload bytes considered as 8 bit unsigned
292 * numbers, discarding any overflow bits.
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200293 * Use to check UART/USB downloaded image integrity when signature
Lionel Debieve1e072262020-04-08 12:08:55 +0200294 * is not used
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200295 */
296 uint32_t payload_checksum;
297 /* Image header version : should have value BOOT_API_HEADER_VERSION */
298 uint32_t header_version;
299 /* Image length in bytes */
300 uint32_t image_length;
301 /*
302 * Image Entry point address : should be in the SYSRAM area
303 * and at least within the download area range
304 */
305 uint32_t image_entry_point;
306 /* Reserved */
307 uint32_t reserved1;
308 /*
309 * Image load address : not used by bootROM but to be consistent
310 * with header format for other packages (xloader, ...)
311 */
312 uint32_t load_address;
313 /* Reserved */
314 uint32_t reserved2;
315 /* Image version to be compared by bootROM with monotonic
316 * counter value in OTP_CFG4 prior executing the downloaded image
317 */
318 uint32_t image_version;
Lionel Debieve1e072262020-04-08 12:08:55 +0200319
320#if STM32MP13
321 /*
322 * Extension flags :
323 *
324 * Bit 0 : Authentication extension header
325 * value 0 : No signature check request
326 * Bit 1 : Encryption extension header
327 * Bit 2 : Padding extension header
328 */
329 uint32_t extension_flags;
330 /* Length in bytes of all extension headers */
331 uint32_t extension_headers_length;
332 /* Add binary type information */
333 uint32_t binary_type;
334 /* Pad up to 128 byte total size */
335 uint8_t pad[16];
Lionel Debieve7c700882022-10-05 16:31:28 +0200336 /* Followed by extension header */
337 uint8_t ext_header[];
Lionel Debieve1e072262020-04-08 12:08:55 +0200338#endif
339#if STM32MP15
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200340 /*
341 * Option flags:
342 * Bit 0 : No signature check request : 'No_sig_check'
343 * value 1 : for No signature check request
344 * value 0 : No request to bypass the signature check
345 * Note : No signature check is never allowed on a Secured chip
346 */
347 uint32_t option_flags;
348 /*
349 * Type of ECC algorithm to use :
350 * value 1 : for P-256 NIST algorithm
351 * value 2 : for Brainpool 256 algorithm
352 * See definitions 'BOOT_API_ECDSA_ALGO_TYPE_XXX' above.
353 */
354 uint32_t ecc_algo_type;
355 /*
356 * OEM ECC Public Key (aka Root pubk) provided in header on 512 bits.
357 * The SHA-256 hash of the OEM ECC pubk must match the one stored
358 * in OTP cells.
359 */
360 uint8_t ecc_pubk[BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES];
361 /* Pad up to 256 byte total size */
Yann Gautier8244e1d2018-10-15 09:36:58 +0200362 uint8_t pad[83];
363 /* Add binary type information */
364 uint8_t binary_type;
Lionel Debieve1e072262020-04-08 12:08:55 +0200365#endif
Yann Gautier4b0c72a2018-07-16 10:54:09 +0200366} __packed boot_api_image_header_t;
367
Lionel Debieve7c700882022-10-05 16:31:28 +0200368typedef uint8_t boot_api_sha256_t[BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES];
369
370typedef struct {
371 /* Extension header type:
372 * BOOT_API_FSBL_DECRYPTION_HEADER_MAGIC_NB or
373 * BOOT_API_AUTHENTICATION_HEADER_MAGIC_NB
374 * BOOT_API_PADDING_HEADER_MAGIC_NB
375 */
376 uint32_t type;
377 /* Extension header len in byte */
378 uint32_t len;
379 /* parameters of this extension */
380 uint8_t params[];
381} __packed boot_extension_header_t;
382
383typedef struct {
384 /* Idx of ECDSA public key to be used in table */
385 uint32_t pk_idx;
386 /* Number of ECDSA public key in table */
387 uint32_t nb_pk;
388 /*
389 * Type of ECC algorithm to use :
390 * value 1 : for P-256 NIST algorithm
391 * value 2 : for Brainpool 256 algorithm
392 * See definitions 'BOOT_API_ECDSA_ALGO_TYPE_XXX' above.
393 */
394 uint32_t ecc_algo_type;
395 /* ECDSA public key to be used to check signature. */
396 uint8_t ecc_pubk[BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES];
397 /* table of Hash of Algo+ECDSA public key */
398 boot_api_sha256_t pk_hashes[];
399} __packed boot_ext_header_params_authentication_t;
400
401typedef struct {
402 /* Size of encryption key (128 or 256) */
403 uint32_t key_size;
404 uint32_t derivation_cont;
405 /* 128 msb bits of plain payload SHA256 */
406 uint32_t hash[4];
407} __packed boot_ext_header_params_encrypted_fsbl_t;
408
Antonio Nino Diaz5eb88372018-11-08 10:20:19 +0000409#endif /* BOOT_API_H */