MBoot Module API

Module implementing communication with the MCU Bootloader.

McuBoot Class

Module for communication with the bootloader.

class spsdk.mboot.mcuboot.McuBoot(device, cmd_exception=False)

Bases: object

Class for communication with the bootloader.

Initialize the McuBoot object.

Parameters

  • device (Interface) – The instance of communication interface class

  • cmd_exception (bool) – True to throw McuBootCommandError on any error; False to set status code only Note: some operation might raise McuBootCommandError is all cases

DEFAULT_MAX_PACKET_SIZE = 32
call(address, argument)

Fill MCU memory with specified pattern.

Parameters

  • address (int) – Call address (must be word aligned)

  • argument (int) – Function arguments address

Return type

bool

Returns

False in case of any problem; True otherwise

close()

Disconnect from the device.

Return type

None

configure_memory(address, mem_id)

Configure memory.

Parameters

  • address (int) – The address in memory where are locating configuration data

  • mem_id (int) – Memory ID

Return type

bool

Returns

False in case of any problem; True otherwise

efuse_program_once(index, value)

Write into MCU once program region (OCOTP).

Parameters

  • index (int) – Start index

  • value (int) – Int value (4 bytes long)

Return type

bool

Returns

False in case of any problem; True otherwise

efuse_read_once(index)

Read from MCU flash program once region.

Parameters

index (int) – Start index

Return type

Optional[int]

Returns

read value (32-bit int); None if operation failed

execute(address, argument, sp)

Execute program on a given address using the stack pointer.

Parameters

  • address (int) – Jump address (must be word aligned)

  • argument (int) – Function arguments address

  • sp (int) – Stack pointer address

Return type

bool

Returns

False in case of any problem; True otherwise

fill_memory(address, length, pattern=4294967295)

Fill MCU memory with specified pattern.

Parameters

  • address (int) – Start address (must be word aligned)

  • length (int) – Count of words (must be word aligned)

  • pattern (int) – Count of wrote bytes

Return type

bool

Returns

False in case of any problem; True otherwise

flash_erase_all(mem_id=0)

Erase complete flash memory without recovering flash security section.

Parameters

mem_id (int) – Memory ID

Return type

bool

Returns

False in case of any problem; True otherwise

flash_erase_all_unsecure()

Erase complete flash memory and recover flash security section.

Return type

bool

Returns

False in case of any problem; True otherwise

flash_erase_region(address, length, mem_id=0)

Erase specified range of flash.

Parameters

  • address (int) – Start address

  • length (int) – Count of bytes

  • mem_id (int) – Memory ID

Return type

bool

Returns

False in case of any problem; True otherwise

flash_program_once(index, data)

Write into MCU flash program once region (max 8 bytes).

Parameters

  • index (int) – Start index

  • data (bytes) – Input data aligned to 4 or 8 bytes

Return type

bool

Returns

False in case of any problem; True otherwise

Raises

SPSDKError – When invalid length of data. Must be aligned to 4 or 8 bytes

flash_read_once(index, count=4)

Read from MCU flash program once region (max 8 bytes).

Parameters

  • index (int) – Start index

  • count (int) – Count of bytes

Return type

Optional[bytes]

Returns

Data read; None in case of an failure

Raises

SPSDKError – When invalid count of bytes. Must be 4 or 8

flash_read_resource(address, length, option=1)

Read resource of flash module.

Parameters

  • address (int) – Start address

  • length (int) – Number of bytes

  • option (int) – Area to be read. 0 means Flash IFR, 1 means Flash Firmware ID

Raises

McuBootError – when the length is not aligned to 4 bytes

Return type

Optional[bytes]

Returns

Data from the resource; None in case of an failure

flash_security_disable(backdoor_key)

Disable flash security by using of backdoor key.

Parameters

backdoor_key (bytes) – The key value as array of 8 bytes

Return type

bool

Returns

False in case of any problem; True otherwise

Raises

McuBootError – If the backdoor_key is not 8 bytes long

fuse_program(address, data, mem_id=0)

Program fuse.

Parameters

  • address (int) – Start address

  • data (bytes) – List of bytes

  • mem_id (int) – Memory ID

Return type

bool

Returns

False in case of any problem; True otherwise

fuse_read(address, length, mem_id=0)

Read fuse.

Parameters

  • address (int) – Start address

  • length (int) – Count of bytes

  • mem_id (int) – Memory ID

Return type

Optional[bytes]

Returns

Data read from the fuse; None in case of a failure

generate_key_blob(dek_data, key_sel=0, count=72)

Generate Key Blob.

Parameters

  • dek_data (bytes) – Data Encryption Key as bytes

  • key_sel (int) – select the BKEK used to wrap the BK (default: OPTMK/FUSES)

  • count (int) – Key blob count (default: 72 - AES128bit)

Return type

Optional[bytes]

Returns

Key blob; None in case of an failure

get_memory_list()

Get list of embedded memories.

Return type

dict

Returns

dict, with the following keys: internal_flash (optional) - list , internal_ram (optional) - list, external_mems (optional) - list

Raises

McuBootCommandError – Error reading the memory list

get_property(prop_tag, index=0)

Get specified property value.

Parameters

  • prop_tag (PropertyTag) – Property TAG (see Properties Enum)

  • index (int) – External memory ID or internal memory region index (depends on property type)

Return type

Optional[List[int]]

Returns

list integers representing the property; None in case no response from device

get_property_list()

Get a list of available properties.

Return type

list

Returns

List of available properties.

Raises

McuBootCommandError – Failure to read properties list

property is_opened
Return type

bool

Returns

True if the device is open.

kp_enroll()

Key provisioning: Enroll Command (start PUF).

Return type

