SDP Module API

SDP Module API#

SPSDK SDP (Serial Download Protocol) communication module.

This module provides a unified interface for SDP communication across different transport layers including UART and USB interfaces. It enables secure provisioning and device communication for NXP MCUs supporting the SDP protocol.

SDP Interfaces

SDP Communication protocol#

SPSDK Serial Download Protocol (SDP) communication implementation.

This module provides the SDP class for communicating with NXP MCUs using the Serial Download Protocol, enabling device programming and debugging operations through various interfaces.

class spsdk.sdp.sdp.SDP(interface, cmd_exception=False)#

Bases: object

Serial Downloader Protocol interface for i.MX devices.

This class provides a high-level interface for communicating with i.MX devices using the Serial Downloader Protocol (SDP). It manages device connections, command execution, and status tracking for secure provisioning operations.

Initialize the SDP object.

Parameters:

interface (Union[SdpUARTInterface, SdpUSBInterface]) – Interface to a device
cmd_exception (bool) – True if commands should raise in exception, defaults to False

close()#

Close the connection to i.MX device.

This method properly disconnects the communication interface with the i.MX device and releases any associated resources.

Return type:: None

property cmd_status: int#

Get the response value from the command.

Returns:: The status code from the last executed command.

property hab_status: int#

Get the response value from HAB.

Returns:: HAB status response value.

property is_opened: bool#

Check interface connection status.

Returns:: True if device is open, False if it’s closed.

jump_and_run(address)#

Jump to specified address and run code from there.

This command instructs the device to transfer execution control to the specified memory address and begin executing code from that location.

Parameters:: address (int) – Destination memory address to jump to and execute code from.
Return type:: bool
Returns:: True if the jump command was successfully processed, False otherwise.

open()#

Connect to i.MX device.

Establishes connection to the i.MX device using the configured interface.

Raises:: SPSDKConnectionError – If the connection to the device fails.
Return type:: None

read(address, length, data_format=32)#

Read value from register or memory at specified address.

Parameters:

address (int) – Start address of the first register or memory location
length (int) – Number of bytes to read
data_format (int) – Register access format in bits (8, 16, or 32)

Return type:

Optional[bytes]

Returns:

Read data as bytes if successful, None otherwise

read_safe(address, length=None, data_format=32, align_count=False)#

Read value from register/memory at specified address.

This method is safe because it validates input arguments and prevents fault execution.

Parameters:

address (int) – Start address of first register.
length (Optional[int]) – Count of bytes to read, defaults to data_format byte size if not specified.
data_format (int) – Register access format in bits (8, 16, or 32).
align_count (bool) – Align the count to data_format, defaults to False.

Return type:

Optional[bytes]

Returns:

Read bytes if successful, None otherwise.

Raises:

SdpError – If the data format is invalid or address is not properly aligned.

read_status()#

Read error status from the device.

This method sends a command to read the current error status and processes the response to extract the status value.

Return type:: Optional[int]
Returns:: Status value if the command succeeds, None if it fails.

set_baudrate(baudrate)#

Configure the UART baudrate on the device side.

The default baudrate is 115200.

Parameters:: baudrate (int) – Baudrate value to be set on the device.
Return type:: bool
Returns:: True if baudrate configuration was successful, False otherwise.

skip_dcd()#

Skip DCD blob from loaded file.

The method sends a SKIP_DCD_HEADER command to skip the Device Configuration Data blob during the boot process.

Return type:: bool
Returns:: True if command executed successfully, False otherwise.
Raises:: SdpCommandError – If command failed and the ‘cmd_exception’ is set to True.

property status_code: StatusCode#

Get status code from SDP.

Returns:: Current status code of the SDP communication.

write(address, value, count=4, data_format=32)#

Write value into register or memory at specified address.

Parameters:

address (int) – Start address of target register or memory location
value (int) – Value to write to the register or memory
count (int) – Number of bytes to write (maximum 4 bytes)
data_format (int) – Data access format in bits (8, 16, or 32)

Return type:

bool

Returns:

True if write operation succeeded, False otherwise

