1 /* 2 * Copyright (c) 2017-2022, 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 * Possible value of boot context field 'auth_status' 15 */ 16 #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 25 /* 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 31 #endif 32 33 /* 34 * 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 46 /* Boot occurred on FMC */ 47 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NAND_FMC 0x3U 48 49 /* Boot occurred on QSPI NOR */ 50 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NOR_QSPI 0x4U 51 52 /* Boot occurred on UART */ 53 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_SERIAL_UART 0x5U 54 55 /* Boot occurred on USB */ 56 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_SERIAL_USB 0x6U 57 58 /* Boot occurred on QSPI NAND */ 59 #define BOOT_API_CTX_BOOT_INTERFACE_SEL_FLASH_NAND_QSPI 0x7U 60 61 /** 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 83 #define BOOT_API_CTX_EMMC_ERROR_STATUS_ACK_ERROR 0x8U 84 85 /* Image Header related definitions */ 86 87 /* Definition of header version */ 88 #if STM32MP13 89 #define BOOT_API_HEADER_VERSION 0x00020000U 90 #endif 91 #if STM32MP15 92 #define BOOT_API_HEADER_VERSION 0x00010000U 93 #endif 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_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 /* 113 * 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 /* 156 * 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 201 #define BOOT_API_RETURN_OK 0x77U 202 203 /* 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 */ 212 typedef 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; 219 #if STM32MP13 220 uint32_t reserved1[12]; 221 #endif 222 #if STM32MP15 223 uint32_t reserved1[13]; 224 #endif 225 uint32_t otp_afmux_values[3]; 226 uint32_t reserved[3]; 227 #if STM32MP15 228 uint32_t reserved2[2]; 229 #endif 230 uint32_t auth_status; 231 232 #if STM32MP15 233 /* 234 * Pointers to bootROM External Secure Services 235 * - ECDSA verify signature 236 */ 237 uint32_t reserved3; 238 uint32_t (*bootrom_ecdsa_verify_signature)(uint8_t *hash_in, 239 uint8_t *pubkey_in, 240 uint8_t *signature, 241 uint32_t ecc_algo); 242 uint32_t reserved4; 243 #endif 244 /* 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 */ 285 typedef 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 291 * 32-bit sum all payload bytes considered as 8 bit unsigned 292 * numbers, discarding any overflow bits. 293 * Use to check UART/USB downloaded image integrity when signature 294 * is not used 295 */ 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; 319 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]; 336 /* Followed by extension header */ 337 uint8_t ext_header[]; 338 #endif 339 #if STM32MP15 340 /* 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 */ 362 uint8_t pad[83]; 363 /* Add binary type information */ 364 uint8_t binary_type; 365 #endif 366 } __packed boot_api_image_header_t; 367 368 typedef uint8_t boot_api_sha256_t[BOOT_API_SHA256_DIGEST_SIZE_IN_BYTES]; 369 370 typedef 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 383 typedef 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 401 typedef 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 409 #endif /* BOOT_API_H */ 410