bool

Returns

False in case of any problem; True otherwise

kp_read_key_store()

Key provisioning: Read key data from key store area.

Return type

Optional[bytes]

kp_read_nonvolatile(mem_id=0)

Key provisioning: Load the key from a nonvolatile memory to bootloader.

Parameters

mem_id (int) – The memory ID (default: 0)

Return type

bool

Returns

False in case of any problem; True otherwise

kp_set_intrinsic_key(key_type, key_size)

Key provisioning: Generate Intrinsic Key.

Parameters

  • key_type (int) – Type of the key

  • key_size (int) – Size of the key

Return type

bool

Returns

False in case of any problem; True otherwise

kp_set_user_key(key_type, key_data)

Key provisioning: Send the user key specified by <key_type> to bootloader.

Parameters

  • key_type (KeyProvUserKeyType) – type of the user key, see enumeration for details

  • key_data (bytes) – binary content of the user key

Return type

bool

Returns

False in case of any problem; True otherwise

kp_write_key_store(key_data)

Key provisioning: Write key data into key store area.

Parameters

key_data (bytes) – key store binary content to be written to processor

Return type

bool

Returns

result of the operation; True means success

kp_write_nonvolatile(mem_id=0)

Key provisioning: Write the key to a nonvolatile memory.

Parameters

mem_id (int) – The memory ID (default: 0)

Return type

bool

Returns

False in case of any problem; True otherwise

load_image(data)

Load a boot image to the device.

Parameters

data (bytes) – boot image

Return type

bool

Returns

False in case of any problem; True otherwise

open()

Connect to the device.

Return type

None

read_memory(address, length, mem_id=0)

Read data from MCU memory.

Parameters

  • address (int) – Start address

  • length (int) – Count of bytes

  • mem_id (int) – Memory ID

Return type

Optional[bytes]

Returns

Data read from the memory; None in case of a failure

receive_sb_file(data)

Receive SB file.

Parameters

data – SB file data

Return type

bool

Returns

False in case of any problem; True otherwise

reliable_update(address)

Reliable Update.

Parameters

address (int) – Address where new the firmware is stored

Return type

bool

Returns

False in case of any problem; True otherwise

reset(timeout=2000, reopen=True)

Reset MCU and reconnect if enabled.

Parameters

  • timeout (int) – The maximal waiting time in [ms] for reopen connection

  • reopen (bool) – True for reopen connection after HW reset else False

Return type

bool

Returns

False in case of any problem; True otherwise

Raises
set_property(prop_tag, value)

Set value of specified property.

Parameters

  • prop_tag – Property TAG (see Property enumerator)

  • value – The value of selected property

Return type

bool

Returns

False in case of any problem; True otherwise

property status_code
Return type

StatusCode

Returns

status code of the last operation.

tp_hsm_enc_blk(mfg_cust_mk_sk_0_blob_input_addr, mfg_cust_mk_sk_0_blob_input_size, kek_id, sb3_header_input_addr, sb3_header_input_size, block_num, block_data_addr, block_data_size)

Trust provisioning: Encrypt the given SB3 data block.

Parameters

  • mfg_cust_mk_sk_0_blob_input_addr (int) – The input buffer address where the CKDF Master Key Blob locates at

  • mfg_cust_mk_sk_0_blob_input_size (int) – The byte count of the CKDF Master Key Blob

  • kek_id (int) – The CKDF Master Key Encryption Key ID (0x10: NXP_CUST_KEK_INT_SK, 0x11: NXP_CUST_KEK_EXT_SK)

  • sb3_header_input_addr (int) – The input buffer address, where the SB3 Header(block0) locates at

  • sb3_header_input_size (int) – The byte count of the SB3 Header

  • block_num (int) – The index of the block. Due to SB3 Header(block 0) is always unencrypted, the index starts from block1

  • block_data_addr (int) – The buffer address where the SB3 data block locates at

  • block_data_size (int) – The byte count of the SB3 data block

Return type

bool

Returns

False in case of any problem; True otherwise

tp_hsm_enc_sign(key_blob_input_addr, key_blob_input_size, block_data_input_addr, block_data_input_size, signature_output_addr, signature_output_size)

Signs the given data.

Parameters

  • key_blob_input_addr (int) – The input buffer address where signing key blob locates at

  • key_blob_input_size (int) – The byte count of the signing key blob

  • block_data_input_addr (int) – The input buffer address where the data locates at

  • block_data_input_size (int) – The byte count of the data

  • signature_output_addr (int) – The output buffer address where ROM writes the signature to

  • signature_output_size (int) – The output buffer size in byte

Return type

Optional[int]

Returns

Return signature size; None in case of an failure

tp_hsm_gen_key(key_type, reserved, key_blob_output_addr, key_blob_output_size, ecdsa_puk_output_addr, ecdsa_puk_output_size)

Trust provisioning: OEM generate common keys.

Parameters

  • key_type (int) – Key to generate (MFW_ISK, MFW_ENCK, GEN_SIGNK, GET_CUST_MK_SK)

  • reserved (int) – Reserved, must be zero

  • key_blob_output_addr (int) – The output buffer address where ROM writes the key blob to

  • key_blob_output_size (int) – The output buffer size in byte

  • ecdsa_puk_output_addr (int) – The output buffer address where ROM writes the public key to

  • ecdsa_puk_output_size (int) – The output buffer size in byte

Return type

Optional[List[Any]]

Returns

Return byte count of the key blob + byte count of the public key from the device; None in case of an failure

tp_hsm_store_key(key_type, key_property, key_input_addr, key_input_size, key_blob_output_addr, key_blob_output_size)

Trust provisioning: OEM generate common keys.