Raises:

SdpCommandError – If command failed and cmd_exception is enabled

write_csf(address, data)#

Write CSF Data at specified address.

This method sends a WRITE_CSF command to write Command Sequence File data to the target device at the specified memory address.

Parameters:

address (int) – Start address where CSF data will be written
data (bytes) – The CSF data in binary format to be written

Return type:

bool

Returns:

True if the write operation succeeds, False otherwise

write_dcd(address, data)#

Write DCD values at specified address.

This method sends a WRITE_DCD command to write Device Configuration Data (DCD) to the target device at the specified memory address.

Parameters:

address (int) – Start address where DCD data will be written
data (bytes) – The DCD data in binary format to be written

Return type:

bool

Returns:

True if the write operation was successful, False otherwise

write_file(address, data)#

Write file or data to specified memory address.

This method sends a WRITE_FILE command to write the provided data to the target device at the specified memory address.

Parameters:

address (int) – Target memory address where data will be written
data (bytes) – Binary data to be written to the device

Return type:

bool

Returns:

True if the write operation succeeds, False otherwise

write_safe(address, value, count=4, data_format=32)#

Write value into register/memory at specified address.

This method provides safe register/memory writing by validating input arguments, ensuring proper address alignment, and preventing fault execution. The count parameter is automatically aligned to the data format requirements.

Parameters:

address (int) – Start address of target register or memory location.
value (int) – Value to write to the register/memory.
count (int) – Number of bytes to write (maximum 4, will be aligned automatically).
data_format (int) – Register access format in bits (8, 16, or 32).

Return type:

bool

Returns:

True if write operation succeeds, False otherwise.

Raises:

SdpError – If address is not properly aligned or data_format is invalid.

SDP Commands#

SPSDK SDP protocol commands and responses implementation.

This module provides command packet structures, response handling, and protocol definitions for Serial Download Protocol (SDP) communication with NXP MCUs.

class spsdk.sdp.commands.CmdPacket(tag, address, pformat, count, value=0)#

Bases: CmdPacketBase

SDP command packet for device communication.

This class encapsulates command data that can be serialized and sent to target devices through the Serial Download Protocol (SDP). It handles command formatting, validation, and binary export functionality.

Variables:

FORMAT – Binary format string for packet serialization.
EMPTY_VALUE – Default empty value used in packet padding.

Initialize SDP command structure.

Creates a new SDP (Serial Download Protocol) command with specified parameters for communication with the target device.

Parameters:

tag (CommandTag) – Command tag enumeration value representing the specific SDP command.
address (int) – Target memory address for the command operation.
pformat (int) – Data format specification (8=byte, 16=half-word, 32=word).
count (int) – Number of data units to process in the command.
value (int) – Optional data value for write operations, defaults to 0.

EMPTY_VALUE = 0#

FORMAT = '>HIB2IB'#

export(padding=True)#

Return command packet as bytes.

Exports the SDP command as a binary packet using the defined format structure. The packet includes tag, address, format, count, value fields and padding.

Parameters:: padding (bool) – Whether to include padding in the exported packet, defaults to True.
Return type:: bytes
Returns:: Binary representation of the command packet.

class spsdk.sdp.commands.CmdResponse(hab, raw_data)#

Bases: CmdResponseBase

SDP command response handler.

This class processes and interprets responses received from SDP (Serial Download Protocol) commands, providing convenient access to response values and status information including HAB (High Assurance Boot) status.

Initialize the response object.

Parameters:

hab (bool) – HAB status response flag indicating security state
raw_data (bytes) – Raw response data received from the target device

property value: int#

Get integer representation of the response.

Returns:: Integer value extracted from the raw response data.

class spsdk.sdp.commands.CommandTag(tag, label, description=None)#

Bases: SpsdkEnum

SDP Command Tags enumeration.

This enumeration defines all available Serial Download Protocol (SDP) command tags used for communication with NXP MCU targets during secure provisioning operations. Each command represents a specific operation like reading/writing memory, jumping to addresses, or managing boot sequences.

