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