Parameters

  • key_type (int) – Key to generate (CKDFK, HKDFK, HMACK, CMACK, AESK, KUOK)

  • key_property (int) – Bit 0: Key Size, 0 for 128bit, 1 for 256bit. Bits 30-31: set key protection CSS mode.

  • key_input_addr (int) – The input buffer address where the key locates at

  • key_input_size (int) – The byte count of the key

  • key_blob_output_addr (int) – The output buffer address where ROM writes the key blob to

  • key_blob_output_size (int) – The output buffer size in byte

Return type

Optional[List[Any]]

Returns

Return header of the key blob + byte count of the key blob (header is not included) from the device; None in case of an failure

tp_oem_gen_master_share(oem_share_input_addr, oem_share_input_size, oem_enc_share_output_addr, oem_enc_share_output_size, oem_enc_master_share_output_addr, oem_enc_master_share_output_size, oem_cust_cert_puk_output_addr, oem_cust_cert_puk_output_size)

Takes the entropy seed provided by the OEM as input.

Parameters

  • oem_share_input_addr (int) – The input buffer address where the OEM Share(entropy seed) locates at

  • oem_share_input_size (int) – The byte count of the OEM Share

  • oem_enc_share_output_addr (int) – The output buffer address where ROM writes the Encrypted OEM Share to

  • oem_enc_share_output_size (int) – The output buffer size in byte

  • oem_enc_master_share_output_addr (int) – The output buffer address where ROM writes the Encrypted OEM Master Share to

  • oem_enc_master_share_output_size (int) – The output buffer size in byte.

  • oem_cust_cert_puk_output_addr (int) – The output buffer address where ROM writes the OEM Customer Certificate Public Key to

  • oem_cust_cert_puk_output_size (int) – The output buffer size in byte

Return type

Optional[List[int]]

Returns

Sizes of two encrypted blobs(the Encrypted OEM Share and the Encrypted OEM Master Share) and a public key(the OEM Customer Certificate Public Key).

tp_oem_get_cust_cert_dice_puk(oem_rkt_input_addr, oem_rkth_input_size, oem_cust_cert_dice_puk_output_addr, oem_cust_cert_dice_puk_output_size)

Creates the initial trust provisioning keys.

Parameters

  • oem_rkt_input_addr (int) – The input buffer address where the OEM RKTH locates at

  • oem_rkth_input_size (int) – The byte count of the OEM RKTH

  • oem_cust_cert_dice_puk_output_addr (int) – The output buffer address where ROM writes the OEM Customer Certificate Public Key for DICE to

  • oem_cust_cert_dice_puk_output_size (int) – The output buffer size in byte

Return type

Optional[int]

Returns

The byte count of the OEM Customer Certificate Public Key for DICE

tp_oem_set_master_share(oem_share_input_addr, oem_share_input_size, oem_enc_master_share_input_addr, oem_enc_master_share_input_size)

Takes the entropy seed and the Encrypted OEM Master Share.

Parameters

  • oem_share_input_addr (int) – The input buffer address where the OEM Share(entropy seed) locates at

  • oem_share_input_size (int) – The byte count of the OEM Share

  • oem_enc_master_share_input_addr (int) – The input buffer address where the Encrypted OEM Master Share locates at

  • oem_enc_master_share_input_size (int) – The byte count of the Encrypted OEM Master Share

Return type

bool

Returns

False in case of any problem; True otherwise

write_memory(address, data, mem_id=0)

Write data into MCU memory.

Parameters

  • address (int) – Start address

  • data (bytes) – List of bytes

  • mem_id (int) – Memory ID, see ExtMemId; additionally use 0 for internal memory

Return type

bool

Returns

False in case of any problem; True otherwise

MBoot Commands

Commands and responses used by MBOOT module.

class spsdk.mboot.commands.CmdHeader(tag, flags, reserved, params_count)

Bases: object

McuBoot command/response header.

Initialize the Command Header.

Parameters

  • tag (int) – Tag indicating the command, see: CommandTag class

  • flags (int) – Flags for the command

  • reserved (int) – Reserved?

  • params_count (int) – Number of parameter for the command

SIZE = 4
classmethod from_bytes(data, offset=0)

Deserialize header from bytes.

Parameters

  • data (bytes) – Input data in bytes

  • offset (int) – The offset of input data

Return type

CmdHeader

Returns

De-serialized CmdHeader object

Raises

McuBootError – Invalid data format

to_bytes()

Serialize header into bytes.

Return type

bytes

class spsdk.mboot.commands.CmdPacket(tag, flags, *args, data=None)

Bases: object

McuBoot command packet format class.

Initialize the Command Packet object.

Parameters

  • tag (int) – Tag identifying the command

  • flags (int) – Flags used by the command

  • args (int) – Arguments used by the command

  • data (Optional[bytes]) – Additional data, defaults to None

EMPTY_VALUE = 0
SIZE = 32
info()

Get object info.

Return type

str

to_bytes(padding=True)

Serialize CmdPacket into bytes.

Parameters

padding (bool) – If True, add padding to specific size

Return type

bytes

Returns

Serialized object into bytes

class spsdk.mboot.commands.CmdResponse(header, raw_data)

Bases: object

McuBoot response base format class.

Initialize the Command Response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.CommandTag

Bases: spsdk.utils.easy_enum.Enum

McuBoot Commands.

