Protected Flash Region API

Protected Flash Region API#

SPSDK Protected Flash Region (PFR) management utilities.

This module provides functionality for working with Protected Flash Region configuration, including PFR data generation, parsing, and validation for NXP MCU devices.

Protected Flash Region#

SPSDK Protected Flash Region (PFR) management utilities.

This module provides comprehensive support for handling Protected Flash Region areas including CMPA (Customer Manufacturing Programming Area), CFPA (Customer Field Programmable Area), and related configuration structures for NXP MCUs.

class spsdk.pfr.pfr.BaseConfigArea(family)#

Bases: FeatureBaseClass

Base class for Protected Flash Region (PFR) configuration areas.

This class provides common functionality for CMPA (Customer Manufacturing Programming Area) and CFPA (Customer Field Programming Area) configuration management. It handles register loading, binary size calculations, and family-specific database operations for NXP MCU protected flash regions.

Variables:

FEATURE – Database feature identifier for PFR operations.
SUB_FEATURE – Sub-feature identifier to be defined by subclasses.
BINARY_SIZE – Default binary size in bytes for configuration area.
ROTKH_SIZE – Size of Root of Trust Key Hash in bytes.
ROTKH_REGISTER – Register name for Root of Trust Key Hash.
MARK – Binary marker for sealed configuration areas.
DESCRIPTION – Human-readable description of the configuration area.
IMAGE_PREFILL_PATTERN – Default pattern for prefilling binary images.
WRITE_METHOD – Memory interface method name for write operations.
READ_METHOD – Memory interface method name for read operations.

Initialize PFR instance for specified device family.

Sets up the database connection, loads device-specific registers, and initializes internal data structures for Protected Flash Region operations.

Parameters:

family (FamilyRevision) – Device family to use, list of supported families is available via ‘get_supported_families’ method

Raises:

SPSDKError – When no device is provided
SPSDKError – When device is not supported

BINARY_SIZE = 512#

DESCRIPTION = 'Base Config Area'#

FEATURE: str = 'pfr'#

IMAGE_PREFILL_PATTERN = '0x00'#

MARK = b'SEAL'#

PRE_VALIDATION_CFG_HOOK = <spsdk.utils.registers.RegistersPreValidationHook object>#

READ_METHOD = 'read_memory'#

ROTKH_REGISTER = 'ROTKH'#

ROTKH_SIZE = 32#

SUB_FEATURE: Optional[str] = 'SubClassDefineIt'#

WRITE_METHOD = 'write_memory'#

property additional_data: bytes#

Get the additional customer data stored in the configuration area.

Returns:: The additional customer data as bytes.

classmethod additional_data_cfg(family)#

Get the additional customer data configuration for the specified family.

This method retrieves the additional customer data configuration parameters from the database for the specified family and PFR/IFR area.

Parameters:: family (FamilyRevision) – The family revision to get the configuration for.
Return type:: AdditionalDataCfg
Returns:: AdditionalDataCfg object containing the configuration parameters.

property binary_size: int#

Get the final binary size of the PFR data.

The binary size includes both the registers size and any additional data that has been added to the PFR structure.

Returns:: Total size in bytes of the binary representation.

compute_register(reg, method)#

Recalculate register value.

The method dynamically calls a computation function based on the provided method name to update the register’s value.

Parameters:

reg (Register) – Register to be recalculated.
method (str) – Method name to be used for recalculation of register value.

Raises:

SPSDKPfrError – When the computing routine is not found.

Return type:

None

export(add_seal=False, keys=None, rotkh=None, draw=True)#

Export PFR configuration as binary data.

Generates binary output for PFR (Protected Flash Region) configuration with optional sealing and ROTKH (Root of Trust Key Hash) computation. The method can compute ROTKH from provided keys or use pre-computed ROTKH value.

Parameters:

add_seal (bool) – Finish the export with seal in the PFR record.
keys (Optional[list[PublicKey]]) – List of public keys to compute ROTKH field.
rotkh (Optional[bytes]) – Pre-computed ROTKH binary value.
draw (bool) – Draw the configuration data in log output.

Return type:

bytes

Returns:

Binary block with PFR configuration (CMPA or CFPA).

Raises:

