1 /* 2 * Copyright (c) 2023, 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 #define BOOT_API_HEADER_VERSION 0x00020000U 90 91 /* 92 * Magic number used to detect header in memory 93 * Its value must be 'S' 'T' 'M' 0x32, i.e 0x324D5453 as field 94 * 'bootapi_image_header_t.magic' 95 * This identifies the start of a boot image. 96 */ 97 #define BOOT_API_IMAGE_HEADER_MAGIC_NB 0x324D5453U 98 99 /* Definitions related to Authentication used in image header structure */ 100 #define BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES 64 101 #define BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES 64 102 #define BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES 32 103 104 /* Possible values of the field 'boot_api_image_header_t.ecc_algo_type' */ 105 #define BOOT_API_ECDSA_ALGO_TYPE_P256NIST 1 106 #define BOOT_API_ECDSA_ALGO_TYPE_BRAINPOOL256 2 107 108 /* 109 * Extension headers related definitions 110 */ 111 /* 'bootapi_image_header_t.extension_flag' used for authentication feature */ 112 #define BOOT_API_AUTHENTICATION_EXTENSION_BIT BIT(0) 113 /* 'bootapi_image_header_t.extension_flag' used for FSBL decryption feature */ 114 #define BOOT_API_FSBL_DECRYPTION_EXTENSION_BIT BIT(1) 115 /* 'bootapi_image_header_t.extension_flag' used for padding header feature */ 116 #define BOOT_API_PADDING_EXTENSION_BIT BIT(31) 117 /* 118 * mask of bits of field 'bootapi_image_header_t.extension_flag' 119 * used for extension headers 120 */ 121 #define BOOT_API_ALL_EXTENSIONS_MASK \ 122 (BOOT_API_AUTHENTICATION_EXTENSION_BIT | \ 123 BOOT_API_FSBL_DECRYPTION_EXTENSION_BIT | \ 124 BOOT_API_PADDING_EXTENSION_BIT) 125 /* 126 * Magic number of FSBL decryption extension header 127 * The value shall gives the four bytes 'S','T',0x00,0x01 in memory 128 */ 129 #define BOOT_API_FSBL_DECRYPTION_HEADER_MAGIC_NB 0x01005453U 130 131 /* 132 * Magic number of PKH revocation extension header 133 * The value shall gives the four bytes 'S','T',0x00,0x02 in memory 134 */ 135 #define BOOT_API_AUTHENTICATION_HEADER_MAGIC_NB 0x02005453U 136 137 /* Max number of ECDSA public key hash in table */ 138 #define BOOT_API_AUTHENTICATION_NB_PKH_MAX 8U 139 140 /* ECDSA public key hash table size in bytes */ 141 #define BOOT_API_AUTHENTICATION_TABLE_SIZE_BYTES \ 142 (BOOT_API_AUTHENTICATION_NB_PKH_MAX * \ 143 BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES) 144 145 /* 146 * Magic number of padding extension header 147 * The value shall gives the four bytes 'S','T',0xFF,0xFF in memory 148 */ 149 #define BOOT_API_PADDING_HEADER_MAGIC_NB 0xFFFF5453U 150 151 /* 152 * Related to binaryType 153 * 0x00: U-Boot 154 * 0x10-0x1F: TF-A 155 * 0x20-0X2F: OPTEE 156 * 0x30: CM33 image 157 */ 158 #define BOOT_API_IMAGE_TYPE_UBOOT 0x0 159 #define BOOT_API_IMAGE_TYPE_M33 0x30 160 161 /* 162 * Cores secure magic numbers 163 * Constant to be stored in bakcup register 164 * BOOT_API_MAGIC_NUMBER_TAMP_BCK_REG_IDX 165 */ 166 #define BOOT_API_A35_CORE0_MAGIC_NUMBER 0xCA7FACE0U 167 #define BOOT_API_A35_CORE1_MAGIC_NUMBER 0xCA7FACE1U 168 169 /* 170 * TAMP_BCK9R register index 171 * This register is used to write a Magic Number in order to restart 172 * Cortex A35 Core 1 and make it execute @ branch address from TAMP_BCK5R 173 */ 174 #define BOOT_API_CORE1_MAGIC_NUMBER_TAMP_BCK_REG_IDX 9U 175 176 /* 177 * TAMP_BCK10R register index 178 * This register is used to contain the branch address of 179 * Cortex A35 Core 1 when restarted by a TAMP_BCK4R magic number writing 180 */ 181 #define BOOT_API_CORE1_BRANCH_ADDRESS_TAMP_BCK_REG_IDX 10U 182 183 /* 184 * Possible value of boot context field 'hse_clock_value_in_hz' 185 */ 186 #define BOOT_API_CTX_HSE_CLOCK_VALUE_UNDEFINED 0U 187 #define BOOT_API_CTX_HSE_CLOCK_VALUE_19_2_MHZ 19200000U 188 #define BOOT_API_CTX_HSE_CLOCK_VALUE_24_MHZ 24000000U 189 #define BOOT_API_CTX_HSE_CLOCK_VALUE_25_MHZ 25000000U 190 #define BOOT_API_CTX_HSE_CLOCK_VALUE_26_MHZ 26000000U 191 #define BOOT_API_CTX_HSE_CLOCK_VALUE_40_MHZ 40000000U 192 #define BOOT_API_CTX_HSE_CLOCK_VALUE_48_MHZ 48000000U 193 194 /* 195 * Possible value of boot context field 'boot_partition_used_toboot' 196 */ 197 #define BOOT_API_CTX_BOOT_PARTITION_UNDEFINED 0U 198 199 /* Used FSBL1 to boot */ 200 #define BOOT_API_CTX_BOOT_PARTITION_FSBL1 1U 201 202 /* Used FSBL2 to boot */ 203 #define BOOT_API_CTX_BOOT_PARTITION_FSBL2 2U 204 205 #define BOOT_API_RETURN_OK 0x66U 206 207 /* 208 * Possible values of boot context field 209 * 'ssp_config_ptr_in->ssp_cmd' 210 */ 211 /* 'K' 'B' 'U' 'P' -.> 'PUBK' */ 212 #define BOOT_API_CTX_SSP_CMD_CALC_CHIP_PUBK 0x4B425550 213 214 /* 215 * Exported types 216 */ 217 218 /* 219 * bootROM version information structure definition 220 * Total size = 24 bytes = 6 uint32_t 221 */ 222 typedef struct { 223 /* Chip Version */ 224 uint32_t chip_ver; 225 226 /* Cut version within a fixed chip version */ 227 uint32_t cut_ver; 228 229 /* Version of ROM Mask within a fixed cut version */ 230 uint32_t rom_mask_ver; 231 232 /* Internal Version of bootROM code */ 233 uint32_t bootrom_ver; 234 235 /* Version of bootROM adapted */ 236 uint32_t for_chip_design_rtl_ver; 237 238 /* Restriction on compiled platform when it applies */ 239 uint32_t platform_type_ver; 240 } boot_api_rom_version_info_t; 241 242 /* 243 * Boot Context related definitions 244 */ 245 246 /* 247 * Boot core boot configuration structure 248 * Specifies all items of the secure boot configuration 249 * Memory and peripheral part. 250 */ 251 typedef struct { 252 /* Boot partition: ie FSBL partition on which the boot was successful */ 253 uint32_t boot_partition_used_toboot; 254 255 uint32_t reserved1[3]; 256 257 /* 258 * Information specific to an SD boot 259 * Updated each time an SD boot is at least attempted, 260 * even if not successful 261 * Note : This is useful to understand why an SD boot failed 262 * in particular 263 */ 264 uint32_t sd_err_internal_timeout_cnt; 265 uint32_t sd_err_dcrc_fail_cnt; 266 uint32_t sd_err_dtimeout_cnt; 267 uint32_t sd_err_ctimeout_cnt; 268 uint32_t sd_err_ccrc_fail_cnt; 269 uint32_t sd_overall_retry_cnt; 270 /* 271 * Information specific to an eMMC boot 272 * Updated each time an eMMC boot is at least attempted, 273 * even if not successful 274 * Note : This is useful to understand why an eMMC boot failed 275 * in particular 276 */ 277 uint32_t emmc_xfer_status; 278 uint32_t emmc_error_status; 279 uint32_t emmc_nbbytes_rxcopied_tosysram_download_area; 280 281 uint32_t reserved[4]; 282 /* 283 * Boot interface used to boot : take values from defines 284 * BOOT_API_CTX_BOOT_INTERFACE_SEL_XXX above 285 */ 286 uint16_t boot_interface_selected; 287 uint16_t boot_interface_instance; 288 289 uint32_t hse_clock_value_in_hz; 290 291 uint32_t nand_fsbl_first_block; 292 293 /* 294 * Returned authentication status : take values from defines 295 * BOOT_API_CTX_AUTH_XXX above 296 */ 297 uint32_t auth_status; 298 299 /* Pointer on ROM constant containing ROM information */ 300 const boot_api_rom_version_info_t *p_rom_version_info; 301 } __packed boot_api_context_t; 302 303 /* 304 * Image Header related definitions 305 */ 306 307 /* 308 * Structure used to define the common Header format used for FSBL, xloader, 309 * ... and in particular used by bootROM for FSBL header readout. 310 * FSBL header size is 256 Bytes = 0x100 311 */ 312 typedef struct { 313 /* BOOT_API_IMAGE_HEADER_MAGIC_NB */ 314 uint32_t magic; 315 uint8_t image_signature[BOOT_API_ECDSA_SIGNATURE_LEN_IN_BYTES]; 316 /* 317 * Checksum of payload 318 * 32-bit sum all payload bytes considered as 8 bit unsigned 319 * numbers, discarding any overflow bits. 320 * Use to check UART/USB downloaded image integrity when signature 321 * is not used 322 */ 323 uint32_t payload_checksum; 324 /* Image header version : should have value BOOT_API_HEADER_VERSION */ 325 uint32_t header_version; 326 /* Image length in bytes */ 327 uint32_t image_length; 328 /* 329 * Image Entry point address : should be in the SYSRAM area 330 * and at least within the download area range 331 */ 332 uint32_t image_entry_point; 333 /* Reserved */ 334 uint32_t reserved1; 335 /* 336 * Image load address : not used by bootROM but to be consistent 337 * with header format for other packages (xloader, ...) 338 */ 339 uint32_t load_address; 340 /* Reserved */ 341 uint32_t reserved2; 342 /* Image version to be compared by bootROM with FSBL_A or FSBL_M version 343 * counter value in OTP prior executing the downloaded image 344 */ 345 uint32_t image_version; 346 /* 347 * Extension flags : 348 * 349 * Bit 0 : Authentication extension header 350 * value 0 : No signature check request 351 * Bit 1 : Encryption extension header 352 * Bit 2 : Padding extension header 353 */ 354 uint32_t extension_flags; 355 /* Length in bytes of all extension headers */ 356 uint32_t extension_headers_length; 357 /* Add binary type information */ 358 uint32_t binary_type; 359 /* Pad up to 128 byte total size */ 360 uint8_t pad[16]; 361 /* Followed by extension header */ 362 uint8_t ext_header[]; 363 } __packed boot_api_image_header_t; 364 365 typedef uint8_t boot_api_sha256_t[BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES]; 366 367 typedef struct { 368 /* Extension header type: 369 * BOOT_API_FSBL_DECRYPTION_HEADER_MAGIC_NB or 370 * BOOT_API_AUTHENTICATION_HEADER_MAGIC_NB 371 * BOOT_API_PADDING_HEADER_MAGIC_NB 372 */ 373 uint32_t type; 374 /* Extension header len in byte */ 375 uint32_t len; 376 /* parameters of this extension */ 377 uint8_t params[]; 378 } __packed boot_extension_header_t; 379 380 typedef struct { 381 /* Idx of ECDSA public key to be used in table */ 382 uint32_t pk_idx; 383 /* Number of ECDSA public key in table */ 384 uint32_t nb_pk; 385 /* 386 * Type of ECC algorithm to use : 387 * value 1 : for P-256 NIST algorithm 388 * value 2 : for Brainpool 256 algorithm 389 * See definitions 'BOOT_API_ECDSA_ALGO_TYPE_XXX' above. 390 */ 391 uint32_t ecc_algo_type; 392 /* ECDSA public key to be used to check signature. */ 393 uint8_t ecc_pubk[BOOT_API_ECDSA_PUB_KEY_LEN_IN_BYTES]; 394 /* table of Hash of Algo+ECDSA public key */ 395 boot_api_sha256_t pk_hashes[]; 396 } __packed boot_ext_header_params_authentication_t; 397 398 typedef struct { 399 /* Size of encryption key (128 or 256) */ 400 uint32_t key_size; 401 uint32_t derivation_cont; 402 /* 128 msb bits of plain payload SHA256 */ 403 uint32_t hash[4]; 404 } __packed boot_ext_header_params_encrypted_fsbl_t; 405 406 #endif /* BOOT_API_H */ 407