CALL = 10
CONFIGURE_CAN = 195
CONFIGURE_I2C = 193
CONFIGURE_MEMORY = 17
CONFIGURE_SPI = 194
EXECUTE = 9
FILL_MEMORY = 5
FLASH_ERASE_ALL = 1
FLASH_ERASE_ALL_UNSECURE = 13
FLASH_ERASE_REGION = 2
FLASH_PROGRAM_ONCE = 14
FLASH_READ_ONCE = 15
FLASH_READ_RESOURCE = 16
FLASH_SECURITY_DISABLE = 6
FUSE_PROGRAM = 20
FUSE_READ = 23
GENERATE_KEY_BLOB = 19
GET_PROPERTY = 7
KEY_PROVISIONING = 21
NO_COMMAND = 0
READ_MEMORY = 3
RECEIVE_SB_FILE = 8
RELIABLE_UPDATE = 18
RESET = 11
SET_PROPERTY = 12
TRUST_PROVISIONING = 22
WRITE_MEMORY = 4
class spsdk.mboot.commands.FlashReadOnceResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot flash read once response format class.

Initialize the Flash-Read-Once response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.FlashReadResourceResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot flash read resource response format class.

Initialize the Flash-Read-Resource response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.GenerateKeyBlobSelect

Bases: spsdk.utils.easy_enum.Enum

Key selector for the generate-key-blob function.

For devices with SNVS, valid options of [key_sel] are 0, 1 or OTPMK: OTPMK from FUSE or OTP(default), 2 or ZMK: ZMK from SNVS, 3 or CMK: CMK from SNVS, For devices without SNVS, this option will be ignored.

CMK = 3
OPTMK = 0
ZMK = 2
class spsdk.mboot.commands.GenericResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot generic response format class.

Initialize the Generic response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.GetPropertyResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot get property response format class.

Initialize the Get-Property response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.KeyProvOperation

Bases: spsdk.utils.easy_enum.Enum

Type of key provisioning operation.

ENROLL = 0
READ_KEY_STORE = 6
READ_NON_VOLATILE = 4
SET_INTRINSIC_KEY = 2
SET_USER_KEY = 1
WRITE_KEY_STORE = 5
WRITE_NON_VOLATILE = 3
class spsdk.mboot.commands.KeyProvUserKeyType

Bases: spsdk.utils.easy_enum.Enum

Enumeration of supported user keys in PUF. Keys are SoC specific, not all will be supported for the processor.

OTFADKEK = 2
PRINCE_REGION_0 = 7
PRINCE_REGION_1 = 8
PRINCE_REGION_2 = 9
SBKEK = 3
UDS = 12
USERKEK = 11
class spsdk.mboot.commands.KeyProvisioningResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot Key Provisioning response format class.

Initialize the Key-Provisioning response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.NoResponse(cmd_tag)

Bases: spsdk.mboot.commands.CmdResponse

Special internal case when no response is provided by the target.

Create a NoResponse to an command that was issued, indicated by its tag.

Parameters

cmd_tag (int) – Tag of the command that preceded the no-response from target

class spsdk.mboot.commands.ReadMemoryResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot read memory response format class.

Initialize the Read-Memory response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

class spsdk.mboot.commands.ResponseTag

Bases: spsdk.utils.easy_enum.Enum

McuBoot Responses to Commands.

FLASH_READ_ONCE = 175
FLASH_READ_RESOURCE = 176
GENERIC = 160
GET_PROPERTY = 167
KEY_BLOB_RESPONSE = 179
KEY_PROVISIONING_RESPONSE = 181
READ_MEMORY = 163
TRUST_PROVISIONING_RESPONSE = 182
class spsdk.mboot.commands.TrustProvKeyType

Bases: spsdk.utils.easy_enum.Enum

Type of key type definition.

AESK = 5
CKDFK = 1
CMACK = 4
HKDFK = 2
HMACK = 3
KUOK = 6
class spsdk.mboot.commands.TrustProvOemKeyType

Bases: spsdk.utils.easy_enum.Enum

Type of oem key type definition.

GENSIGNK = 23100
GETCUSTMKSK = 15450
MFWENCK = 42435
MFWISK = 50085
class spsdk.mboot.commands.TrustProvOperation

Bases: spsdk.utils.easy_enum.Enum

Type of trust provisioning operation.

HSM_ENC_BLOCK = 5
HSM_ENC_SIGN = 6
HSM_GEN_KEY = 3
HSM_STORE_KEY = 4
OEM_GEN_MASTER_SHARE = 0
OEM_GET_CUST_CERT_DICE_PUK = 2
OEM_SET_MASTER_SHARE = 1
class spsdk.mboot.commands.TrustProvWrappingKeyType

Bases: spsdk.utils.easy_enum.Enum

Type of wrapping key type definition.

EXT_SK = 17
INT_SK = 16
class spsdk.mboot.commands.TrustProvisioningResponse(header, raw_data)

Bases: spsdk.mboot.commands.CmdResponse

McuBoot Trust Provisioning response format class.

Initialize the Trust-Provisioning response object.

Parameters

  • header (CmdHeader) – Header for the response

  • raw_data (bytes) – Response data

info()

Get object info.

Return type

str

spsdk.mboot.commands.parse_cmd_response(data, offset=0)

Parse command response.

Parameters

  • data (bytes) – Input data in bytes

  • offset (int) – The offset of input data

Return type

CmdResponse

Returns

De-serialized object from data

MBoot Properties

Helper module for more human-friendly interpretation of the target device properties.

class spsdk.mboot.properties.AvailableCommandsValue(tag, raw_values)

Bases: spsdk.mboot.properties.PropertyValueBase

Available commands property.

Initialize the AvailableCommands-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

property tags

List of tags representing Available commands.

Return type

List[str]

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.AvailablePeripheralsValue(tag, raw_values)

Bases: spsdk.mboot.properties.PropertyValueBase

Available Peripherals property.

Initialize the AvailablePeripherals-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

to_int()