SPSDKPfrRotkhIsNotPresent – This PFR block doesn’t contain ROTKH field.
SPSDKError – Invalid data size or cannot determine ROTKH source.

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

Get configuration from loaded PFR.

Extracts the current PFR configuration including family information, settings, and any additional data into a structured configuration object.

Parameters:

data_path (str) – Data path parameter (not used in PFR implementation).
diff (bool) – If True, return only configuration values that differ from reset state.

Return type:

Config

Returns:

PFR configuration object containing family, revision, type, settings and optional additional data.

classmethod get_supported_families(include_predecessors=False)#

Get supported families for the feature.

Retrieves a list of supported family revisions for the current feature class. The method handles sub-features and can optionally include predecessor families.

Parameters:: include_predecessors (bool) – Whether to include predecessor families in the result.
Return type:: list[FamilyRevision]
Returns:: List of supported family revisions for the feature.

classmethod get_validation_schemas(family)#

Get validation schemas for PFR configuration.

Creates validation schemas for the Protected Flash Region (PFR) configuration including family-specific settings, base configuration, and optional additional data.

Parameters:: family (FamilyRevision) – Family and revision specification for target MCU.
Raises:: SPSDKError – Family or revision is not supported.
Return type:: list[dict[str, Any]]
Returns:: List of validation schemas for PFR configuration.

classmethod get_validation_schemas_basic()#

Create the validation schema for supported families.

The method generates validation schemas by combining family-specific schema with PFR base configuration schema, filtered for supported families only.

Return type:: list[dict[str, Any]]
Returns:: List containing family validation schema and PFR base schema.

classmethod get_validation_schemas_from_cfg(config)#

Get validation schemas based on configuration.

If the class doesn’t behave generally, just override this implementation. The method validates the configuration against basic schemas, extracts family and area information, and returns appropriate validation schemas for the specific IFR/PFR class.

Parameters:: config (Config) – Valid configuration object containing family and type information.
Return type:: list[dict[str, Any]]
Returns:: List of validation schema dictionaries for the specified area and family.

classmethod load_from_config(config)#

Load configuration area from PFR configuration.

Creates a BaseConfigArea object based on the provided configuration, including family revision, settings, and optional additional data that can be loaded from file or provided as hex string.

Parameters:: config (Config) – PFR configuration containing type, settings and optional additional data.
Return type:: Self
Returns:: Configured BaseConfigArea object of the appropriate type.
Raises:: SPSDKError – When additional_data cannot be loaded from file or parsed as hex.

classmethod parse(data, family=None)#

Parse input binary data to registers.

The method parses binary data into PFR registers and handles additional data if present and enabled for the specified MCU family.

Parameters:

data (bytes) – Input binary data of PFR block.
family (Optional[FamilyRevision]) – The MCU family name.

Raises:

SPSDKPfrError – When family parameter is not provided.

Return type:

Self

Returns:

The PFR initialized class.

static pfr_reg_inverse_high_half(val)#

Inverse low 16-bits of register value to high 16 bits.

The function takes the lower 16 bits of the input value, inverts them bitwise, and places the result in the upper 16 bits while preserving the original lower 16 bits.

Parameters:: val (int) – Input register value to process.
Return type:: int
Returns:: Complete register value with inverted lower bits in upper half.

static pfr_reg_inverse_lower_8_bits(val)#

Inverse lower 8 bits of register value and place result in bits 8-15.

This function takes the lower 8 bits of the input value, performs bitwise inversion, and places the inverted bits in positions 8-15 while preserving other bits.

Parameters:: val (int) – Input register value to process.
Return type:: int
Returns:: Complete register value with inverted lower 8 bits placed in bits 8-15.

set_config(cfg)#

Set a new values configuration.

The method loads configuration into registers and automatically computes any missing bitfield values using predefined computation methods. If a register is used in configuration but some computed bitfields are not specified, those bitfields will be automatically calculated and a warning will be logged.

Parameters:: cfg (Config) – Registers configuration containing register and bitfield definitions.
Return type:: None

class spsdk.pfr.pfr.CFPA(family)#

Bases: BaseConfigArea

Customer In-Field Programmable Area configuration manager.

This class manages the Customer In-Field Programmable Area (CFPA) configuration data for NXP MCU devices, providing functionality to handle customer-specific programmable settings that can be modified in the field.

