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