1 /* 2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _BOOT_BOOTROM_CONSTANTS_H 8 #define _BOOT_BOOTROM_CONSTANTS_H 9 10 #ifndef NO_PICO_PLATFORM 11 #include "pico/platform.h" 12 #endif 13 14 // ROOT ADDRESSES 15 #define BOOTROM_MAGIC_OFFSET 0x10 16 #define BOOTROM_FUNC_TABLE_OFFSET 0x14 17 #if PICO_RP2040 18 #define BOOTROM_DATA_TABLE_OFFSET 0x16 19 #endif 20 21 #if PICO_RP2040 22 #define BOOTROM_VTABLE_OFFSET 0x00 23 #define BOOTROM_TABLE_LOOKUP_OFFSET 0x18 24 #else 25 #define BOOTROM_WELL_KNOWN_PTR_SIZE 2 26 #if defined(__riscv) 27 #define BOOTROM_ENTRY_OFFSET 0x7dfc 28 #define BOOTROM_TABLE_LOOKUP_ENTRY_OFFSET (BOOTROM_ENTRY_OFFSET - BOOTROM_WELL_KNOWN_PTR_SIZE) 29 #define BOOTROM_TABLE_LOOKUP_OFFSET (BOOTROM_ENTRY_OFFSET - BOOTROM_WELL_KNOWN_PTR_SIZE*2) 30 #else 31 #define BOOTROM_VTABLE_OFFSET 0x00 32 #define BOOTROM_TABLE_LOOKUP_OFFSET (BOOTROM_FUNC_TABLE_OFFSET + BOOTROM_WELL_KNOWN_PTR_SIZE) 33 #endif 34 #endif 35 36 #if !PICO_RP2040 || PICO_COMBINED_DOCS 37 38 #define BOOTROM_OK 0 39 //#define BOOTROM_ERROR_TIMEOUT (-1) 40 //#define BOOTROM_ERROR_GENERIC (-2) 41 //#define BOOTROM_ERROR_NO_DATA (-3) // E.g. read from an empty buffer/FIFO 42 #define BOOTROM_ERROR_NOT_PERMITTED (-4) // Permission violation e.g. write to read-only flash partition 43 #define BOOTROM_ERROR_INVALID_ARG (-5) // Argument is outside of range of supported values` 44 //#define BOOTROM_ERROR_IO (-6) 45 //#define BOOTROM_ERROR_BADAUTH (-7) 46 //#define BOOTROM_ERROR_CONNECT_FAILED (-8) 47 //#define BOOTROM_ERROR_INSUFFICIENT_RESOURCES (-9) // Dynamic allocation of resources failed 48 #define BOOTROM_ERROR_INVALID_ADDRESS (-10) // Address argument was out-of-bounds or was determined to be an address that the caller may not access 49 #define BOOTROM_ERROR_BAD_ALIGNMENT (-11) // Address modulo transfer chunk size was nonzero (e.g. word-aligned transfer with address % 4 != 0) 50 #define BOOTROM_ERROR_INVALID_STATE (-12) // Something happened or failed to happen in the past, and consequently we (currently) can't service the request 51 #define BOOTROM_ERROR_BUFFER_TOO_SMALL (-13) // A user-allocated buffer was too small to hold the result or working state of this function 52 #define BOOTROM_ERROR_PRECONDITION_NOT_MET (-14) // This call failed because another ROM function must be called first 53 #define BOOTROM_ERROR_MODIFIED_DATA (-15) // Cached data was determined to be inconsistent with the full version of the data it was calculated from 54 #define BOOTROM_ERROR_INVALID_DATA (-16) // A data structure failed to validate 55 #define BOOTROM_ERROR_NOT_FOUND (-17) // Attempted to access something that does not exist; or, a search failed 56 #define BOOTROM_ERROR_UNSUPPORTED_MODIFICATION (-18) // Write is impossible based on previous writes; e.g. attempted to clear an OTP bit 57 #define BOOTROM_ERROR_LOCK_REQUIRED (-19) // A required lock is not owned 58 #define BOOTROM_ERROR_LAST (-19) 59 60 #define RT_FLAG_FUNC_RISCV 0x0001 61 #define RT_FLAG_FUNC_RISCV_FAR 0x0003 62 #define RT_FLAG_FUNC_ARM_SEC 0x0004 63 // reserved for 32-bit pointer: 0x0008 64 #define RT_FLAG_FUNC_ARM_NONSEC 0x0010 65 // reserved for 32-bit pointer: 0x0020 66 #define RT_FLAG_DATA 0x0040 67 // reserved for 32-bit pointer: 0x0080 68 69 #define PARTITION_TABLE_MAX_PARTITIONS 16 70 // note this is deliberately > MAX_PARTITIONs is likely to be, and also -1 as a signed byte 71 #define PARTITION_TABLE_NO_PARTITION_INDEX 0xff 72 73 // todo these are duplicated in picoboot_constants.h 74 // values 0-7 are secure/non-secure 75 #define BOOT_TYPE_NORMAL 0 76 #define BOOT_TYPE_BOOTSEL 2 77 #define BOOT_TYPE_RAM_IMAGE 3 78 #define BOOT_TYPE_FLASH_UPDATE 4 79 80 // values 8-15 are secure only 81 #define BOOT_TYPE_PC_SP 0xd 82 83 // ORed in if a bootloader chained into the image 84 #define BOOT_TYPE_CHAINED_FLAG 0x80 85 86 // call from NS to S 87 #ifndef __riscv 88 #define BOOTROM_API_CALLBACK_secure_call 0 89 #endif 90 #define BOOTROM_API_CALLBACK_COUNT 1 91 92 #define BOOTROM_LOCK_SHA_256 0 93 #define BOOTROM_LOCK_FLASH_OP 1 94 #define BOOTROM_LOCK_OTP 2 95 #define BOOTROM_LOCK_MAX 2 96 97 #define BOOTROM_LOCK_ENABLE 7 98 99 #define BOOT_PARTITION_NONE (-1) 100 #define BOOT_PARTITION_SLOT0 (-2) 101 #define BOOT_PARTITION_SLOT1 (-3) 102 #define BOOT_PARTITION_WINDOW (-4) 103 104 #define BOOT_DIAGNOSTIC_WINDOW_SEARCHED 0x01 105 // note if both BOOT_DIAGNOSTIC_INVALID_BLOCK_LOOP and BOOT_DIAGNOSTIC_VALID_BLOCK_LOOP then the block loop was valid 106 // but it has a PARTITION_TABLE which while it passed the initial verification (and hash/sig) had invalid contents 107 // (discovered when it was later loaded) 108 #define BOOT_DIAGNOSTIC_INVALID_BLOCK_LOOP 0x02 109 #define BOOT_DIAGNOSTIC_VALID_BLOCK_LOOP 0x04 110 #define BOOT_DIAGNOSTIC_VALID_IMAGE_DEF 0x08 111 #define BOOT_DIAGNOSTIC_HAS_PARTITION_TABLE 0x10 112 #define BOOT_DIAGNOSTIC_CONSIDERED 0x20 113 #define BOOT_DIAGNOSTIC_CHOSEN 0x40 114 #define BOOT_DIAGNOSTIC_PARTITION_TABLE_LSB 7 115 #define BOOT_DIAGNOSTIC_PARTITION_TABLE_MATCHING_KEY_FOR_VERIFY 0x80 116 #define BOOT_DIAGNOSTIC_PARTITION_TABLE_HASH_FOR_VERIFY 0x100 117 #define BOOT_DIAGNOSTIC_PARTITION_TABLE_VERIFIED_OK 0x200 118 #define BOOT_DIAGNOSTIC_IMAGE_DEF_LSB 10 119 #define BOOT_DIAGNOSTIC_IMAGE_DEF_MATCHING_KEY_FOR_VERIFY 0x400 120 #define BOOT_DIAGNOSTIC_IMAGE_DEF_HASH_FOR_VERIFY 0x800 121 #define BOOT_DIAGNOSTIC_IMAGE_DEF_VERIFIED_OK 0x1000 122 123 #define BOOT_DIAGNOSTIC_LOAD_MAP_ENTRIES_LOADED 0x2000 124 #define BOOT_DIAGNOSTIC_IMAGE_LAUNCHED 0x4000 125 #define BOOT_DIAGNOSTIC_IMAGE_CONDITION_FAILURE 0x8000 126 127 #define BOOT_PARSED_BLOCK_DIAGNOSTIC_MATCHING_KEY_FOR_VERIFY 0x1 // if this is present and VERIFIED_OK isn't the sig check failed 128 #define BOOT_PARSED_BLOCK_DIAGNOSTIC_HASH_FOR_VERIFY 0x2 // if this is present and VERIFIED_OL isn't then hash check failed 129 #define BOOT_PARSED_BLOCK_DIAGNOSTIC_VERIFIED_OK 0x4 130 131 #define BOOT_TBYB_AND_UPDATE_FLAG_BUY_PENDING 0x1 132 #define BOOT_TBYB_AND_UPDATE_FLAG_OTP_VERSION_APPLIED 0x2 133 #define BOOT_TBYB_AND_UPDATE_FLAG_OTHER_ERASED 0x4 134 135 #ifndef __ASSEMBLER__ 136 // Limited to 3 arguments in case of varm multiplex hint (trashes Arm r3) 137 typedef int (*bootrom_api_callback_generic_t)(uint32_t r0, uint32_t r1, uint32_t r2); 138 // Return negative for error, else number of bytes transferred: 139 //typedef int (*bootrom_api_callback_stdout_put_blocking_t)(const uint8_t *buffer, uint32_t size); 140 //typedef int (*bootrom_api_callback_stdin_get_t)(uint8_t *buffer, uint32_t size); 141 //typedef void (*bootrom_api_callback_core1_security_setup_t)(void); 142 #endif 143 144 #endif 145 146 /*! \brief Return a bootrom lookup code based on two ASCII characters 147 * \ingroup pico_bootrom 148 * 149 * These codes are uses to lookup data or function addresses in the bootrom 150 * 151 * \param c1 the first character 152 * \param c2 the second character 153 * \return the 'code' to use in rom_func_lookup() or rom_data_lookup() 154 */ 155 #define ROM_TABLE_CODE(c1, c2) ((c1) | ((c2) << 8)) 156 157 // ROM FUNCTIONS 158 159 // RP2040 & RP2350 160 #define ROM_DATA_SOFTWARE_GIT_REVISION ROM_TABLE_CODE('G', 'R') 161 #define ROM_FUNC_FLASH_ENTER_CMD_XIP ROM_TABLE_CODE('C', 'X') 162 #define ROM_FUNC_FLASH_EXIT_XIP ROM_TABLE_CODE('E', 'X') 163 #define ROM_FUNC_FLASH_FLUSH_CACHE ROM_TABLE_CODE('F', 'C') 164 #define ROM_FUNC_CONNECT_INTERNAL_FLASH ROM_TABLE_CODE('I', 'F') 165 #define ROM_FUNC_FLASH_RANGE_ERASE ROM_TABLE_CODE('R', 'E') 166 #define ROM_FUNC_FLASH_RANGE_PROGRAM ROM_TABLE_CODE('R', 'P') 167 168 169 #if PICO_RP2040 170 // RP2040 only 171 #define ROM_FUNC_MEMCPY44 ROM_TABLE_CODE('C', '4') 172 #define ROM_DATA_COPYRIGHT ROM_TABLE_CODE('C', 'R') 173 #define ROM_FUNC_CLZ32 ROM_TABLE_CODE('L', '3') 174 #define ROM_FUNC_MEMCPY ROM_TABLE_CODE('M', 'C') 175 #define ROM_FUNC_MEMSET ROM_TABLE_CODE('M', 'S') 176 #define ROM_FUNC_POPCOUNT32 ROM_TABLE_CODE('P', '3') 177 #define ROM_FUNC_REVERSE32 ROM_TABLE_CODE('R', '3') 178 #define ROM_FUNC_MEMSET4 ROM_TABLE_CODE('S', '4') 179 #define ROM_FUNC_CTZ32 ROM_TABLE_CODE('T', '3') 180 #define ROM_FUNC_RESET_USB_BOOT ROM_TABLE_CODE('U', 'B') 181 #endif 182 183 #if !PICO_RP2040 || PICO_COMBINED_DOCS 184 // RP2350 only 185 #define ROM_FUNC_PICK_AB_PARTITION ROM_TABLE_CODE('A', 'B') 186 #define ROM_FUNC_CHAIN_IMAGE ROM_TABLE_CODE('C', 'I') 187 #define ROM_FUNC_EXPLICIT_BUY ROM_TABLE_CODE('E', 'B') 188 #define ROM_FUNC_FLASH_RUNTIME_TO_STORAGE_ADDR ROM_TABLE_CODE('F', 'A') 189 #define ROM_DATA_FLASH_DEVINFO16_PTR ROM_TABLE_CODE('F', 'D') 190 #define ROM_FUNC_FLASH_OP ROM_TABLE_CODE('F', 'O') 191 #define ROM_FUNC_GET_B_PARTITION ROM_TABLE_CODE('G', 'B') 192 #define ROM_FUNC_GET_PARTITION_TABLE_INFO ROM_TABLE_CODE('G', 'P') 193 #define ROM_FUNC_GET_SYS_INFO ROM_TABLE_CODE('G', 'S') 194 #define ROM_FUNC_GET_UF2_TARGET_PARTITION ROM_TABLE_CODE('G', 'U') 195 #define ROM_FUNC_LOAD_PARTITION_TABLE ROM_TABLE_CODE('L', 'P') 196 #define ROM_FUNC_OTP_ACCESS ROM_TABLE_CODE('O', 'A') 197 #define ROM_DATA_PARTITION_TABLE_PTR ROM_TABLE_CODE('P', 'T') 198 #define ROM_FUNC_FLASH_RESET_ADDRESS_TRANS ROM_TABLE_CODE('R', 'A') 199 #define ROM_FUNC_REBOOT ROM_TABLE_CODE('R', 'B') 200 #define ROM_FUNC_SET_ROM_CALLBACK ROM_TABLE_CODE('R', 'C') 201 #define ROM_FUNC_SECURE_CALL ROM_TABLE_CODE('S', 'C') 202 #define ROM_FUNC_SET_NS_API_PERMISSION ROM_TABLE_CODE('S', 'P') 203 #define ROM_FUNC_BOOTROM_STATE_RESET ROM_TABLE_CODE('S', 'R') 204 #define ROM_FUNC_SET_BOOTROM_STACK ROM_TABLE_CODE('S', 'S') 205 #define ROM_DATA_SAVED_XIP_SETUP_FUNC_PTR ROM_TABLE_CODE('X', 'F') 206 #define ROM_FUNC_FLASH_SELECT_XIP_READ_MODE ROM_TABLE_CODE('X', 'M') 207 #define ROM_FUNC_VALIDATE_NS_BUFFER ROM_TABLE_CODE('V', 'B') 208 #endif 209 210 // these form a bit set 211 #define BOOTROM_STATE_RESET_CURRENT_CORE 0x01 212 #define BOOTROM_STATE_RESET_OTHER_CORE 0x02 213 #define BOOTROM_STATE_RESET_GLOBAL_STATE 0x04 // reset any global state (e.g. permissions) 214 215 // partition level stuff is returned first (note PT_INFO flags is only 16 bits) 216 217 // 3 words: pt_count, unpartitioned_perm_loc, unpartioned_perm_flags 218 #define PT_INFO_PT_INFO 0x0001 219 #define PT_INFO_SINGLE_PARTITION 0x8000 // marker to just include a single partition in the results) 220 221 // then in order per partition selected 222 223 // 2 words: unpartitioned_perm_loc, unpartioned_perm_flags 224 #define PT_INFO_PARTITION_LOCATION_AND_FLAGS 0x0010 225 // 2 words: id lsb first 226 #define PT_INFO_PARTITION_ID 0x0020 227 // n+1 words: n, family_id... 228 #define PT_INFO_PARTITION_FAMILY_IDS 0x0040 229 // (n+3)/4 words... bytes are: n (len), c0, c1, ... cn-1 padded to word boundary with zeroes 230 #define PT_INFO_PARTITION_NAME 0x0080 231 232 // items are returned in order 233 // 3 words package_id, device_id, wafer_id 234 #define SYS_INFO_CHIP_INFO 0x0001 235 // 1 word: chip specific critical bits 236 #define SYS_INFO_CRITICAL 0x0002 237 // 1 word: bytes: cpu_type, supported_cpu_type_bitfield 238 #define SYS_INFO_CPU_INFO 0x0004 239 // 1 word: same as FLASH_DEVINFO row in OTP 240 #define SYS_INFO_FLASH_DEV_INFO 0x0008 241 // 4 words 242 #define SYS_INFO_BOOT_RANDOM 0x0010 243 // 2 words lsb first 244 #define SYS_INFO_NONCE 0x0020 245 // 4 words boot_info, boot_diagnostic, boot_param0, boot_param1 246 #define SYS_INFO_BOOT_INFO 0x0040 247 248 #define BOOTROM_NS_API_get_sys_info 0 249 #define BOOTROM_NS_API_checked_flash_op 1 250 #define BOOTROM_NS_API_flash_runtime_to_storage_addr 2 251 #define BOOTROM_NS_API_get_partition_table_info 3 252 #define BOOTROM_NS_API_secure_call 4 253 #define BOOTROM_NS_API_otp_access 5 254 #define BOOTROM_NS_API_reboot 6 255 #define BOOTROM_NS_API_get_b_partition 7 256 #define BOOTROM_NS_API_COUNT 8 257 258 #define OTP_CMD_ROW_BITS 0x0000ffffu 259 #define OTP_CMD_ROW_LSB _u(0) 260 #define OTP_CMD_WRITE_BITS 0x00010000u 261 #define OTP_CMD_WRITE_LSB _u(16) 262 #define OTP_CMD_ECC_BITS 0x00020000u 263 #define OTP_CMD_ECC_LSB _u(17) 264 265 #ifndef __ASSEMBLER__ 266 static_assert(OTP_CMD_WRITE_BITS == (1 << OTP_CMD_WRITE_LSB), ""); 267 static_assert(OTP_CMD_ECC_BITS == (1 << OTP_CMD_ECC_LSB), ""); 268 269 typedef struct { 270 uint32_t permissions_and_location; 271 uint32_t permissions_and_flags; 272 } resident_partition_t; 273 static_assert(sizeof(resident_partition_t) == 8, ""); 274 275 typedef struct otp_cmd { 276 uint32_t flags; 277 } otp_cmd_t; 278 279 typedef enum { 280 BOOTROM_XIP_MODE_03H_SERIAL = 0, 281 BOOTROM_XIP_MODE_0BH_SERIAL, 282 BOOTROM_XIP_MODE_BBH_DUAL, 283 BOOTROM_XIP_MODE_EBH_QUAD, 284 BOOTROM_XIP_MODE_N_MODES 285 } bootrom_xip_mode_t; 286 287 // The checked flash API wraps the low-level flash routines from generic_flash, adding bounds 288 // checking, permission checking against the resident partition table, and simple address 289 // translation. The low-level API deals with flash offsets (i.e. distance from the start of the 290 // first flash device, measured in bytes) but the checked flash API accepts one of two types of 291 // address: 292 // 293 // - Flash runtime addresses: the address of some flash-resident data or code in the currently 294 // running image. The flash addresses your binary is "linked at" by the linker. 295 // - Flash storage addresses: a flash offset, plus the address base where QSPI hardware is first 296 // mapped on the system bus (XIP_BASE constant from addressmap.h) 297 // 298 // These addresses are one and the same *if* the currently running program is stored at the 299 // beginning of flash. They are different if the start of your image has been "rolled" by the flash 300 // boot path to make it appear at the address it was linked at even though it is stored at a 301 // different location in flash, which is necessary when you have A/B images for example. 302 // 303 // The address translation between flash runtime and flash storage addresses is configured in 304 // hardware by the QMI_ATRANSx registers, and this API assumes those registers contain a valid 305 // address mapping which it can use to translate runtime to storage addresses. 306 307 typedef struct cflash_flags { 308 uint32_t flags; 309 } cflash_flags_t; 310 311 #endif // #ifdef __ASSEMBLER__ 312 313 // Bits which are permitted to be set in a flags variable -- any other bits being set is an error 314 #define CFLASH_FLAGS_BITS 0x00070301u 315 316 // Used to tell checked flash API which space a given address belongs to 317 #define CFLASH_ASPACE_BITS 0x00000001u 318 #define CFLASH_ASPACE_LSB _u(0) 319 #define CFLASH_ASPACE_VALUE_STORAGE _u(0) 320 #define CFLASH_ASPACE_VALUE_RUNTIME _u(1) 321 322 // Used to tell checked flash APIs the effective security level of a flash access (may be forced to 323 // one of these values for the NonSecure-exported version of this API) 324 #define CFLASH_SECLEVEL_BITS 0x00000300u 325 #define CFLASH_SECLEVEL_LSB _u(8) 326 // Zero is not a valid security level: 327 #define CFLASH_SECLEVEL_VALUE_SECURE _u(1) 328 #define CFLASH_SECLEVEL_VALUE_NONSECURE _u(2) 329 #define CFLASH_SECLEVEL_VALUE_BOOTLOADER _u(3) 330 331 #define CFLASH_OP_BITS 0x00070000u 332 #define CFLASH_OP_LSB _u(16) 333 // Erase size_bytes bytes of flash, starting at address addr. Both addr and size_bytes must be a 334 // multiple of 4096 bytes (one flash sector). 335 #define CFLASH_OP_VALUE_ERASE _u(0) 336 // Program size_bytes bytes of flash, starting at address addr. Both addr and size_bytes must be a 337 // multiple of 256 bytes (one flash page). 338 #define CFLASH_OP_VALUE_PROGRAM _u(1) 339 // Read size_bytes bytes of flash, starting at address addr. There are no alignment restrictions on 340 // addr or size_bytes. 341 #define CFLASH_OP_VALUE_READ _u(2) 342 #define CFLASH_OP_MAX _u(2) 343 344 #endif 345
