SDP Module API

SDP Module API#

Module implementing the SDP communication protocol.

SDP Interfaces

SDP Communication protocol#

Module implementing the SDP communication protocol.

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

Bases: object

Serial Downloader Protocol.

Initialize the SDP object.

Parameters:

device – Interface to a device
cmd_exception (bool) – True if commands should raise in exception, defaults to False

close()#

Disconnect i.MX device.

Return type:: None

property cmd_status: int#: Get the response value from the command.

property hab_status: int#: Get the response value from hab.

property is_opened: bool#

Indicates whether the underlying interface is open.

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

jump_and_run(address)#

Jump to specified address and run code from there.

Parameters:: address (int) – Destination address
Return type:: bool
Returns:: Return True if success else False.

open()#

Connect to i.MX device.

Return type:: None

read(address, length, data_format=32)#

Read value from reg/mem at specified address.

Parameters:

address (int) – Start address of first register
length (int) – Count of bytes
data_format (int) – Register access format 8, 16, 32 bits

Return type:

Optional[bytes]

Returns:

Return bytes if success else None.

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

Read value from reg/mem at specified address.

This method is safe, because is validating input arguments and prevents fault execution.

Parameters:

address (int) – Start address of first register
length (Optional[int]) – Count of bytes
data_format (int) – Register access format 8, 16, 32 bits
align_count (bool) – Align the count to data_format , default False

Return type:

Optional[bytes]

Returns:

Return bytes if success else None.

Raises:

SdpError – If the address is not properly aligned

read_status()#

Read Error Status.

Return type:: Optional[int]
Returns:: Return status value if success else None

set_baudrate(baudrate)#

Configure the UART baudrate on the device side.

The default baudrate is 115200.

Parameters:: baudrate (int) – Baudrate to be set
Return type:: bool
Returns:: Return True if success else False.

skip_dcd()#

Skip DCD blob from loaded file.

Return type:: bool
Returns:: Return True if success else False.
Raises:: SdpCommandError – If command failed and the ‘cmd_exception’ is set to True

property status_code: StatusCode#: Get status code from SDP.

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

Write value into reg/mem at specified address.

Parameters:

address (int) – Start address of first register
value (int) – Register value
count (int) – Count of bytes (max 4)
data_format (int) – Register access format 8, 16, 32 bits

Return type:

bool

Returns:

Return True if success else False.

Raises:

SdpCommandError – If command failed and the ‘cmd_exception’ is set to True

write_csf(address, data)#

Write CSF Data at specified address.

Parameters:

address (int) – Start Address
data (bytes) – The CSF data in binary format

Return type:

bool

Returns:

Return True if success else False.

write_dcd(address, data)#

Write DCD values at specified address.

Parameters:

address (int) – Start Address
data (bytes) – The DCD data in binary format

Return type:

bool

Returns:

Return True if success else False.

write_file(address, data)#

Write File/Data at specified address.

Parameters:

address (int) – Start Address
data (bytes) – The boot image data in binary format

Return type:

bool

Returns:

Return True if success else False.

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

Write value into reg/mem at specified address.

This method is safe, because is validating input arguments and prevents fault execution.

Parameters:

address (int) – Start address of first register
value (int) – Register value
count (int) – Count of bytes (max 4)
data_format (int) – Register access format 8, 16, 32 bits

Return type:

bool

Returns:

Return True if success else False.

Raises:

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

SDP Commands#

Commands and responses used by SDP module.

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

Bases: CmdPacketBase

Class representing a command packet to be sent to device.

Initialize the struct.

Parameters:

tag (CommandTag) – Tag number representing the command
address (int) – Address used by the command
pformat (int) – Format of the data: 8 = byte, 16 = half-word, 32 = word
count (int) – Count used by individual command
value (int) – Value to use in a particular command, defaults to 0

EMPTY_VALUE = 0#

FORMAT = '>HIB2IB'#

to_bytes(padding=True)#

Return command packet as bytes.

Return type:: bytes

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

Bases: CmdResponseBase

Response on the previously issued command.

Initialize the response object.

Parameters:

hab (bool) – HAB status response
raw_data (bytes) – Data sent by the device

property value: int#: Return a integer representation of the response.

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

Bases: SpsdkEnum

SDP Commands.

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.

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#

Module implementing the SDPS communication protocol.

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

Bases: CmdPacketBase

Class representing a command packet to be sent to device.

Initialize the struct.

Parameters:

tag (int) – Tag number representing the command
address – Address used by the command
pformat – Format of the data: 8 = byte, 16 = half-word, 32 = word
count – Count used by individual command
value – Value to use in a particular command, defaults to 0

FORMAT = '<3IB2xbI11x'#

to_bytes(padding=True)#

Return command packet as bytes.

Return type:: bytes

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

Bases: SpsdkEnum

Command flag enum.

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

Command signature enum.

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

Command tag enum.

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

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

Bases: object

Secure Serial Downloader Protocol.

Initialize SDPS object.

Parameters:

device – USB device
device_name (str) – target platform name used to determine ROM settings

close()#

Disconnect i.MX device.

Return type:: None

property is_opened: bool#

Indicates whether the underlying interface is open.

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

property name: str#: Get name.

open()#

Connect to i.MX device.

Return type:: None

write_file(data)#

Write data to the target.

Parameters:: data (bytes) – The boot image data in binary format
Raises:: SdpConnectionError – Timeout or Connection error
Return type:: None

SDP Error/Status codes#

Error codes defined by the SDP protocol.

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

Bases: SpsdkEnum

HAB Error Context.

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.

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 codes.

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.

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#

Exceptions used in the SDP module.

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

Bases: SdpError

SDP Module: Command Exception.

Initialize the Exception object.

Parameters:

cmd (str) – Name of the command causing the exception
value (int) – Response value causing the exception

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

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

Bases: SdpError

SDP Module: Connection Exception.

Initialize the base SPSDK Exception.

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

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

Bases: SPSDKError

SDP Module: Base Exception.

Initialize the base SPSDK Exception.

fmt = 'SDP: {description}'#

SDP Scanner#

Helper module used for scanning the existing devices.

spsdk.sdp.scanner.get_sdp_interface(port=None, usb=None, plugin=None, timeout=5000)#

Get SDP interface.

‘port’, ‘usb’ parameters are mutually exclusive; one of them is required.

Parameters:

port (Optional[str]) – name and speed of the serial port (format: name[,speed]), defaults to None
usb (Optional[str]) – PID,VID of the USB interface, defaults to None
plugin (Optional[str]) – Additional plugin to be used
timeout (int) – timeout in milliseconds

Return type:

SDPProtocolBase

Returns:

Selected interface instance

Raises:

SPSDKError – Only one of appropriate interfaces must be specified
SPSDKError – Interface couldn’t be opened

SDP Module API

Contents

SDP Module API#

SDP Communication protocol#

SDP Commands#

SDPS communication protocol#

SDP Error/Status codes#

SDP Exceptions#

SDP Scanner#