ERROR_STATUS = (1285, 'ErrorStatus', 'Read error code')#

JUMP_ADDRESS = (2827, 'JumpAddress', 'Jump to specified address and run')#

PING = (23206, 'Ping')#

READ_REGISTER = (257, 'ReadRegister', 'Read data from memory or registers')#

SET_BAUDRATE = (3341, 'SetBaudrate')#

SKIP_DCD_HEADER = (3084, 'SkipDcdHeader', 'Skip DCD content from loaded image')#

WRITE_CSF = (1542, 'WriteCsf', 'Write CSF data into target')#

WRITE_DCD = (2570, 'WriteDcd', 'Write DCD data into target')#

WRITE_FILE = (1028, 'WriteFile', 'Write file (boot image) into memory')#

WRITE_REGISTER = (514, 'WriteRegister', 'Write one word (max 4 bytes) into memory or register')#

class spsdk.sdp.commands.ResponseValue(tag, label, description=None)#

Bases: SpsdkEnum

SDP Response Values enumeration.

This enumeration defines standard response codes returned by SDP (Serial Download Protocol) operations, including success indicators for various commands and HAB (High Assurance Boot) status values.

BAUDRATE_SET = (164629904, 'BAUDRATE_SET', 'Baudrate Setup Success')#

HAB_SUCCESS = (4042322160, 'HAB_SUCCESS', 'HAB Success')#

LOCKED = (305411090, 'LOCKED', 'HAB Is Enabled (Locked)')#

SKIP_DCD_HEADER_OK = (2416824329, 'SKIP_DCD_HEADER_OK', 'Skip DCD Header Success')#

UNLOCKED = (1450735702, 'UNLOCKED', 'Hab Is Disabled (Unlocked)')#

WRITE_DATA_OK = (311069202, 'WRITE_DATA_OK', 'Write Data Success')#

WRITE_FILE_OK = (2290649224, 'WRITE_FILE_OK', 'Write File Success')#

SDPS communication protocol#

SPSDK Serial Download Protocol Stream (SDPS) communication implementation.

This module provides functionality for secure communication with NXP MCU bootloaders using the SDPS protocol. It includes command packet handling, ROM information management, and secure provisioning operations.

class spsdk.sdp.sdps.CmdPacket(signature, length, flags, command, tag=1)#

Bases: CmdPacketBase

SDP Command Packet for device communication.

This class represents a command packet structure used in Serial Download Protocol (SDP) communication with NXP devices. It encapsulates command data including signature, flags, and command type for reliable device interaction.

Variables:: FORMAT – Binary format string for packet serialization.

Initialize the SDP command structure.

Creates a new SDP (Serial Download Protocol) command with the specified parameters for communication with the target device.

Parameters:

signature (int) – Command signature for validation
length (int) – Length of the command data
flags (CommandFlag) – Command flags defining behavior and options
command (CommandTag) – Command tag specifying the operation type
tag (int) – Tag number representing the command, defaults to 1

FORMAT = '<3IB2xbI11x'#

export(padding=True)#

Export command packet as bytes.

Serializes the command packet structure into a binary format using the defined FORMAT string for transmission or storage.

Parameters:: padding (bool) – Whether to include padding in the exported packet.
Return type:: bytes
Returns:: Binary representation of the command packet.

class spsdk.sdp.sdps.CommandFlag(tag, label, description=None)#

Bases: SpsdkEnum

SDP command flag enumeration for data transfer direction.

This enumeration defines the direction flags used in SDP (Serial Download Protocol) commands to specify whether data flows from device to host or from host to device.

DEVICE_TO_HOST_DIR = (128, 'DataOut', 'Data Out')#

HOST_TO_DEVICE_DIR = (0, 'DataIn', 'Data In')#

class spsdk.sdp.sdps.CommandSignature(tag, label, description=None)#

Bases: SpsdkEnum

SDP command signature enumeration.

This enumeration defines the signature values used to identify different types of SDP (Serial Download Protocol) command block wrappers in secure provisioning operations.

CBW_BLTC_SIGNATURE = (1129598018, 'CbwBlts', 'Command Block Wrapper BLTC')#

