@web-font-path: "roboto-debian.css";
Loading...
Searching...
No Matches
bootrom_constants.h
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)
137typedef 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
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__
266static_assert(OTP_CMD_WRITE_BITS == (1 << OTP_CMD_WRITE_LSB), "");
267static_assert(OTP_CMD_ECC_BITS == (1 << OTP_CMD_ECC_LSB), "");
268
269typedef struct {
270 uint32_t permissions_and_location;
271 uint32_t permissions_and_flags;
273static_assert(sizeof(resident_partition_t) == 8, "");
274
275typedef struct otp_cmd {
276 uint32_t flags;
277} otp_cmd_t;
278
279typedef 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
307typedef struct cflash_flags {
308 uint32_t flags;
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
Definition bootrom_constants.h:307
Definition bootrom_constants.h:275
Definition bootrom_constants.h:269