Fuses API

SPSDK Fuses support utilities.

This module provides functionality for handling and managing fuses across NXP MCU portfolio within the SPSDK framework.

Fuses

SPSDK fuse operations and management utilities.

This module provides comprehensive functionality for reading, writing, and managing fuses across NXP MCU devices. It includes abstract base classes for fuse operations, concrete implementations for different tools (blhost, nxpele), and utilities for fuse scripting and configuration management.

class spsdk.fuses.fuses.BlhostFuseOperator(mboot)

Bases: FuseOperator

SPSDK Blhost fuse operator for MCU fuse operations.

This class provides fuse read/write operations using the Blhost protocol through McuBoot interface. It handles individual fuse programming, reading, and script generation for batch operations.

Variables:

NAME – Operator identifier for blhost protocol.

Initialize the Blhost fuse operator.

Creates a new instance of the fuse operator that uses the provided McuBoot interface for communication with the target device.

Parameters:

mboot (McuBoot) – McuBoot interface instance for device communication.

NAME: Optional[str] = 'blhost'

classmethod get_fuse_script(family, fuses)

Generate BLHOST fuses programming script for given family and fuses.

Creates a complete script with header information including SPSDK version and chip family, followed by individual fuse programming commands with descriptive comments.

Parameters:

• family (FamilyRevision) – Target chip family and revision information.

• fuses (list[FuseRegister]) – List of fuse registers to be programmed.

Raises:

SPSDKAttributeError – When OTP index is not defined for a fuse register.

Return type:

str

Returns:

Complete BLHOST script as formatted string with programming commands.

classmethod get_fuse_write_cmd(index, value, lock=False, verify=False)

Get fuse write command for programming eFuses.

Generates a command string for programming eFuse values with optional verification and locking capabilities.

Parameters:

• index (int) – eFuse index to program.

• value (int) – Value to write to the eFuse.

• lock (bool) – Lock the eFuse after programming, defaults to False.

• verify (bool) – Verify the programmed value, defaults to False.

Return type:

str

Returns:

Formatted eFuse programming command string.

read_fuse(index, length)

Read a single fuse value from the device.

This method reads the value of a fuse at the specified index using the mboot interface. The length parameter specifies the expected bit length of the fuse data.

Parameters:

• index (int) – Index of the fuse to read

• length (int) – Length of fuse data in bits

Raises:

SPSDKFuseOperationFailure – When the fuse reading operation fails

Return type:

int

Returns:

The value read from the specified fuse

write_fuse(index, value, length, lock=False)

Write a single fuse to the device.

The method programs a fuse at the specified index with the given value and optionally locks it to prevent further modifications.

Parameters:

• index (int) – Index of the fuse to be written.

• value (int) – Fuse value to be programmed.

• length (int) – Length of fuse in bits.

• lock (bool) – Lock fuse after write to prevent further modifications.

Raises:

SPSDKFuseOperationFailure – Writing of fuse failed.

Return type:

None

class spsdk.fuses.fuses.BlhostFuseOperatorLegacy(mboot)

Bases: FuseOperator

Legacy Blhost fuse operator for backward compatibility.

This class provides fuse operations using legacy Blhost commands that differ from the standard implementation. It maintains compatibility with older systems while providing the same fuse read/write interface.

Variables:

NAME – Operator identifier for legacy Blhost operations.

Initialize the Blhost fuse operator.

Parameters:

mboot (McuBoot) – McuBoot instance for communication with the target device.

NAME: Optional[str] = 'blhost_legacy'

classmethod get_fuse_script(family, fuses)

Generate BLHOST fuses programming script for given family and fuses.

Creates a complete BLHOST script that includes voltage setting, fuse programming commands, and proper reset sequence for safe fuse programming operations.

Parameters:

• family (FamilyRevision) – Target MCU family and revision information.

• fuses (list[FuseRegister]) – List of fuse registers to be programmed with their values.

Raises:

SPSDKAttributeError – When OTP index is not defined for a fuse register.

Return type:

str

Returns:

Complete BLHOST script as string with programming commands.

classmethod get_fuse_write_cmd(index, value, lock=False, verify=False)

Get fuse write command.

Generates a command string for programming a fuse with the specified index and value.

Parameters:

• index (int) – Fuse index to program.

• value (int) – Value to write to the fuse.

• lock (bool) – Whether to lock the fuse after programming (currently not used in command).

• verify (bool) – Whether to verify the fuse after programming (currently not used in command).

Return type:

str

Returns:

Command string for fuse programming.

read_fuse(index, length)

Read a single fuse value from the device.

This method reads a fuse at the specified index with the given bit length and returns the fuse value as an integer.

Parameters:

• index (int) – Index of the fuse to read

• length (int) – Length of fuse in bits

Return type:

int

Returns:

Fuse value as integer

Raises:

SPSDKFuseOperationFailure – When reading of fuse fails

write_fuse(index, value, length, lock=False)

Write a single fuse.

This method programs a fuse at the specified index with the given value by setting the appropriate voltage, programming the fuse, and resetting the voltage.

Parameters:

• index (int) – Index of the fuse to be written.

• value (int) – Fuse value to be programmed.

• length (int) – Length of fuse in bits (currently not used in implementation).

• lock (bool) – Lock fuse after write (currently not implemented).

Raises:

SPSDKFuseOperationFailure – When the fuse programming operation fails.

Return type:

None

class spsdk.fuses.fuses.FuseOperator

Bases: object

Fuse operator abstract base class for device fuse management operations.

This abstract class defines the interface for reading, writing, and managing fuses across different NXP MCU devices. Concrete implementations provide device-specific fuse operation capabilities including script generation and command formatting.

Variables:

NAME – Operator name identifier for registration and lookup.

NAME: Optional[str] = None

abstract classmethod get_fuse_script(family, fuses)

Get fuse script for specified family and fuse registers.

Generates a script containing fuse programming commands based on the provided family revision and list of fuse registers.

Parameters:

• family (FamilyRevision) – Target MCU family and revision information.

• fuses (list[FuseRegister]) – List of fuse registers to include in the script.

Return type:

str

Returns:

Generated fuse programming script as string.

abstract classmethod get_fuse_write_cmd(index, value, lock=False, verify=False)

Get write command for a single fuse.

Parameters:

• index (int) – Index of the fuse to write.

• value (int) – Value to write to the fuse.

• lock (bool) – Whether to lock the fuse after writing, defaults to False.

• verify (bool) – Whether to verify the fuse value after writing, defaults to False.

Return type:

str

Returns:

Command string for writing the specified fuse.

classmethod get_operator_type(name)

Get operator type by its name.

Searches through all FuseOperator subclasses to find the one matching the specified name.

Parameters:

name (str) – Name of the fuse operator to find.

Raises:

SPSDKKeyError – When no fuse operator with the specified name exists.

Return type:

Type[FuseOperator]

Returns:

The FuseOperator subclass type matching the given name.

abstract read_fuse(index, length)

Read a single fuse value from the device.

Parameters:

• index (int) – Index of the fuse to read.

• length (int) – Length of the fuse in bits.

Return type:

int

Returns:

The fuse value as an integer.

abstract write_fuse(index, value, length, lock=False)

Write a single fuse.

The method writes a value to the specified fuse index with given bit length and optionally locks the fuse to prevent further modifications.

Parameters:

• index (int) – Index of the fuse to write.

• value (int) – Fuse value to be written.

• length (int) – Length of fuse in bits.

• lock (bool) – Lock fuse after write to prevent further modifications.

Return type:

None

class spsdk.fuses.fuses.FuseScript(family, feature, index=None, fuses_key='fuses')

Bases: object

SPSDK Fuse Script Generator.

This class generates programming scripts for writing fuses to NXP MCU devices. It manages fuse configuration data, validates settings against device databases, and produces executable scripts compatible with various programming tools like blhost.

Initialize FuseScript object.

Creates a new FuseScript instance for managing fuse operations on a specific device family and feature configuration.

Parameters:

• family (FamilyRevision) – Device family and revision information.

• feature (str) – Feature name to configure fuses for.

• index (Optional[int]) – Optional index to append to fuses key for multiple configurations.

• fuses_key (str) – Base key name for fuses configuration in database.

Raises:

SPSDKError – When the specified family has no fuses definition.

generate_file_header()

Generate file header for fuses programming script.

Creates a formatted header containing operator name, fuse name, SPSDK version, and target family information for use in generated programming scripts.

Return type:

str

Returns:

Formatted header string with script metadata.

generate_script(attributes_object, info_only=False)

Generate script for writing fuses.

This method generates a script for writing fuses based on the provided attributes object. The script includes the file header and the commands for setting the fuse values. Special attributes: - __str_value: Value with double underscore represents attribute of the object.

Parameters:

• attributes_object (object) – An object containing the attributes used to set the fuse values.

• info_only (bool) – If True, only the information about the fuses is generated, defaults to False.

Raises:

SPSDKError – OTP index is not defined for register.

Return type:

str

Returns:

The generated script for writing fuses or info string if info_only is True.

static get_object_value(value, attributes_object)

Get object value from attributes object by attribute name.

Retrieves the value of an attribute from the given object. The method handles attribute names that start with double underscores by removing the prefix before attempting to access the attribute.

Parameters:

• value (str) – Name of the attribute to retrieve, may start with “__” prefix.

• attributes_object (object) – Object from which to retrieve the attribute value.

Raises:

SPSDKValueError – When the object does not contain the specified attribute.

Return type:

Any

Returns:

Value of the requested attribute from the object.

write_script(filename, output_dir, attributes_object, overwrite=True)

Write script to file.

Generates a script using the provided attributes object and writes it to a file with the operator name appended to the filename.

Parameters:

• filename (str) – Base name for the output script file (without extension).

• output_dir (str) – Directory where the script file will be written.

• attributes_object (Any) – Object containing attributes used for script generation.

• overwrite (bool) – Whether to overwrite existing file if it exists.

Return type:

str

Returns:

The absolute path to the generated script file.

class spsdk.fuses.fuses.Fuses(family, fuse_operator=None)

Bases: FeatureBaseClassComm

SPSDK Fuses Manager.

This class provides a comprehensive interface for managing and manipulating fuse operations across NXP MCU families. It handles fuse register initialization, configuration loading, and communication with physical fuse hardware through configurable operators.

Variables:

FEATURE – Database feature identifier for fuses functionality.

Initialize Fuses class to control fuse operations.

The Fuses class provides functionality to manage and manipulate fuse registers for NXP MCU devices, including reading, writing, and configuring fuse values.

Parameters:

• family (FamilyRevision) – Target MCU family and revision information for fuse operations.

• fuse_operator (Optional[FuseOperator]) – Optional operator for performing actual fuse operations, defaults to None.

Raises:

SPSDKError – When the specified family has no fuses definition available.

FEATURE: str = 'fuses'

create_fuse_script()

Generate fuse programming script for blhost or nxpele tools.

This method processes all fuse registers in the context, handling both simple registers and group registers with sub-registers. For group registers, it processes sub-registers in the appropriate order based on the reverse_subregs_order flag.

Return type:

str

Returns:

Content of the fuse programming script file as a string.

property fuse_operator: FuseOperator

Get fuse operator instance.

Property to access the fuse operator for performing fuse operations on the device.

Raises:

SPSDKError – Fuse operator is not defined.

Returns:

The fuse operator instance.

property fuse_operator_type: Type[FuseOperator]

Get fuse operator type for the current family.

Returns the appropriate FuseOperator class type that corresponds to the device family configured for this instance.

Returns:

FuseOperator class type for the configured family.

get_config(data_path='./', diff=False)

Create fuse configuration object.

Generates a configuration object containing family information, revision details, and register settings that can be used for fuse programming or analysis.

Parameters:

• data_path (str) – Path to store the data files of configuration.

• diff (bool) – If set, only changed registers will be placed in configuration.

Return type:

Config

Returns:

Configuration object with family, revision and register data.

classmethod get_fuse_operator_type(family)

Get operator type based on family.

Retrieves the appropriate FuseOperator type for the specified MCU family by querying the database configuration.

Parameters:

family (FamilyRevision) – MCU family and revision specification.

Return type:

Type[FuseOperator]

Returns:

FuseOperator class type for the specified family.

Raises:

SPSDKError – If family is not supported or database query fails.

classmethod get_init_regs(family)

Get initialized fuse registers.

Creates and returns a new FuseRegisters instance for the specified family revision.

Parameters:

family (FamilyRevision) – The family revision to initialize the fuse registers for.

Return type:

FuseRegisters

Returns:

Initialized fuse registers instance for the given family.

classmethod get_validation_schemas(family)

Create the validation schema for fuses configuration.

The method builds validation schemas by combining basic family schemas with fuse-specific configuration schemas. It updates the family properties and integrates register validation schemas from initialization registers.

Parameters:

family (FamilyRevision) – Family description containing MCU family and revision information.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas for fuses configuration.

load_config(config)

Load the fuses configuration from dictionary.

The method validates the configuration against schema, loads register values, and sets up the fuse context with the configured registers.

Parameters:

config (dict[str, Any]) – Dictionary containing fuses configuration with registers section.

Raises:

SPSDKError – Invalid configuration format or validation failure.

Return type:

None

classmethod load_from_config(config)

Create fuses object from given configuration.

This class method instantiates a new fuses object using the provided configuration data, including family revision information and fuse-specific settings.

Parameters:

config (Config) – The configuration object containing fuses settings and family revision data.

Return type:

Self

Returns:

New fuses object configured according to the provided configuration.

read_all()

Read all fuses from connected device.

Attempts to read every fuse register from the connected device and updates the fuse context with successfully read registers. Failed reads are logged as warnings but do not stop the operation.

Raises:

SPSDKFuseOperationFailure – When individual fuse read operations fail (logged as warnings, does not interrupt the overall operation).

Return type:

None

read_single(name, check_locks=True)

Read single fuse from device.

Reads the value of a specified fuse register from the device, with optional lock checking to ensure the fuse is readable before attempting the operation.

Parameters:

• name (str) – Fuse name or uid to read from device.

• check_locks (bool) – Check value of lock fuse before reading to prevent locked fuse access.

