On-flash layout of shared PRF storage entries. More...

Data Structures
struct	SprfRootKeys
	BLE root keys field. More...

struct	SprfBlePairingData
	BLE pairing field, for the device most recently paired. More...

struct	SprfBlePairingName
	BLE pairing device name field. More...

struct	SprfPinnedAddress
	Pinned address field. More...

struct	SprfGettingStarted
	Onboarding (getting started) field. More...

struct	SprfLocalName
	Custom local device name field. More...

struct	SprfLocalIdentityAddress
	Local identity address field. More...

struct	SharedPRFData
	Legacy shared PRF storage contents. More...

struct	SharedPRFData.main_fw_scratch
	Area reserved for the normal firmware to stash pairing related data. More...

Macros
#define	SPRF_PAGE_IDX_INVALID ((uint16_t)~0)
	Page index meaning no valid entry has been found.

#define	SPRF_MAX_NUM_PAGES_MULT(num) ((num) * 3 / 4)
	Page index beyond which the region is compacted at boot.

Enumerations
enum	SprfValidFields { SprfValidFields_LocalEncryptionInfoValid = (1 << 0) , SprfValidFields_RemoteEncryptionInfoValid = (1 << 1) , SprfValidFields_RemoteIdentityInfoValid = (1 << 2) , SprfValidFields_RemoteSigningInfoValid = (1 << 3) }
	Valid parts of SprfBlePairingData. More...

enum	SprfMagic { SprfMagic_ValidEntry = 0x46525053 , SprfMagic_UnpopulatedEntry = 0xFFFFFFFF , SprfMagic_InvalidatedEntry = 0x0 }
	Entry header magic. More...

Detailed Description

On-flash layout of shared PRF storage entries.

The region holds a rolling list of SharedPRFData entries of 256 bytes, so that a whole number of them fits in a flash sector. Exactly one entry is valid (or unpopulated); entries before it are invalidated.

An entry is made of fields, each starting with a CRC-32 (pbl_crc32()) of the rest of the field, written once the field is complete. A field is:

unpopulated if it is all 0xFF;
valid if its CRC matches its contents;
corrupted, e.g. partially written, otherwise, which invalidates the whole entry.

Rewriting a field invalidates the current entry and copies its other fields to the next one.

Data Structure Documentation

◆ SprfRootKeys

struct SprfRootKeys

BLE root keys field.

Data Fields
uint32_t	crc	Field CRC.
struct pbl_bt_sm_key	keys[PBL_BT_SM_ROOT_KEY_TYPE_NUM]	Keys indexed by pbl_bt_sm_root_key_type.

◆ SprfBlePairingData

struct SprfBlePairingData

BLE pairing field, for the device most recently paired.

Data Fields
uint32_t	crc	Field CRC.
struct pbl_bt_sm_key	csrk	Remote CSRK.
SprfValidFields	fields: 8	Valid parts, SprfValidFields bits. 0 means no pairing.
uint8_t	flags	Pairing flags. Added in version 2, always 0 in version 1.
struct pbl_bt_device_internal	identity	Remote identity address.
struct pbl_bt_sm_key	irk	Remote IRK.
bool	is_mitm_protection_enabled	Pairing has MITM protection.
uint16_t	l_ediv	Local EDIV.
struct pbl_bt_sm_key	l_ltk	Local LTK.
uint64_t	l_rand	Local Rand.
uint16_t	r_ediv	Remote EDIV.
struct pbl_bt_sm_key	r_ltk	Remote LTK.
uint64_t	r_rand	Remote Rand.
bool	requires_address_pinning	Pairing requires address pinning.

◆ SprfBlePairingName

struct SprfBlePairingName

BLE pairing device name field.

Data Fields
uint32_t	crc	Field CRC.
char	name[PBL_BT_DEVICE_NAME_BUFFER_SIZE]	Remote device name.

◆ SprfPinnedAddress

struct SprfPinnedAddress

Pinned address field.

Data Fields
uint32_t	crc	Field CRC.
struct pbl_bt_addr	pinned_address	Pinned address of the device most recently paired.
uint8_t	rsvd[2]	Reserved.