CBW_PITC_SIGNATURE = (1129597264, 'CbwPits', 'Command Block Wrapper PITC')#

class spsdk.sdp.sdps.CommandTag(tag, label, description=None)#

Bases: SpsdkEnum

SDP command tag enumeration.

This enumeration defines the available command tags used in the Serial Download Protocol (SDP) for communication with NXP MCU devices during secure provisioning operations.

FW_DOWNLOAD = (2, 'FwDownload', 'Firmware download')#

class spsdk.sdp.sdps.RomInfo(no_cmd, hid_ep1, hid_pack_size)#

Bases: object

ROM information container for SDP communication parameters.

This class holds configuration data about ROM capabilities and communication settings used during Serial Download Protocol (SDP) operations.

hid_ep1: bool#

hid_pack_size: int#

no_cmd: bool#

class spsdk.sdp.sdps.SDPS(interface, family)#

Bases: object

SDPS communication interface for NXP MCU devices.

This class provides a high-level interface for communicating with NXP MCU devices using the Serial Downloader Protocol Stream (SDPS). It manages device connections, protocol parameters, and ROM-specific configurations across the supported MCU family portfolio.

Initialize SDPS object.

Parameters:

interface (Union[SdpUARTInterface, SdpUSBInterface]) – SDP device interface for communication.
family (FamilyRevision) – Target platform family and revision information.

close()#

Close the connection to the i.MX device.

This method properly disconnects from the i.MX device and releases any associated resources through the underlying interface.

Raises:: SPSDKError – If there’s an error during the disconnection process.
Return type:: None

property family: FamilyRevision#

Get device family and revision information.

Returns:: Family and revision details of the connected device.

static get_supported_families(include_predecessors=False)#

Get supported families for SDPS protocol.

Retrieves a list of device families that support the SDPS (Serial Download Protocol Stream) communication protocol. Optionally includes predecessor device families for backward compatibility.

Parameters:: include_predecessors (bool) – Include predecessor family names in the result list.
Return type:: list[FamilyRevision]
Returns:: List of family revisions that support SDPS protocol.

property is_opened: bool#

Check interface open status.

Returns:: True if device is open, False if it’s closed.

open()#

Connect to i.MX device.

Establishes connection to the i.MX device through the configured interface if not already connected. Logs the connection attempt with interface details.

Raises:: SPSDKError – If the interface fails to open or connect to the device.
Return type:: None

property rom_info: RomInfo#

Get ROM information for the current device family.

Retrieves ROM protocol parameters from the device database including command support, HID endpoint configuration, and packet size settings.

Returns:: ROM information object containing protocol parameters.

write_file(data)#

Write data to the target device.

This method configures the interface and sends the boot image data to the target device. It handles command packet creation and data transmission according to the ROM information settings.

Parameters:

data (bytes) – The boot image data in binary format.

Raises:

SdpConnectionError – Timeout or connection error during data transfer.
SPSDKError – Failure occurred in middle of transfer process.

Return type:

None

SDP Error/Status codes#

SDP protocol error codes and status information.

This module defines error codes, status codes, and HAB (High Assurance Boot) related error information used in the Serial Download Protocol (SDP) communication. It provides enumerations for status codes, HAB status information, error reasons, and error contexts to facilitate proper error handling and debugging.

class spsdk.sdp.error_codes.HabErrorContext(tag, label, description=None)#

Bases: SpsdkEnum

HAB Error Context enumeration for Secure Provisioning operations.

This enumeration defines context codes used by the High Assurance Boot (HAB) system to identify where security events occurred during the boot process. Each context represents a specific HAB function or operation stage.

AUTH_DATA_BLOCK = (219, 'AUTH_DATA_BLOCK', 'Authenticated data block')#

HAB_CTX_ANY = (0, 'HAB_CTX_ANY', 'Match any context in hab_rvt.report_event()')#

HAB_FAB_TEST = (255, 'HAB_FAB_TEST', 'Event logged in hab_fab_test()')#