Get the raw integer portion of the property.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.BoolValue(tag, raw_values, true_values=(1), true_string='YES', false_values=(0), false_string='NO')

Bases: spsdk.mboot.properties.PropertyValueBase

Boolean-based value property.

Initialize the Boolean-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

  • true_values (Tuple) – Values representing ‘True’, defaults to (1,)

  • true_string (str) – String representing ‘True, defaults to ‘YES’

  • false_values (Tuple) – Values representing ‘False’, defaults to (0,)

  • false_string (str) – String representing ‘False, defaults to ‘NO’

to_int()

Get the raw integer portion of the property.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.DeviceUidValue(tag, raw_values)

Bases: spsdk.mboot.properties.PropertyValueBase

Device UID value property.

Initialize the Version-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

to_int()

Get the raw integer portion of the property.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.EnumValue(tag, raw_values, enum, na_msg='Unknown Item')

Bases: spsdk.mboot.properties.PropertyValueBase

Enumeration value property.

Initialize the enumeration-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

  • enum (Type[Enum]) – Enumeration to pick from

  • na_msg (str) – Message to display if an item is not found in the enum

enum
to_int()

Get the raw integer portion of the property.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.ExternalMemoryAttributesValue(tag, raw_values, mem_id=0)

Bases: spsdk.mboot.properties.PropertyValueBase

Attributes for external memories.

Initialize the ExternalMemoryAttributes-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

  • mem_id (int) – ID of the external memory

block_size
mem_id
page_size
sector_size
start_address
to_str()

Get stringified property representation.

Return type

str

total_size
value
class spsdk.mboot.properties.FlashReadMargin

Bases: spsdk.utils.easy_enum.Enum

Scopes for flash read.

FACTORY = 2
NORMAL = 0
USER = 1
class spsdk.mboot.properties.IntValue(tag, raw_values, str_format='dec')

Bases: spsdk.mboot.properties.PropertyValueBase

Integer-based value property.

Initialize the integer-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

  • str_format (str) – Format to display the value (‘dec’, ‘hex’, ‘size’)

to_int()

Get the raw integer property representation.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.IrqNotifierPinValue(tag, raw_values)

Bases: spsdk.mboot.properties.PropertyValueBase

IRQ notifier pin property.

Initialize the IrqNotifierPin-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

property enabled

Indicates whether IRQ reporting is enabled.

Return type

bool

property pin

Number of the pin used for reporting IRQ.

Return type

int

property port

Number of the port used for reporting IRQ.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
class spsdk.mboot.properties.PeripheryTag

Bases: spsdk.utils.easy_enum.Enum

Tags representing peripherals.

CAN = 8
I2C_SLAVE = 2
SPI_SLAVE = 4
UART = 1
USB_CDC = 32
USB_DFU = 64
USB_HID = 16
class spsdk.mboot.properties.PfrKeystoreUpdateOpt

Bases: spsdk.utils.easy_enum.Enum

Options for PFR updating.

KEY_PROVISIONING = 0
WRITE_MEMORY = 1
class spsdk.mboot.properties.PropertyTag

Bases: spsdk.utils.easy_enum.Enum

McuBoot Properties.

AVAILABLE_COMMANDS = 7
AVAILABLE_PERIPHERALS = 2
CRC_CHECK_STATUS = 8
CURRENT_VERSION = 1
EXTERNAL_MEMORY_ATTRIBUTES = 25
FLASH_ACCESS_SEGMENT_COUNT = 21
FLASH_ACCESS_SEGMENT_SIZE = 20
FLASH_BLOCK_COUNT = 6
FLASH_FAC_SUPPORT = 19
FLASH_PAGE_SIZE = 27
FLASH_READ_MARGIN = 22
FLASH_SECTOR_SIZE = 5
FLASH_SECURITY_STATE = 17
FLASH_SIZE = 4
FLASH_START_ADDRESS = 3
IRQ_NOTIFIER_PIN = 28
LAST_ERROR = 9
MAX_PACKET_SIZE = 11
PFR_KEYSTORE_UPDATE_OPT = 29
QSPI_INIT_STATUS = 23
RAM_SIZE = 15
RAM_START_ADDRESS = 14
RELIABLE_UPDATE_STATUS = 26
RESERVED_REGIONS = 12
SYSTEM_DEVICE_IDENT = 16
TARGET_VERSION = 24
UNIQUE_DEVICE_IDENT = 18
VALIDATE_REGIONS = 13
VERIFY_WRITES = 10
class spsdk.mboot.properties.PropertyValueBase(tag, name=None, desc=None)

Bases: object

Base class for property value.

Initialize the base of property.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • name (Optional[str]) – Optional name for the property

  • desc (Optional[str]) – Optional description for the property

desc
name
tag
to_str()

Stringified representation of a property.

Derived classes should implement this function.

Raises

NotImplementedError – Derived class didn’t provide implementation

Return type

str

Returns

String representation

class spsdk.mboot.properties.ReservedRegionsValue(tag, raw_values)

Bases: spsdk.mboot.properties.PropertyValueBase

Reserver Regions property.

Initialize the ReserverRegion-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

regions
to_str()

Get stringified property representation.

Return type

str

class spsdk.mboot.properties.Version(*args, **kwargs)

Bases: object

McuBoot current and target version type.

Initialize the Version object.

Raises

McuBootError – Argument passed the not str not int

from_int(value)

Parse version data from raw int value.

Parameters

value (int) – Raw integer input

Return type

None

from_str(value)

Parse version data from string value.

Parameters

value (str) – String representation input

Return type

None

to_int(no_mark=False)

Get version value in raw integer format.

Parameters

no_mark (bool) – If True, return value without mark

Return type

int

Returns

Integer representation

to_str(no_mark=False)

