PRA (Protected Register Access)

General Description

Note

The Protection Register Access (PRA) driver is intended for the PSoC 64 devices only and provides other PDL drivers access to the registers that have secure access restrictions. It is not intended to be used directly by user application.

The PRA driver is used to protect the system from invalid configurations that could potentially cause the system to be unstable or indirectly allow access to registers and memory that are protected. This is done using several methods:

• Allow only valid register settings.
• Force a specified sequence of operations when writing to a register.
• Totally block access to registers that are deemed critical to security.
• Allow only known, well defined system configurations.

• Allow access to non-critical registers that are protected by a fixed PPU.

  On PSoC 64 devices, secure firmware protects entire regions of registers with the fixed PPUs, however there are some registers within that regions that should not be protected but, are protected due to fixed PPU granularity.

  The list of the registers that can be accessed by PRA driver directly is defined in the cy_pra.h file with the CY_PRA_INDX_ prefix.

Most PDL drivers are not affected or use the PRA driver. Only the following PDL drivers are affected by this driver:

• LVD (Low-Voltage-Detect)
• SysLib (System Library)
• SysClk (System Clock)
• SysPm (System Power Management)
• SysTick (Arm® System Timer)
• WDT (Watchdog Timer)
• Flash (Flash System Routine)
• SysInt (System Interrupt) (PSoC 64 CYB06xx7 devices only)
• Prot (Protection Unit) (PSoC 64 CYB06xx7 devices only)
• GPIO (General Purpose Input Output)

The execution time of the functions that access the protected registers is increased on the PSoC 64 devices because the access is performed on Cortex-M0+ via the IPC command (both CPU cores run at 8 MHz):

• The access to the protected register may take about 50 us, while access to the unprotected one may take about 3 us.
• The initial device configuration may take up to 1.75 ms for PSoC 64 devices, while for the other devices it may take about 0.3 ms.
• The transition Active to DeepSleep to Active may take about 2 times longer.

Basic Operation

The PRA driver uses an IPC channel to transfer register data between the user application running on the Cortex-CM4 and the secure Cortex-CM0+ CPU. The secure processor performs the data validation and correct register write sequence to ensure proper stable operation of the system. Function status and requested data is also returned via the IPC channel.

The PDL driver that accesses protected registers, generates request to the PRA driver and it passes request over the IPC to secure Cortex-M0+, where request is validated and executed, and, then, reports result back to the driver on Cortex-M4 side.

Device Configuration

For PSoC 64 device, device configuration (like system clock settings and power modes) is applied on the secure Cortex-M0+. The device configuration can be initiated from either of the core or both the cores. The device configuration structure cy_stc_pra_system_config_t is initialized with Device Configurator. For Cortext-M4 application, it passed to the secure Cortex-M0+ core through IPC for validation and register the update in the cybsp_init() function. For Cortext-M0+ application, this device configuration structure is directly validated and applied.

Note

The external clocks (ECO, WCO, and EXTCLK) require additional configuration to be allowed to source CLK_HF0 (clocks both Cortex-M0+ and Cortex-M4 CPUs) in order to prevent clock tampering. See External Clock Sources for details.

The ALTHF (BLE ECO) is not allowed to source CLK_HF0 (clocks both Cortex-M0+ and Cortex-M4 CPUs) in order to prevent clock tampering.

The internal low-frequency clocks (ILO and PILO) are not allowed to source the CLK_HF0 directly and through PLL or FLL.

The clock source for Cortex-M4 SysTick cannot be configured with the Device Configurator. Enabling CLK_ALT_SYS_TICK will result in a compilation error. SysTick still can be configured in run-time with some limitations. For more details, refer to Cy_SysTick_SetClockSource() in SysTick (Arm® System Timer).

When EXT_CLK is source to HF0 then the drive mode for EXT_CLK pin is hard coded to CY_GPIO_DM_HIGHZ. So user has to make sure this pin configuration is not overwritten from secure application.

External Clock Sources

The PSoC 64 devices must be provisioned with the external clocks (ECO, WCO, and EXTCLK) configuration before routing these clocks to CLK_HF0. To do that, update the JSON file (delivered with CySecureTools) with the "extclk" node in the custom data section as shown below. The configuration fields in the JSON file match the fields in the Device Configurator.

For more details, refer to the PSoC 64 Secure MCU Secure Boot SDK User Guide.

For EXTCLK:
    "custom_data_sections": ["extclk"],
    "extclk": {
            "extClkEnable": 1,
            "extClkFreqHz": 24000000,
            "extClkPort": 0,
            "extClkPinNum": 0,
            "extClkHsiom": 0
    }

