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