Variables:

SUB_FEATURE – Identifier for the CFPA sub-feature.
DESCRIPTION – Human-readable description of the configuration area.

Initialize PFR instance for specified device family.

Sets up the database connection, loads device-specific registers, and initializes internal data structures for Protected Flash Region operations.

Parameters:

family (FamilyRevision) – Device family to use, list of supported families is available via ‘get_supported_families’ method

Raises:

SPSDKError – When no device is provided
SPSDKError – When device is not supported

DESCRIPTION = 'Customer In-field Programmable Area'#

SUB_FEATURE: Optional[str] = 'cfpa'#

class spsdk.pfr.pfr.CMPA(family)#

Bases: BaseConfigArea

Customer Manufacturing Configuration Area.

This class represents the Customer Manufacturing Programmable Area (CMPA) which is a specific configuration area used for manufacturing-related settings and parameters in NXP MCU devices.

Variables:

SUB_FEATURE – Identifier for the CMPA sub-feature.
DESCRIPTION – Human-readable description of the programmable area.

Initialize PFR instance for specified device family.

Sets up the database connection, loads device-specific registers, and initializes internal data structures for Protected Flash Region operations.

Parameters:

family (FamilyRevision) – Device family to use, list of supported families is available via ‘get_supported_families’ method

Raises:

SPSDKError – When no device is provided
SPSDKError – When device is not supported

DESCRIPTION = 'Customer Manufacturing Programmable Area'#

SUB_FEATURE: Optional[str] = 'cmpa'#

Protected Flash Region Checker for brick-conditions#

SPSDK PFR processor for handling conditional rules and transformations.

This module provides functionality for processing and transforming conditional rules in PFR (Protected Flash Region) context. It includes AST-based code transformation capabilities and rule processing logic.

class spsdk.pfr.processor.Processor(translator)#

Bases: object

SPSDK condition processor for PFR operations.

This class processes conditional expressions by parsing condition strings, transforming register keys through a translator, and evaluating the results. It handles the conversion of condition expressions into executable code while maintaining proper logging and formatting of numeric values.

Initialize processor with translator instance.

Parameters:: translator (Translator) – Translator instance used for processing operations.

process(condition)#

Process individual condition from rules.

The method parses and evaluates a condition string using AST transformation, converting it to executable code and returning both the boolean result and the transformed condition string with translated keys.

Parameters:: condition (str) – Condition string to parse and evaluate.
Return type:: tuple[bool, str]
Returns:: Tuple containing boolean evaluation result and transformed condition string.

SPSDK PFR configuration translator utilities.

This module provides functionality for translating stringified configuration keys into their corresponding values for PFR (Protected Flash Region) operations. The Translator class handles conversion between human-readable configuration parameters and their binary representations used in CFPA and CMPA structures.

class spsdk.pfr.translator.Translator(cmpa=None, cfpa=None)#

Bases: object

PFR register and key value translator.

This class provides translation services for converting string-based register and key names into their corresponding numeric values. It supports CMPA and CFPA configuration data translation through dedicated handlers for different areas.

Initialize CMPA and CFPA data.

Parameters:

cmpa (Optional[CMPA]) – Configuration data loaded from CMPA config file.
cfpa (Optional[CFPA]) – Configuration data loaded from CFPA config file.

translate(key)#

Translate register or generic key to its corresponding value.

The method parses the key by splitting on the first dot to separate area and value designators, then uses the appropriate handler to retrieve the value.

Parameters:: key (str) – Register or key name in format “area.value” (e.g., “CFPA.BOOT_CFG”).
Return type:: int
Returns:: Translated integer value for the given key.
Raises:: SPSDKPfrcTranslationError – When configuration for given key is not defined.

PFR Exceptions#

SPSDK PFR (Protected Flash Region) exception classes.

This module defines custom exception classes for handling errors specific to PFR operations, including configuration errors, validation failures, and missing component errors.

exception spsdk.pfr.exceptions.SPSDKPfrConfigError(desc=None)#

Bases: SPSDKPfrError

PFR configuration error exception.

This exception is raised when there are issues with PFR (Protected Flash Region) configuration data, such as invalid parameters, malformed configuration files, or configuration validation failures.