Get version value in readable string format.

Parameters

no_mark (bool) – If True, return value without mark

Return type

str

Returns

String representation

class spsdk.mboot.properties.VersionValue(tag, raw_values)

Bases: spsdk.mboot.properties.PropertyValueBase

Version property class.

Initialize the Version-based property object.

Parameters

  • tag (int) – Property tag, see: PropertyTag

  • raw_values (List[int]) – List of integers representing the property

to_int()

Get the raw integer portion of the property.

Return type

int

to_str()

Get stringified property representation.

Return type

str

value
spsdk.mboot.properties.parse_property_value(property_tag, raw_values, ext_mem_id=None)

Parse the property value received from the device.

Parameters

  • property_tag (int) – Tag representing the property

  • raw_values (list) – Data received from the device

  • ext_mem_id (Optional[int]) – ID of the external memory used to read the property, defaults to None

Return type

Optional[PropertyValueBase]

Returns

Object representing the property

spsdk.mboot.properties.size_fmt(value, kibibyte=True)

Convert size value into string format.

Parameters

  • value (Union[int, float]) – The raw value

  • kibibyte (bool) – True if 1024 Bytes represent 1kB or False if 1000 Bytes represent 1kB

Return type

str

Returns

Stringified value

External Memories

Various types of memory identifiers used in the MBoot module.

class spsdk.mboot.memories.ExtMemId

Bases: spsdk.utils.easy_enum.Enum

McuBoot External Memory Property Tags.

FLASH_EXEC_ONLY = 16
FLEX_SPI_NOR = 9
I2C_NOR_EEPROM = 273
IFR0 = 4
MMC_CARD = 289
QUAD_SPI0 = 1
SD_CARD = 288
SEMC_NAND = 256
SEMC_NOR = 8
SPIFI_NOR = 10
SPI_NAND = 257
SPI_NOR_EEPROM = 272
class spsdk.mboot.memories.ExtMemPropTags

Bases: spsdk.utils.easy_enum.Enum

McuBoot External Memory Property Tags.

BLOCK_SIZE = 16
INIT_STATUS = 0
PAGE_SIZE = 4
SECTOR_SIZE = 8
SIZE_IN_KBYTES = 2
START_ADDRESS = 1
class spsdk.mboot.memories.ExtMemRegion(mem_id, raw_values=None)

Bases: spsdk.mboot.memories.MemoryRegion

External memory regions.

Initialize the external memory region object.

Parameters

  • mem_id (int) – ID of the external memory

  • raw_values (Optional[List[int]]) – List of integers representing the property

property name

Get the name of external memory for given memory ID.

Return type

str

class spsdk.mboot.memories.FlashRegion(index, start, size, sector_size)

Bases: spsdk.mboot.memories.MemoryRegion

Flash memory regions.

Initialize the Flash memory region object.

Parameters

  • index (int) – number of region

  • start (int) – start address of region

  • size (int) – size of region

  • sector_size (int) – size of sector

class spsdk.mboot.memories.MemId

Bases: spsdk.mboot.memories.ExtMemId

McuBoot Internal/External Memory Property Tags.

INTERNAL_MEMORY = 0
class spsdk.mboot.memories.MemoryRegion(start, end)

Bases: object

Base class for memory regions.

Initialize the memory region object.

Parameters

  • start (int) – start address of region

  • end (int) – end address of region

class spsdk.mboot.memories.RamRegion(index, start, size)

Bases: spsdk.mboot.memories.MemoryRegion

RAM memory regions.

Initialize the RAM memory region object.

Parameters

  • index (int) – number of region

  • start (int) – start address of region

  • size (int) – size of region

MBoot ErrorCodes

Status and error codes used by the MBoot protocol.

class spsdk.mboot.error_codes.StatusCode

Bases: spsdk.utils.easy_enum.Enum

McuBoot status codes.