◆ SprfGettingStarted

struct SprfGettingStarted

Onboarding (getting started) field.

Data Fields
uint32_t	crc	Field CRC.
bool	is_complete	Onboarding has been completed.
uint8_t	rsvd[3]	Reserved.

◆ SprfLocalName

struct SprfLocalName

Custom local device name field.

Data Fields
uint32_t	crc	Field CRC.
char	name[PBL_BT_DEVICE_NAME_BUFFER_SIZE]	Local device name, replacing the default "Pebble XXXX".

◆ SprfLocalIdentityAddress

struct SprfLocalIdentityAddress

Local identity address field.

Carved out of main_fw_scratch, so firmware that predates it neither validates it nor drops it when rewriting the entry. An invalid value only reads as absent.

Data Fields
struct pbl_bt_addr	address	Random static identity address of the watch, for controllers without one of their own.
uint32_t	crc	Field CRC.
uint8_t	rsvd[2]	Reserved.

◆ SharedPRFData

struct SharedPRFData

Legacy shared PRF storage contents.

Shared PRF storage entry.

Data Fields
BLEPairingData	ble_data	BLE pairing, must be adjacent to bt_classic_data.
SprfBlePairingData	ble_pairing_data	BLE pairing.
SprfBlePairingName	ble_pairing_name	BLE pairing device name.
BTClassicPairingData	bt_classic_data	BT Classic pairing.
SprfGettingStarted	getting_started	Onboarding state.
bool	getting_started_is_complete	Onboarding has been completed.
char	local_device_name[PBL_BT_DEVICE_NAME_BUFFER_SIZE]	Custom local device name, empty to use the default name.
SprfLocalIdentityAddress	local_identity_address	Local identity address.
SprfLocalName	local_name	Custom local device name.
SprfMagic	magic	Entry state.
struct SharedPRFData.main_fw_scratch	main_fw_scratch	Area reserved for the normal firmware to stash pairing related data.
SprfPinnedAddress	pinned_address	Pinned address.
struct pbl_bt_sm_key	root_keys[PBL_BT_SM_ROOT_KEY_TYPE_NUM]	BLE root keys (ER and IR).
SprfRootKeys	root_keys	BLE root keys.
uint8_t	rsvd[3]	Reserved.
uint32_t	version	Layout version, see SHARED_PRF_STORAGE_VERSION.
uint8_t	version	Layout version, currently 2.

◆ SharedPRFData.main_fw_scratch

struct SharedPRFData.main_fw_scratch

Area reserved for the normal firmware to stash pairing related data.

Data Fields
uint8_t	rsvd[32]	Reserved.

Macro Definition Documentation

◆ SPRF_MAX_NUM_PAGES_MULT

#define SPRF_MAX_NUM_PAGES_MULT ( num ) ((num) * 3 / 4)

Page index beyond which the region is compacted at boot.

Parameters

num	Number of pages in the region.

◆ SPRF_PAGE_IDX_INVALID

#define SPRF_PAGE_IDX_INVALID ((uint16_t)~0)

Page index meaning no valid entry has been found.

Enumeration Type Documentation

◆ SprfMagic

enum SprfMagic

Entry header magic.

Enumerator
SprfMagic_ValidEntry	Valid entry, "SPRF".
SprfMagic_UnpopulatedEntry	Erased entry, not written yet.
SprfMagic_InvalidatedEntry	Invalidated entry, superseded by a later one.

◆ SprfValidFields

enum SprfValidFields

Valid parts of SprfBlePairingData.

Enumerator
SprfValidFields_LocalEncryptionInfoValid	Local encryption info (l_ltk, l_rand, l_ediv).
SprfValidFields_RemoteEncryptionInfoValid	Remote encryption info (r_ltk, r_rand, r_ediv).
SprfValidFields_RemoteIdentityInfoValid	Remote identity info (irk, identity).
SprfValidFields_RemoteSigningInfoValid	Remote signing info (csrk).

Data Structures

Macros

Enumerations