1 /* 2 * Copyright (c) 2023-2026, STMicroelectronics - All Rights Reserved 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef BOOT_API_H 8 #define BOOT_API_H 9 10 #include <stdint.h> 11 #include <stdio.h> 12 13 /* 14 * Exported constants 15 */ 16 17 /* 18 * Boot Context related definitions 19 */ 20 21 /* 22 * Possible value of boot context field 'auth_status' 23 */ 24 /* No authentication done */ 25 #define BOOT_API_CTX_AUTH_NO 0x0U 26 /* Authentication done and failed */ 27 #define BOOT_API_CTX_AUTH_FAILED 0x1U 28 /* Authentication done and succeeded */ 29 #define BOOT_API_CTX_AUTH_SUCCESS 0x2U 30 31 /* 32 * Possible value of boot context field 'boot_interface_sel' 33 */ 34 35 /* Value of field 'boot_interface_sel' when no boot occurred */ 36 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_NO 0x0U 37 38 /* Boot occurred on SD */ 39 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_SD 0x1U 40 41 /* Boot occurred on EMMC */ 42 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_EMMC 0x2U 43 44 /* Boot occurred on FMC */ 45 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NAND_FMC 0x3U 46 47 /* Boot occurred on OSPI NOR */ 48 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NOR_SPI 0x4U 49 50 /* Boot occurred on UART */ 51 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_SERIAL_UART 0x5U 52 53 /* Boot occurred on USB */ 54 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_SERIAL_USB 0x6U 55 56 /* Boot occurred on OSPI NAND */ 57 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NAND_SPI 0x7U 58 59 /* Boot occurred on HyperFlash QSPI */ 60 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_HYPERFLASH_OSPI 0x8U 61 62 /* 63 * Possible value of boot context field 'emmc_xfer_status' 64 */ 65 #define BOOT_API_CTX_EMMC_XFER_STATUS_NOT_STARTED 0x0U 66 #define BOOT_API_CTX_EMMC_XFER_STATUS_DATAEND_DETECTED 0x1U 67 #define BOOT_API_CTX_EMMC_XFER_STATUS_XFER_DATA_TIMEOUT 0x2U 68 69 /* 70 * Possible value of boot context field 'emmc_error_status' 71 */ 72 #define BOOT_API_CTX_EMMC_ERROR_STATUS_NONE 0x0U 73 #define BOOT_API_CTX_EMMC_ERROR_STATUS_CMD_TIMEOUT 0x1U 74 #define BOOT_API_CTX_EMMC_ERROR_STATUS_ACK_TIMEOUT 0x2U 75 #define BOOT_API_CTX_EMMC_ERROR_STATUS_DATA_CRC_FAIL 0x3U 76 #define BOOT_API_CTX_EMMC_ERROR_STATUS_NOT_ENOUGH_BOOT_DATA_RX 0x4U 77 #define BOOT_API_CTX_EMMC_ERROR_STATUS_HEADER_NOT_FOUND 0x5U 78 #define BOOT_API_CTX_EMMC_ERROR_STATUS_HEADER_SIZE_ZERO 0x6U 79 #define BOOT_API_CTX_EMMC_ERROR_STATUS_IMAGE_NOT_COMPLETE 0x7U 80 #define BOOT_API_CTX_EMMC_ERROR_STATUS_ACK_ERROR 0x8U 81 82 /* Definitions relative to 'p_rom_version_info->platform_type_ver' field */ 83 #define BOOT_API_CTX_ROM_VERSION_PLAT_VER_IC_EMU_FPGA 0xAA 84 #define BOOT_API_CTX_ROM_VERSION_PLAT_VER_FPGA_ONLY 0xBB 85 86 /* Image Header related definitions */ 87 88 /* Definition of header version */ 89 #if STM32MP21 90 #define BOOT_API_HEADER_VERSION 0x00020300U 91 #else /* STM32MP21 */ 92 #define BOOT_API_HEADER_VERSION 0x00020200U 93 #endif /* STM32MP21 */ 94 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_256_LEN_IN_BYTES 64 105 #define BOOT_API_ECDSA_SIGNATURE_256_LEN_IN_BYTES 64 106 #define BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES 32 107 #define BOOT_API_ECDSA_PUB_KEY_384_LEN_IN_BYTES 96 108 #define BOOT_API_ECDSA_SIGNATURE_384_LEN_IN_BYTES 96 109 #define BOOT_API_SHA384_DIGEST_SIZE_IN_BYTES 48 110 111 #define BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES \ 112 BOOT_API_ECDSA_PUB_KEY_256_LEN_IN_BYTES 113 #define BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES \ 114 BOOT_API_ECDSA_SIGNATURE_256_LEN_IN_BYTES 115 116 /* Possible values of the field 'boot_api_image_header_t.ecc_algo_type' */ 117 #define BOOT_API_ECDSA_ALGO_TYPE_P256NIST 1 118 #define BOOT_API_ECDSA_ALGO_TYPE_BRAINPOOL256 2 119 #define BOOT_API_ECDSA_ALGO_TYPE_P384NIST 3 120 #define BOOT_API_ECDSA_ALGO_TYPE_BRAINPOOL384 4 121 122 /* 123 * Extension headers related definitions 124 */ 125 /* 'bootapi_image_header_t.extension_flag' used for authentication feature */ 126 #define BOOT_API_AUTHENTICATION_EXTENSION_BIT BIT(0) 127 /* 'bootapi_image_header_t.extension_flag' used for FSBL decryption feature */ 128 #define BOOT_API_FSBL_DECRYPTION_EXTENSION_BIT BIT(1) 129 /* 'bootapi_image_header_t.extension_flag' used for padding header feature */ 130 #define BOOT_API_PADDING_EXTENSION_BIT BIT(31) 131 /* 132 * mask of bits of field 'bootapi_image_header_t.extension_flag' 133 * used for extension headers 134 */ 135 #define BOOT_API_ALL_EXTENSIONS_MASK \ 136 (BOOT_API_AUTHENTICATION_EXTENSION_BIT | \ 137 BOOT_API_FSBL_DECRYPTION_EXTENSION_BIT | \ 138 BOOT_API_PADDING_EXTENSION_BIT) 139 /* 140 * Magic number of FSBL decryption extension header 141 * The value shall gives the four bytes 'S','T',0x00,0x01 in memory 142 */ 143 #define BOOT_API_FSBL_DECRYPTION_HEADER_MAGIC_NB 0x01005453U 144 145 /* 146 * Magic number of PKH revocation extension header 147 * The value shall gives the four bytes 'S','T',0x00,0x02 in memory 148 */ 149 #define BOOT_API_AUTHENTICATION_HEADER_MAGIC_NB 0x02005453U 150 151 /* Max number of ECDSA public key hash in table */ 152 #define BOOT_API_AUTHENTICATION_NB_PKH_MAX 8U 153 154 /* ECDSA public key hash table size in bytes */ 155 #define BOOT_API_AUTHENTICATION_TABLE_SIZE_BYTES \ 156 (BOOT_API_AUTHENTICATION_NB_PKH_MAX * \ 157 BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES) 158 159 /* 160 * Magic number of padding extension header 161 * The value shall gives the four bytes 'S','T',0xFF,0xFF in memory 162 */ 163 #define BOOT_API_PADDING_HEADER_MAGIC_NB 0xFFFF5453U 164 165 /* 166 * Related to binaryType 167 * 0x00: U-Boot 168 * 0x10-0x1F: TF-A 169 * 0x20-0X2F: OPTEE 170 * 0x30: CM33 image 171 */ 172 #define BOOT_API_IMAGE_TYPE_UBOOT 0x0 173 #define BOOT_API_IMAGE_TYPE_M33 0x30 174 175 /* 176 * Cores secure magic numbers 177 * Constant to be stored in bakcup register 178 * BOOT_API_MAGIC_NUMBER_TAMP_BCK_REG_IDX 179 */ 180 #define BOOT_API_A35_CORE0_MAGIC_NUMBER 0xCA7FACE0U 181 #if !STM32MP21 182 #define BOOT_API_A35_CORE1_MAGIC_NUMBER 0xCA7FACE1U 183 184 /* 185 * TAMP_BCK9R register index 186 * This register is used to write a Magic Number in order to restart 187 * Cortex A35 Core 1 and make it execute @ branch address from TAMP_BCK5R 188 */ 189 #define BOOT_API_CORE1_MAGIC_NUMBER_TAMP_BCK_REG_IDX 9U 190 191 /* 192 * TAMP_BCK10R register index 193 * This register is used to contain the branch address of 194 * Cortex A35 Core 1 when restarted by a TAMP_BCK4R magic number writing 195 */ 196 #define BOOT_API_CORE1_BRANCH_ADDRESS_TAMP_BCK_REG_IDX 10U 197 #endif /* !STM32MP21 */ 198 199 /* 200 * Possible value of boot context field 'hse_clock_value_in_hz' 201 */ 202 #define BOOT_API_CTX_HSE_CLOCK_VALUE_UNDEFINED 0U 203 #define BOOT_API_CTX_HSE_CLOCK_VALUE_19_2_MHZ 19200000U 204 #define BOOT_API_CTX_HSE_CLOCK_VALUE_24_MHZ 24000000U 205 #define BOOT_API_CTX_HSE_CLOCK_VALUE_25_MHZ 25000000U 206 #define BOOT_API_CTX_HSE_CLOCK_VALUE_26_MHZ 26000000U 207 #define BOOT_API_CTX_HSE_CLOCK_VALUE_40_MHZ 40000000U 208 #define BOOT_API_CTX_HSE_CLOCK_VALUE_48_MHZ 48000000U 209 210 /* 211 * Possible value of boot context field 'boot_partition_used_toboot' 212 */ 213 #define BOOT_API_CTX_BOOT_PARTITION_UNDEFINED 0U 214 215 /* Used FSBL1 to boot */ 216 #define BOOT_API_CTX_BOOT_PARTITION_FSBL1 1U 217 218 /* Used FSBL2 to boot */ 219 #define BOOT_API_CTX_BOOT_PARTITION_FSBL2 2U 220 221 #define BOOT_API_RETURN_OK 0x66U 222 223 /* 224 * Possible values of boot context field 225 * 'ssp_config_ptr_in->ssp_cmd' 226 */ 227 /* 'K' 'B' 'U' 'P' -.> 'PUBK' */ 228 #define BOOT_API_CTX_SSP_CMD_CALC_CHIP_PUBK 0x4B425550 229 230 /* 231 * Exported types 232 */ 233 234 /* 235 * bootROM version information structure definition 236 * Total size = 24 bytes = 6 uint32_t 237 */ 238 typedef struct { 239 /* Chip Version */ 240 uint32_t chip_ver; 241 242 /* Cut version within a fixed chip version */ 243 uint32_t cut_ver; 244 245 /* Version of ROM Mask within a fixed cut version */ 246 uint32_t rom_mask_ver; 247 248 /* Internal Version of bootROM code */ 249 uint32_t bootrom_ver; 250 251 /* Version of bootROM adapted */ 252 uint32_t for_chip_design_rtl_ver; 253 254 /* Restriction on compiled platform when it applies */ 255 uint32_t platform_type_ver; 256 } boot_api_rom_version_info_t; 257 258 /* 259 * Boot Context related definitions 260 */ 261 262 /* 263 * Boot core boot configuration structure 264 * Specifies all items of the secure boot configuration 265 * Memory and peripheral part. 266 */ 267 typedef struct { 268 /* Boot partition: ie FSBL partition on which the boot was successful */ 269 uint32_t boot_partition_used_toboot; 270 271 uint32_t reserved1[3]; 272 273 /* 274 * Information specific to an SD boot 275 * Updated each time an SD boot is at least attempted, 276 * even if not successful 277 * Note : This is useful to understand why an SD boot failed 278 * in particular 279 */ 280 uint32_t sd_err_internal_timeout_cnt; 281 uint32_t sd_err_dcrc_fail_cnt; 282 uint32_t sd_err_dtimeout_cnt; 283 uint32_t sd_err_ctimeout_cnt; 284 uint32_t sd_err_ccrc_fail_cnt; 285 uint32_t sd_overall_retry_cnt; 286 /* 287 * Information specific to an eMMC boot 288 * Updated each time an eMMC boot is at least attempted, 289 * even if not successful 290 * Note : This is useful to understand why an eMMC boot failed 291 * in particular 292 */ 293 uint32_t emmc_xfer_status; 294 uint32_t emmc_error_status; 295 uint32_t emmc_nbbytes_rxcopied_tosysram_download_area; 296 297 uint32_t reserved[4]; 298 /* 299 * Boot interface used to boot : take values from defines 300 * BOOT_API_CTX_BOOT_INTERFACE_SEL_XXX above 301 */ 302 uint16_t boot_interface_selected; 303 uint16_t boot_interface_instance; 304 305 uint32_t hse_clock_value_in_hz; 306 307 uint32_t nand_fsbl_first_block; 308 309 /* 310 * Returned authentication status : take values from defines 311 * BOOT_API_CTX_AUTH_XXX above 312 */ 313 uint32_t auth_status; 314 315 /* Pointer on ROM constant containing ROM information */ 316 const boot_api_rom_version_info_t *p_rom_version_info; 317 } __packed boot_api_context_t; 318 319 /* 320 * Image Header related definitions 321 */ 322 323 /* 324 * Structure used to define the common Header format used for FSBL, xloader, 325 * ... and in particular used by bootROM for FSBL header readout. 326 * FSBL header size is 256 Bytes = 0x100 327 */ 328 typedef struct { 329 /* BOOT_API_IMAGE_HEADER_MAGIC_NB */ 330 uint32_t magic; 331 #if STM32MP21 332 uint8_t image_signature[BOOT_API_ECDSA_SIGNATURE_384_LEN_IN_BYTES]; 333 #else /* STM32MP21 */ 334 uint8_t image_signature[BOOT_API_ECDSA_SIGNATURE_256_LEN_IN_BYTES]; 335 #endif /* STM32MP21 */ 336 /* 337 * Checksum of payload 338 * 32-bit sum all payload bytes considered as 8 bit unsigned 339 * numbers, discarding any overflow bits. 340 * Use to check UART/USB downloaded image integrity when signature 341 * is not used 342 */ 343 uint32_t payload_checksum; 344 /* Image header version : should have value BOOT_API_HEADER_VERSION */ 345 uint32_t header_version; 346 /* Image length in bytes */ 347 uint32_t image_length; 348 /* 349 * Image Entry point address : should be in the SYSRAM area 350 * and at least within the download area range 351 */ 352 uint32_t image_entry_point; 353 /* Reserved */ 354 uint32_t reserved1; 355 /* 356 * Image load address : not used by bootROM but to be consistent 357 * with header format for other packages (xloader, ...) 358 */ 359 uint32_t load_address; 360 /* Reserved */ 361 uint32_t reserved2; 362 /* Image version to be compared by bootROM with FSBL_A or FSBL_M version 363 * counter value in OTP prior executing the downloaded image 364 */ 365 uint32_t image_version; 366 /* 367 * Extension flags : 368 * 369 * Bit 0 : Authentication extension header 370 * value 0 : No signature check request 371 * Bit 1 : Encryption extension header 372 * Bit 2 : Padding extension header 373 */ 374 uint32_t extension_flags; 375 /* Length in bytes of all extension headers */ 376 uint32_t extension_headers_length; 377 /* Add binary type information */ 378 uint32_t binary_type; 379 /* Pad up to 128 byte total size */ 380 uint8_t pad[16]; 381 /* Followed by extension header */ 382 uint8_t ext_header[]; 383 } __packed boot_api_image_header_t; 384 385 #if STM32MP21 386 typedef uint8_t boot_api_sha384_t[BOOT_API_SHA384_DIGEST_SIZE_IN_BYTES]; 387 #endif /* STM32MP21 */ 388 typedef uint8_t boot_api_sha256_t[BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES]; 389 390 typedef struct { 391 /* Extension header type: 392 * BOOT_API_FSBL_DECRYPTION_HEADER_MAGIC_NB or 393 * BOOT_API_AUTHENTICATION_HEADER_MAGIC_NB 394 * BOOT_API_PADDING_HEADER_MAGIC_NB 395 */ 396 uint32_t type; 397 /* Extension header len in byte */ 398 uint32_t len; 399 /* parameters of this extension */ 400 uint8_t params[]; 401 } __packed boot_extension_header_t; 402 403 typedef struct { 404 /* Idx of ECDSA public key to be used in table */ 405 uint32_t pk_idx; 406 /* Number of ECDSA public key in table */ 407 uint32_t nb_pk; 408 /* 409 * Type of ECC algorithm to use : 410 * value 1 : for P-256 NIST algorithm 411 * value 2 : for Brainpool 256 algorithm 412 * See definitions 'BOOT_API_ECDSA_ALGO_TYPE_XXX' above. 413 */ 414 uint32_t ecc_algo_type; 415 /* ECDSA public key to be used to check signature. */ 416 417 /* table of Hash of Algo+ECDSA public key */ 418 #if STM32MP21 419 uint8_t ecc_pubk[BOOT_API_ECDSA_PUB_KEY_384_LEN_IN_BYTES]; 420 boot_api_sha384_t pk_hashes[]; 421 #else /* STM32MP21 */ 422 uint8_t ecc_pubk[BOOT_API_ECDSA_PUB_KEY_256_LEN_IN_BYTES]; 423 boot_api_sha256_t pk_hashes[]; 424 #endif /* STM32MP21 */ 425 } __packed boot_ext_header_params_authentication_t; 426 427 typedef struct { 428 /* Size of encryption key (128 or 256) */ 429 uint32_t key_size; 430 uint32_t derivation_cont; 431 /* 128 msb bits of plain payload SHA256 */ 432 uint32_t hash[4]; 433 } __packed boot_ext_header_params_encrypted_fsbl_t; 434 435 #endif /* BOOT_API_H */ 436