ABORT_DATA_PHASE = 10002
APP_CRC_CHECK_FAILED = 10401
APP_CRC_CHECK_INACTIVE = 10402
APP_CRC_CHECK_INVALID = 10403
APP_CRC_CHECK_OUT_OF_RANGE = 10404
APP_CRC_CHECK_PASSED = 10400
FAIL = 1
FLASH_ACCESS_ERROR = 103
FLASH_ADDRESS_ERROR = 102
FLASH_ALIGNMENT_ERROR = 101
FLASH_BLANK_IFR_PAGE_DATA = 133
FLASH_CMPA_CFG_DIRECT_ERASE_NOT_ALLOWED = 140
FLASH_COMMAND_FAILURE = 105
FLASH_COMMAND_NOT_SUPPORTED = 111
FLASH_ENCRYPTED_REGIONS_ERASE_NOT_DONE_AT_ONCE = 134
FLASH_EXEC_IN_RAM_NOT_READY = 109
FLASH_HASH_CHECK_ERROR = 136
FLASH_NMPA_UPDATE_NOT_ALLOWED = 139
FLASH_OUT_OF_DATE_CFPA_PAGE = 132
FLASH_PFR_BANK_IS_LOCKED = 141
FLASH_PFR_REGION_WRITE_BROKEN = 138
FLASH_PROGRAM_VERIFICATION_NOT_ALLOWED = 135
FLASH_PROTECTION_VIOLATION = 104
FLASH_REGION_EXECUTE_ONLY = 108
FLASH_SEALED_PFR_REGION = 137
FLASH_SIZE_ERROR = 100
FLASH_UNKNOWN_PROPERTY = 106
FLEXSPINAND_ECC_CHECK_FAIL = 20002
FLEXSPINAND_ERASE_BLOCK_FAIL = 20005
FLEXSPINAND_NOT_FOUND = 20011
FLEXSPINAND_PAGE_EXECUTE_FAIL = 20004
FLEXSPINAND_PAGE_LOAD_FAIL = 20003
FLEXSPINAND_READ_CACHE_FAIL = 20001
FLEXSPINAND_READ_PAGE_FAIL = 20000
FLEXSPINAND_WAIT_TIMEOUT = 20006
FLEXSPINAND_WRITEALIGNMENTERROR = 20010
FLEXSPINOR_COMMANDFAILURE = 20106
FLEXSPINOR_DTR_READ_DUMMYPROBEFAILED = 20110
FLEXSPINOR_ERASE_ALL_FAIL = 20102
FLEXSPINOR_ERASE_SECTOR_FAIL = 20101
FLEXSPINOR_FLASH_NOTFOUND = 20109
FLEXSPINOR_NOT_SUPPORTED = 20104
FLEXSPINOR_PROGRAM_FAIL = 20100
FLEXSPINOR_SFDP_NOTFOUND = 20107
FLEXSPINOR_UNSUPPORTED_SFDP_VERSION = 20108
FLEXSPINOR_WAIT_TIMEOUT = 20103
FLEXSPINOR_WRITE_ALIGNMENT_ERROR = 20105
FLEXSPI_DEVICE_TIMEOUT = 70002
FLEXSPI_INVALID_SEQUENCE = 70001
FLEXSPI_SEQUENCE_EXECUTION_TIMEOUT = 70000
FlexSPINAND_DBBT_UPDATE_FAIL = 20009
FlexSPINAND_FCB_UPDATE_FAIL = 20008
FlexSPINAND_NOT_SUPPORTED = 20007
I2C_ARBITRATION_LOST = 202
I2C_SLAVE_RX_OVERRUN = 201
I2C_SLAVE_TX_UNDERRUN = 200
INVALID_ARGUMENT = 4
INVALID_PROPERTY_VALUE = 10302
MEMORY_ADDRESS_ERROR = 10209
MEMORY_ALIGNMENT_ERROR = 10206
MEMORY_APP_OVERLAP_WITH_EXECUTE_ONLY_REGION = 10204
MEMORY_BLANK_CHECK_FAILED = 10210
MEMORY_BLANK_PAGE_READ_DISALLOWED = 10211
MEMORY_CUMULATIVE_WRITE = 10203
MEMORY_NOT_CONFIGURED = 10205
MEMORY_PFR_SPEC_REGION_WRITE_BROKEN = 10213
MEMORY_PROTECTED_PAGE_READ_DISALLOWED = 10212
MEMORY_RANGE_INVALID = 10200
MEMORY_READ_FAILED = 10201
MEMORY_UNSUPPORTED_COMMAND = 10214
MEMORY_VERIFY_FAILED = 10207
MEMORY_WRITE_FAILED = 10202
MEMORY_WRITE_PROTECTED = 10208
NO_RESPONSE = 10004
NO_RESPONSE_EXPECTED = 10005
NO_TRANSFER_IN_PROGRESS = 6
OCOTP_PROGRAM_FAILURE = 20201
OCOTP_READ_FAILURE = 20200
OCOTP_RELOAD_FAILURE = 20202
OCOTP_WAIT_TIMEOUT = 20203
OTFAD_INVALID_KEY = 502
OTFAD_INVALID_KEY_BLOB = 503
OTFAD_LOGICALLY_DISABLED = 501
OTFAD_SECURITY_VIOLATION = 500
OTP_CRC_CHECK_PASS = 52808
OTP_CRC_FAIL = 52803
OTP_ECC_CRC_FAIL = 52805
OTP_ERROR = 52804
OTP_INVALID_ADDRESS = 52801
OTP_LOCKED = 52806
OTP_PROGRAM_FAIL = 52802
OTP_TIMEOUT = 52807
OUT_OF_RANGE = 3
PACKETIZER_INVALID_CRC = 10502
PACKETIZER_INVALID_PACKET_TYPE = 10501
PACKETIZER_NO_COMMAND_RESPONSE = 10503
PACKETIZER_NO_PING_RESPONSE = 10500
PING_ERROR = 10003
QSPI_COMMAND_NOT_SUPPORTED = 406
QSPI_COMMAND_TIMEOUT = 407
QSPI_FLASH_ADDRESS_ERROR = 402
QSPI_FLASH_ALIGNMENT_ERROR = 401
QSPI_FLASH_COMMAND_FAILURE = 403
QSPI_FLASH_SIZE_ERROR = 400
QSPI_FLASH_UNKNOWN_PROPERTY = 404
QSPI_NOT_CONFIGURED = 405
QSPI_WRITE_FAILURE = 408
READ_ONLY = 2
READ_ONLY_PROPERTY = 10301
RELIABLE_UPDATE_BACKUPAPPLICATIONINVALID = 10603
RELIABLE_UPDATE_BACKUPBOOTLOADERNOTREADY = 10606
RELIABLE_UPDATE_FAIL = 10601
RELIABLE_UPDATE_INACIVE = 10602
RELIABLE_UPDATE_STILLINMAINAPPLICATION = 10604
RELIABLE_UPDATE_SUCCESS = 10600
RELIABLE_UPDATE_SWAPINDICATORADDRESSINVALID = 10607
RELIABLE_UPDATE_SWAPSYSTEMNOTAVAILABLE = 10608
RELIABLE_UPDATE_SWAPSYSTEMNOTREADY = 10605
RELIABLE_UPDATE_SWAPTEST = 10609
ROMLDR_CALL_FAILED = 10111
ROMLDR_CHECKSUM = 10105
ROMLDR_CRC32_ERROR = 10106
ROMLDR_DATA_UNDERRUN = 10109
ROMLDR_EOF_REACHED = 10104
ROMLDR_ID_NOT_FOUND = 10108
ROMLDR_INVALID_SECTION_MAC_COUNT = 10116
ROMLDR_JUMP_RETURNED = 10110
ROMLDR_KEY_NOT_FOUND = 10112
ROMLDR_RESET_RETURNED = 10114
ROMLDR_ROLLBACK_BLOCKED = 10115
ROMLDR_SECTION_LENGTH = 10102
ROMLDR_SECTION_OVERRUN = 10100
ROMLDR_SECURE_ONLY = 10113
ROMLDR_SIGNATURE = 10101
ROMLDR_UNENCRYPTED_ONLY = 10103
ROMLDR_UNEXPECTED_COMMAND = 10117
ROMLDR_UNKNOWN_COMMAND = 10107
SECURITY_VIOLATION = 10001
SEMCNAND_CANNOT_ENABLE_DEVICE_ECC = 21206
SEMCNAND_DEVICE_TIMEOUT = 21200
SEMCNAND_DISALLOW_OVERWRITE_BCB = 21219
SEMCNAND_DISORDERED_IMAGE_COPIES = 21222
SEMCNAND_ECC_CHECK_FAIL = 21204
SEMCNAND_ERASE_VERIFY_FAILURE = 21209
SEMCNAND_FAIL_TO_UPDATE_DBBT = 21218
SEMCNAND_FAIL_TO_UPDATE_FCB = 21217
SEMCNAND_INVALID_CFG_TAG = 21216
SEMCNAND_INVALID_MEMORY_ADDRESS = 21201
SEMCNAND_INVALID_ONFI_PARAMETER = 21205
SEMCNAND_INVALID_READBACK_BUFFER = 21210
SEMCNAND_MORE_THAN_MAX_IMAGE_COPY = 21221
SEMCNAND_MORE_THAN_ONE_PAGE_SIZE = 21203
SEMCNAND_NOT_EQUAL_TO_ONE_PAGE_SIZE = 21202
SEMCNAND_ONLY_SUPPORT_ONFI_DEVICE = 21220
SEMCNAND_PROGRAM_VERIFY_FAILURE = 21208
SEMCNAND_SWITCH_TIMING_MODE_FAILURE = 21207
SEMCNOR_ADDRESS_ALIGNMENT_ERROR = 21103
SEMCNOR_BLOCK_ERASE_COMMAND_FAILURE = 21107
SEMCNOR_BUFFER_PROGRAM_COMMAND_FAILURE = 21108
SEMCNOR_COMMAND_ERROR_NO_INFO_AVAILABLE = 21106
SEMCNOR_COMMAND_ERROR_NO_OP_TO_SUSPEND = 21105
SEMCNOR_DEVICE_TIMEOUT = 21100
SEMCNOR_ERASE_VERIFY_FAILURE = 21110
SEMCNOR_INVALID_CFG_TAG = 21116
SEMCNOR_INVALID_CFI_SIGNATURE = 21104
SEMCNOR_INVALID_MEMORY_ADDRESS = 21101
SEMCNOR_PROGRAM_VERIFY_FAILURE = 21109
SEMCNOR_UNMATCHED_COMMAND_SET = 21102
SERIAL_NOR_EEPROM_ADDRESS_INVALID = 10700
SERIAL_NOR_EEPROM_COMMAND_INVALID = 10704
SERIAL_NOR_EEPROM_SIZE_INVALID = 10703
SERIAL_NOR_EEPROM_TRANSFER_ERROR = 10701
SERIAL_NOR_EEPROM_TYPE_INVALID = 10702
SPIFINOR_COMMAND_FAILURE = 22006
SPIFINOR_ERASE_ALL_FAIL = 22002
SPIFINOR_ERASE_SECTORFAIL = 22001
SPIFINOR_NOT_SUPPORTED = 22004
SPIFINOR_PROGRAM_FAIL = 22000
SPIFINOR_SFDP_NOT_FOUND = 22007
SPIFINOR_WAIT_TIMEOUT = 22003
SPIFINOR_WRITE_ALIGNMENTERROR = 22005
SPI_SLAVE_RX_OVERRUN = 301
SPI_SLAVE_TX_UNDERRUN = 300
SUCCESS = 0
TIMEOUT = 5
UNKNOWN_COMMAND = 10000
UNKNOWN_PROPERTY = 10300
UNSUPPORTED_COMMAND = 10006

MBoot Exceptions

Exceptions used in the MBoot module.

exception spsdk.mboot.exceptions.McuBootCommandError(cmd, value)

Bases: spsdk.mboot.exceptions.McuBootError

MBoot Module: Command Exception.

Initialize the Command Error exception.

Parameters

  • cmd (str) – Name of the command causing the exception

  • value (int) – Response value causing the exception

fmt = 'MBoot: {cmd_name} interrupted -> {description}'
exception spsdk.mboot.exceptions.McuBootConnectionError(desc=None)

Bases: spsdk.mboot.exceptions.McuBootError

MBoot Module: Connection Exception.

Initialize the base SPSDK Exception.

fmt = 'MBoot: Connection issue -> {description}'
exception spsdk.mboot.exceptions.McuBootDataAbortError(desc=None)

Bases: spsdk.mboot.exceptions.McuBootError

MBoot Module: Data phase aborted by sender.

Initialize the base SPSDK Exception.

fmt = 'Mboot: Data aborted by sender'
exception spsdk.mboot.exceptions.McuBootError(desc=None)

Bases: spsdk.exceptions.SPSDKError

MBoot Module: Base Exception.

Initialize the base SPSDK Exception.

fmt = 'MBoot: {description}'