Shadow Registers API

SPSDK shadow registers management for Debug Authentication Tool (DAT).

This module provides functionality for controlling and managing shadow registers that enable debug access through the Debug Authentication Tool. It includes register manipulation, debug enablement, and verification capabilities.

class spsdk.fuses.shadowregs.ShadowRegisters(family, debug_probe=None)

Bases: FeatureBaseClassComm

SPSDK Shadow Registers Manager.

This class provides control and management of shadow registers for NXP MCU devices. Shadow registers are temporary storage locations that mirror fuse values and can be modified without permanently altering the actual fuses, enabling safe testing and configuration validation.

Variables:

FEATURE – Database feature identifier for shadow registers operations.

Initialize Shadow register class.

Creates a new instance of the Shadow register class with the specified family and optional debug probe for fuse and shadow register operations.

Parameters:

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

• debug_probe (Optional[DebugProbe]) – Optional debug probe interface for hardware communication.

FEATURE: str = 'shadow_regs'

static antipolize_register(src, dst)

Antipolize given registers by applying bitwise XOR with 0xFFFFFFFF.

This method takes the value from the source register and applies bitwise NOT operation (XOR with 0xFFFFFFFF) to create an antipole value, which is then set to the destination register.

Parameters:

• src (FuseRegister) – Input register to read the value from.

• dst (FuseRegister) – The antipole destination register where the inverted value will be stored.

Return type:

None

static comalg_dcfg_cc_socu_crc8(val)

Compute CRC8 for DCFG_CC_SOCU register value.

This function extracts the upper 24 bits of the input value, computes a CRC8 checksum over those bytes, and replaces the lower 8 bits with the computed CRC.

Parameters:

val (int) – Input DCFG_CC_SOCU register value (32-bit integer).

Return type:

int

Returns:

DCFG_CC_SOCU value with CRC8 field in the lower 8 bits.

comalg_dcfg_cc_socu_test_en(val)

Configure DCFG_CC_SOCU register with appropriate test mode setting.

The method modifies the DEV_TEST_EN bit in DCFG_CC_SOCU register based on the current fuse mode to satisfy MCU operational requirements.

Parameters:

val (int) – Input DCFG_CC_SOCU register value to be modified.

Return type:

int

Returns:

Modified DCFG_CC_SOCU value with test mode bit configured appropriately.

compute_register(reg, method)

Recalculate register value using specified computation method.

The method dynamically calls the specified computation function to update the register’s value. The computation method must exist as an attribute of the current object.

Parameters:

• reg (FuseRegister) – Register to be recalculated.

• method (str) – Method name to be used to recompute the register value.

Raises:

SPSDKError – When the specified computing routine is not found.

Return type:

None

static crc_update(data, crc=0, is_final=True)

Compute CRC8 ITU checksum from given bytes.

The function implements CRC8 ITU algorithm with polynomial 0x07 and final XOR value 0x55. Supports incremental CRC calculation for large data processing.

Parameters:

• data (bytes) – Input data bytes to compute CRC checksum.

• crc (int) – Initial CRC seed value for incremental calculation.

• is_final (bool) – Flag indicating whether to apply final XOR transformation.

Return type:

int

Returns:

Computed CRC8 checksum value.

create_fuse_blhost_script(reg_list)

Create BLHOST script to burn fuses.

The method generates a script file that can be used with BLHOST tool to program fuses on the target device. It processes the register list, handles antipole registers, and creates appropriate efuse-program-once commands for each register.

Parameters:

reg_list (list[str]) – List of register names to be burned to fuses.

Raises:

SPSDKError – Register not found for the target device family.

Return type:

str

Returns:

Content of BLHOST script file as string.

flush_func_handler()

Execute the flush function handler for shadow registers.

Determines the flush function name from the database configuration and executes the corresponding method if it exists on the current instance.

Raises:

SPSDKError – When the specified flush function method doesn’t exist.

Return type:

None

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

Create configuration for shadow registers.

The method generates a configuration object containing family information and register data. Optionally filters to include only modified registers when diff mode is enabled.

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 and register information.

get_register(reg_name)

Get shadow register value from device.

Reads the shadow register value from the connected device using the debug probe. For group registers, reads all sub-registers and combines their values.

Parameters:

reg_name (str) – The register name to read.

Raises:

• SPSDKError – Register not found, invalid configuration, or read operation failed.

• SPSDKDebugProbeError – Debug probe is not specified or communication failed.

Return type:

bytes

Returns:

The value of requested register in bytes.

classmethod get_validation_schemas(family)

Create the validation schema for shadow registers.

The method builds validation schemas by combining family-specific schema with shadow registers schema, updating the registers properties based on the provided family configuration.

Parameters:

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

Raises:

SPSDKError – Family is not supported or schema generation fails.

Return type:

list[dict[str, Any]]

Returns:

List of validation schemas containing family and shadow registers schemas.

classmethod load_from_config(config, debug_probe=None)

Load shadow registers configuration from config object.

Creates a new shadow registers instance with the specified family and debug probe, then loads register values from the configuration. Automatically computes missing bitfields for registers with computed fields and handles antipole register pairs.

Parameters:

• config (Config) – Configuration object containing shadow registers settings.

• debug_probe (Optional[DebugProbe]) – Optional debug probe interface for hardware communication.

Return type:

Self

Returns:

Configured shadow registers instance with loaded register values.

reload_registers()

Reload all the values in managed registers.

This method iterates through all registers in the managed collection and refreshes their values by calling get_register for each one.

Return type:

None

rw61x_update_scratch_reg()

Update scratch register for RW61x to enable shadow register functionality.

This method writes a specific value to the scratch register address to activate the shadow register functionality on RW61x devices.

Raises:

AssertionError – If the probe is not a DebugProbe instance.

Return type:

None

set_all_registers(verify=True)

Update all shadow registers in target using their local values.

This method iterates through all registers and writes their current local values to the target device using the set_register method.

Parameters:

verify (bool) – Verify write operation after setting each register.

Return type:

None

set_loaded_registers(verify=True)

Update shadow registers in target using their local values.

This method iterates through all loaded registers and writes their current local values to the target device using the set_register method.

Parameters:

verify (bool) – Verify write operation after setting each register.

Raises:

SPSDKError – If register write operation fails.

Return type:

None

set_register(reg_name, data, verify=True, raw=True)

Set the value of the specified shadow register.

Writes data to a shadow register on the target device through the debug probe. Supports both individual registers and group registers with sub-registers.

Parameters:

• reg_name (str) – The register name to write to.

• data (Any) – The new data to be stored to shadow register.

• verify (bool) – Verify write operation after completion.

• raw (bool) – Do not use any modification hooks during value setting.

Raises:

• SPSDKDebugProbeError – The debug probe is not specified.

• SPSDKError – General error with write of shadow register or register not found.

• SPSDKVerificationError – Verification of written data failed.

Return type:

None

spsdk.fuses.shadowregs.enable_debug(probe, family)

Enable debug access ports on devices with debug mailbox.

The method checks if AHB access is available and if not, attempts to unlock the device using debug mailbox system. It handles probe reconnection and validates the unlock operation.

Parameters:

• probe (DebugProbe) – Initialized debug probe for device communication.

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

Return type:

bool

Returns:

True if debug port is enabled, False otherwise.

Raises:

SPSDKError – Invalid input parameters or unlock method failed.