Raises:

• SPSDKFuseOperationFailure – When fuse is not readable or read operation is locked.

• SPSDKFuseConfigurationError – When OTP index is not defined for the fuse.

Return type:

int

Returns:

Value read from the fuse register.

write_multiple(names)

Write multiple fuses to the device.

This method iterates through the provided list of fuse names or UIDs, finds the corresponding registers, and writes each one individually to the device.

Parameters:

names (list[str]) – List of fuse names or UIDs to be written to the device.

Raises:

SPSDKError – If any fuse name/UID is not found or write operation fails.

Return type:

None

write_single(name, lock=False)

Write single fuse to the device.

The method handles both individual fuses and group registers. It performs lock checks, validates write permissions, and manages individual write lock behavior according to fuse configuration.

Parameters:

• name (str) – Fuse name or uid to write.

• lock (bool) – Set lock after write operation.

Raises:

• SPSDKError – OTP index for fuse is not set.

• SPSDKFuseOperationFailure – Fuse is not writable, write-locked, or has non-reset value with write lock.

Return type:

None

class spsdk.fuses.fuses.NxpeleFuseOperator(ele_handler)

Bases: FuseOperator

NXP EdgeLock Enclave (ELE) fuse operator.

This class provides fuse operations for NXP EdgeLock Enclave devices, enabling reading and writing of fuse values through ELE message communication. It handles the low-level ELE protocol for secure fuse management operations.

Variables:

NAME – Operator identifier for NXP ELE fuse operations.

Initialize NXP ELE fuse operator.

Creates a new instance of the ELE fuse operator with the provided ELE message handler for secure fuse operations.

Parameters:

ele_handler (Any) – ELE message handler instance for communication with ELE.

Raises:

AssertionError – If ele_handler is not an instance of EleMessageHandler.

NAME: Optional[str] = 'nxpele'

classmethod get_fuse_script(family, fuses)

Generate fuse programming script for specified family and fuse registers.

Creates a complete NXPELE fuses programming script with header information and individual fuse write commands for each provided fuse register.

Parameters:

• family (FamilyRevision) – Target chip family and revision information.

• fuses (list[FuseRegister]) – List of fuse registers to include in the programming script.

Raises:

SPSDKAttributeError – When OTP index is not defined for any fuse register.

Return type:

str

Returns:

Complete fuse programming script as formatted string.

classmethod get_fuse_write_cmd(index, value, lock=False, verify=False)

Get write command for a single fuse.

Generates a command string for writing a value to a specific fuse index with optional locking. The verify parameter is not applicable for nxpele command.

Parameters:

• index (int) – Index of the fuse to write to.

• value (int) – Value to write to the fuse.

• lock (bool) – Whether to lock the fuse after writing, defaults to False.

• verify (bool) – Verification flag (not applicable for nxpele command), defaults to False.

Return type:

str

Returns:

Command string for writing the fuse.

read_fuse(index, length)

Read a single fuse value from the device.

This method uses ELE (EdgeLock Enclave) messaging to read a common fuse value from the specified index position.

Parameters:

• index (int) – Index of the fuse to read

• length (int) – Length of fuse in bits (currently not used in implementation)

Return type:

int

Returns:

The fuse value as an integer

write_fuse(index, value, length, lock=False)

Write a single fuse.

This method writes a value to a specific fuse register using the ELE (EdgeLock Enclave) messaging system. The fuse can optionally be locked after writing to prevent further modifications.

Parameters:

• index (int) – Index of the fuse register to write to.

• value (int) – Fuse value to be written to the register.

• length (int) – Length of fuse in bits (currently unused, fixed at 32 bits).

• lock (bool) – Lock fuse after write to prevent further modifications.

Return type:

None

exception spsdk.fuses.fuses.SPSDKFuseConfigurationError(desc=None)

Bases: SPSDKError

SPSDK Fuse configuration error exception.

This exception is raised when fuse configuration operations fail due to invalid parameters, unsupported configurations, or other fuse-related errors.

Initialize the base SPSDK Exception.

Parameters:

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

exception spsdk.fuses.fuses.SPSDKFuseOperationFailure(desc=None)

Bases: SPSDKError

SPSDK Fuse operation failure exception.

Exception raised when fuse-related operations fail during device provisioning or configuration processes. This includes failures in fuse reading, writing, verification, or other fuse management operations.

Initialize the base SPSDK Exception.

Parameters:

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

spsdk.fuses.fuses.mboot_operation_decorator(func)

Decorator to handle MCUboot operations with automatic connection management.

This decorator ensures that the MCUboot interface is properly opened before executing the decorated method and closed afterwards, regardless of whether the operation succeeds or fails.

Parameters:

func (Callable) – Function to be decorated that performs MCUboot operations.

Return type:

Callable

Returns:

Wrapped function with automatic connection management.