HAB_RVT_ENTRY = (225, 'HAB_RVT_ENTRY', 'Event logged in hab_rvt.entry()')#

RVT_ASSERT = (160, 'RVT_ASSERT', 'Event logged in hab_rvt.assert()')#

RVT_AUTHENTICATE_IMG = (10, 'v', 'Event logged in hab_rvt.authenticate_image()')#

RVT_CHECK_TARGET = (51, 'RVT_CHECK_TARGET', 'Event logged in hab_rvt.check_target()')#

RVT_CSF_DCD_CMD = (192, 'RVT_CSF_DCD_CMD', 'Event logged executing CSF or DCD command')#

RVT_EXIT = (238, 'RVT_EXIT', 'Event logged in hab_rvt.exit()')#

RVT_RUN_CSF = (207, 'RVT_RUN_CSF', 'Event logged in hab_rvt.run_csf()')#

RVT_RUN_DCD = (221, 'RVT_RUN_DCD', 'Event logged in hab_rvt.run_dcd()')#

class spsdk.sdp.error_codes.HabErrorReason(tag, label, description=None)#

Bases: SpsdkEnum

HAB Error Reason enumeration for NXP MCU secure boot operations.

This enumeration defines standardized error reason codes returned by the High Assurance Boot (HAB) authentication process. Each error code includes a numeric value, symbolic name, and human-readable description to facilitate debugging and error handling in secure provisioning workflows.

CALL_OUT_OF_SEQUENCE = (40, 'CALL_OUT_OF_SEQUENCE', 'Function Called Out Of Sequence')#

ENGINE_FAILURE = (48, 'ENGINE_FAILURE', 'Engine Failure')#

EXHAUSTED_STORAGE_REGION = (45, 'EXHAUSTED_STORAGE_REGION', 'Exhausted Storage Region')#

EXPIRED_POLL_COUNT = (43, 'EXPIRED_POLL_COUNT', 'Expired Poll Count')#

FAILED_CALLBACK = (30, 'FAILED_CALLBACK', 'Failed Callback Function')#

INVALID_ADDRESS = (34, 'INVALID_ADDRESS', 'Invalid Address: Access Denied')#

INVALID_ASSERTION = (12, 'INVALID_ASSERTION', 'Invalid Assertion')#

INVALID_BLOB = (49, 'INVALID_BLOB', 'Invalid Blob')#

INVALID_CERTIFICATE = (33, 'INVALID_CERTIFICATE', 'Invalid Certificate')#

INVALID_COMMAND = (6, 'INVALID_COMMAND', 'Invalid Command: Malformed')#

INVALID_CSF = (17, 'INVALID_CSF', 'Invalid CSF')#

INVALID_DATA_SIZE = (23, 'INVALID_DATA_SIZE', 'Invalid Data Size')#

INVALID_DCD = (39, 'INVALID_DCD', 'Invalid DCD')#

INVALID_INDEX = (15, 'INVALID_INDEX', 'Invalid Index: Access Denied')#

INVALID_IVT = (5, 'INVALID_IVT', 'Invalid IVT')#

INVALID_KEY = (29, 'INVALID_KEY', 'Invalid Key')#

INVALID_MAC = (50, 'INVALID_MAC', 'Invalid MAC')#

INVALID_SIGNATURE = (24, 'INVALID_SIGNATURE', 'Invalid Signature')#

MEMORY_FAILURE = (46, 'MEMORY_FAILURE', 'Memory Failure')#

UNKNOWN = (0, 'UNKNOWN', 'Unknown Reason')#

UNSUITABLE_STATE = (9, 'UNSUITABLE_STATE', 'Unsuitable State')#

UNSUPPORTED_ALGORITHM = (18, 'UNSUPPORTED_ALGORITHM', 'Unsupported Algorithm')#

UNSUPPORTED_COMMAND = (3, 'UNSUPPORTED_COMMAND', 'Unsupported Command')#

UNSUPPORTED_CONF_ITEM = (36, 'UNSUPPORTED_CONF_ITEM', 'Unsupported Configuration Item')#

