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 classcmd_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 datamem_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 indexvalue (
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 addresssp (
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 addresslength (
int
) – Count of bytesmem_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 indexdata (
bytes
) – Input data aligned to 4 or 8 bytes
- Return type
bool
- Returns
False in case of any problem; True otherwise
-
flash_read_once
(index, count=4)¶ Read from MCU flash program once region (max 8 bytes).
- Parameters
index (
int
) – Start indexcount (
int
) – Count of bytes
- Return type
Optional
[bytes
]- Returns
Data read; None in case of an failure
-
flash_read_resource
(address, length, option=1)¶ Read resource of flash module.
- Parameters
address (
int
) – Start addresslength (
int
) – Number of bytesoption (
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
ValueError – If the backdoor_key is not 8 bytes long
-
fuse_program
(address, data, mem_id=0)¶ Program fuse.
- Parameters
address (
int
) – Start addressdata (
bytes
) – List of bytesmem_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 addresslength (
int
) – Count of bytesmem_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 byteskey_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 keykey_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 detailskey_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 addresslength (
int
) – Count of bytesmem_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 connectionreopen (
bool
) – True for reopen connection after HW reset else False
- Return type
bool
- Returns
False in case of any problem; True otherwise
- Raises
ValueError – if reopen is not supported
McuBootConnectionError – Failure to reopen the device
-
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
- Returns
status code of the last operation.
-
write_memory
(address, data, mem_id=0)¶ Write data into MCU memory.
- Parameters
address (
int
) – Start addressdata (
bytes
) – List of bytesmem_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 classflags (
int
) – Flags for the commandreserved (
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 bytesoffset (
int
) – The offset of input data
- Return type
- 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 commandflags (
int
) – Flags used by the commandargs (
int
) – Arguments used by the commanddata (
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 responseraw_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¶
-
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 responseraw_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 responseraw_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 responseraw_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 responseraw_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 responseraw_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 responseraw_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¶
-
-
spsdk.mboot.commands.
parse_cmd_response
(data, offset=0)¶ Parse command response.
- Parameters
data (
bytes
) – Input data in bytesoffset (
int
) – The offset of input data
- Return type
- 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: PropertyTagraw_values (
List
[int
]) – List of integers representing the property
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: PropertyTagraw_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: PropertyTagraw_values (
List
[int
]) – List of integers representing the propertytrue_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: PropertyTagraw_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: PropertyTagraw_values (
List
[int
]) – List of integers representing the propertyenum (
Type
[Enum
]) – Enumeration to pick fromna_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: PropertyTagraw_values (
List
[int
]) – List of integers representing the propertymem_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: PropertyTagraw_values (
List
[int
]) – List of integers representing the propertystr_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: PropertyTagraw_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: PropertyTagname (
Optional
[str
]) – Optional name for the propertydesc (
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: PropertyTagraw_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
TypeError – 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: PropertyTagraw_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 propertyraw_values (
list
) – Data received from the deviceext_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 valuekibibyte (
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 memoryraw_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 regionstart (
int
) – start address of regionsize (
int
) – size of regionsector_size (
int
) – size of sector
-
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 regionend (
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 regionstart (
int
) – start address of regionsize (
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 exceptionvalue (
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'¶
-