For ECO:
    "custom_data_sections": ["extclk"],
    "extclk": {
            "ecoEnable": 1,
            "ecoFreqHz": 24000000,
            "ecoLoad": 18,
            "ecoEsr": 50,
            "ecoDriveLevel": 100,
            "ecoInPort": 12,
            "ecoOutPort": 12,
            "ecoInPinNum": 6,
            "ecoOutPinNum": 7,
    }

For WCO:
    "custom_data_sections": ["extclk"],
    "extclk": {
            "wcoEnable": 1,
            "bypassEnable": 0
            "wcoInPort": 0,
            "wcoOutPort": 0,
            "wcoInPinNum": 0,
            "wcoOutPinNum": 1
    }

Note

The same "extclk" section is used for all external clocks. If more than one external clock source is required, please append its parameters.

SRAM Power Mode Configurations

The PSoC 64 devices must be provisioned with the SRAM power mode configuration to protects secure core memory. To do that, update the JSON file (delivered with CySecureTools) with the "srampwrmode" node in the custom data section as shown below.

For more details, refer to the PSoC 64 Secure MCU Secure Boot SDK User Guide.

"custom_data_sections": ["srampwrmode"],
"sram0": [
    {
        "macroNum": 1,      // bits 0
        "powerMode": 6,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF
    },
    {
        "macroNum": 2,      // bits 1
        "powerMode": 1,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF
    },
    {
        "macroNum": 65532,  // bits [15-2] = 0xFFFC
        "powerMode": 7,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF
    }
],
"sram1": [
    {
        "macroNum": 1,      // bit 0
        "powerMode": 7,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF
    }
],
"sram2": [
    {
        "macroNum": 1,      // bit 0
        "powerMode": 7,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF
    }
]

Note

If a particular configuration(either SRAM or macro section) is not present in the policy file but available in the device then SRAM MACRO can be allowed to be modified to any of power modes (ON, RETAIN and OFF).

Using without BSPs

If PDL is used in Standalone mode without Board Support Package (BSP), do the following:

• 1) Call the Cy_PRA_Init function prior to executing API of any of the drivers listed above. By default, this function is called from SystemInit on both CPU cores.
• 2) Call the Cy_PRA_SystemConfig function with the initial device configuration passed as a parameter. Refer to Section "Function Usage" of the Cy_PRA_SystemConfig function for more details.

More Information

See the device technical reference manual (TRM) reference manual (TRM) for the list of the protected registers.

Changelog

Version	Changes	Reason for Change
2.40.1	Coverity errors fixed.	Bug fixes.
2.40	Initialize internal data structure to initial values when external clock policy pointer is NULL to avoid null pointer de-referencing.	Defect fix.
2.30	System Configuration can be done from CM0+ using PRA API with CY_PRA_MSG_TYPE_SYS_CFG_FUNC and CY_PRA_FUNC_INIT_CYCFG_DEVICE arguments.	Enhancement based on customer feedback.
	System configuration structure is updated with appropriate value, when cm0+ application calls any PDL API accessing to FUNCTION_POLICY registers.	Enhancement based on customer feedback.
	Fixed MISRA 2012 violations.	MISRA 2012 compliance.
	Updated doxygen for External clock source to HF0.	Documentation enhancement.
2.20	Allowing external clocks (EXT_CLK, ECO and WCO) can be source to secure core. Provide interface for validating and configuring SRAM power modes.	External clock support and SRAM power mode configuration support.
2.10	Removed include of cy_gpio.h from the driver's c source files. Added some source code comments.	Source code cleanup.
	Updated attribute usage for the linker section placement.	Enhancement based on usability feedback.
	Fixed MISRA 2012 violations.	MISRA 2012 compliance.
2.0	Added PSoC 64 CYB06xx7 devices support.	New devices support.
	Updated Cy_PRA_Init() to compare the major and minor version of the PRA driver on the Cortex-M0+ and Cortex-M4 sides and halt Cortex-M4 if the versions are different.	Ensure that the same PRA driver version is used on the Cortex-M0+ and Cortex-M4 sides.
	Fixed the location of the cy_stc_pra_system_config_t description in the documentation.	Documentation update.
	Corrected the reference to the SysTick (Arm® System Timer) function with the limitation description - Cy_SysTick_SetClockSource().	Documentation update.
	The state of the following clocks changes only when the requested state differs from the actual state in the hardware: HF1-HF5, TIMER, PUMP, BLE_ECO, ILO, PILO, and WCO.	Improved the Cy_PRA_SystemConfig() function execution time.
	Renamed altHfFreq to altHFclkFreq in cy_stc_pra_system_config_t.	Eliminated the naming conflict with the SysClk driver.
1.0	Initial version

API Reference
	Macros
	Functions
	Enumerated Types
	Data Structures