UNSUPPORTED_ENGINE = (10, 'UNSUPPORTED_ENGINE', 'Unsupported Engine')#

UNSUPPORTED_KEY_OR_PARAM = (27, 'UNSUPPORTED_KEY_OR_PARAM', 'Unsupported Key Type or Parameters')#

UNSUPPORTED_PROTOCOL = (20, 'UNSUPPORTED_PROTOCOL', 'Unsupported Protocol')#

class spsdk.sdp.error_codes.HabStatusInfo(tag, label, description=None)#

Bases: SpsdkEnum

HAB status information enumeration.

This enumeration defines the High Assurance Boot (HAB) status codes used to indicate the result of HAB operations in NXP secure boot processes.

ERROR = (51, 'ERROR', 'Failure')#

SUCCESS = (240, 'SUCCESS', 'Success')#

UNKNOWN = (0, 'UNKNOWN', 'Unknown')#

WARNING = (105, 'WARNING', 'Warning')#

class spsdk.sdp.error_codes.StatusCode(tag, label, description=None)#

Bases: SpsdkEnum

SDP status codes enumeration.

This enumeration defines all possible status codes returned by Serial Download Protocol (SDP) operations, providing standardized error reporting and success indication for SDP communication with NXP MCU devices.

CMD_FAILURE = (1, 'CommandFailure', 'Command Failure')#

HAB_IS_LOCKED = (2, 'HabIsLocked', 'HAB Is Locked')#

READ_DATA_FAILURE = (10, 'ReadDataFailure', 'Read Register/Data Failure')#

SKIP_DCD_HEADER_FAILURE = (15, 'SkipDcdHeaderFailure', 'Skip DCD Header Failure')#

SUCCESS = (0, 'Success', 'Success')#

WRITE_CSF_FAILURE = (14, 'WriteCsfFailure', 'Write CSF Failure')#

WRITE_DCD_FAILURE = (13, 'WriteDcdFailure', 'Write DCD Failure')#

WRITE_IMAGE_FAILURE = (12, 'WriteImageFailure', 'Write Image Failure')#

WRITE_REGISTER_FAILURE = (11, 'WriteRegisterFailure', 'Write Register Failure')#

SDP Exceptions#

SDP (Serial Download Protocol) exception classes.

This module defines custom exception classes for handling errors that occur during SDP operations, including command execution errors and connection issues.

exception spsdk.sdp.exceptions.SdpCommandError(cmd, value)#

Bases: SdpError

SDP command execution exception.

This exception is raised when an SDP command fails during execution, providing detailed error information including the command name and status code description.

Variables:: fmt – Format string template for error message display.

Initialize the SDP command exception.

Creates an exception instance for SDP command errors with error code resolution.

Parameters:

cmd (str) – Name of the SDP command that caused the exception.
value (int) – Response error value from the SDP command.

fmt = 'SDP: {cmd_name} interrupted -> {description}'#

exception spsdk.sdp.exceptions.SdpConnectionError(desc=None)#

Bases: SPSDKConnectionError, SdpError

SDP connection error exception.

This exception is raised when connection-related issues occur during SDP (Serial Download Protocol) operations, such as communication failures or device connectivity problems.

Variables:: fmt – Error message format template for connection issues.

Initialize the base SPSDK Exception.

Parameters:: desc (Optional[str]) – Optional description of the exception.

fmt = 'SDP: Connection issue -> {description}'#

exception spsdk.sdp.exceptions.SdpError(desc=None)#

Bases: SPSDKError

Base exception class for SDP (Serial Download Protocol) operations.

This exception serves as the foundation for all SDP-related errors in SPSDK, providing consistent error formatting and handling across SDP functionality.

Variables:: fmt – Format string template for SDP error messages.

Initialize the base SPSDK Exception.

Parameters:: desc (Optional[str]) – Optional description of the exception.

fmt = 'SDP: {description}'#

SDP Module API

Contents

SDP Module API#

SDP Communication protocol#

SDP Commands#

SDPS communication protocol#

SDP Error/Status codes#

SDP Exceptions#