4.21.2.1. PM safety checker¶

The PM Safety Checker is designed to ensure the integrity of register configurations within the Power Management (PM) module. The Safety Application utilizes the Safety Checker APIs, running in the Safety Core, to manage configuration registers. These APIs involve reading the configuration data, and periodically validating the configuration to ensure it remains unchanged.

4.21.2.1.1. Introduction¶

PM safety checker library APIs are integrated into the safety application to verify the PSC/PLL configurations and validate the current PSC and PLL configurations against golden reference. It also provides the PLL lock API which is responsible for locking a PLL control module registers by preventing the stray writes.

The safety checker register read configurations design follows a generic pattern, applicable to various modules within the system.

To retrieve the configuration of a PM module, a dedicated APIs are provided.

When invoking the configuration register read APIs, it collects the corresponding configuration for devices present on the platform. The collected configuration shall be stored in an memory array.

Similar to the register read process, the verification of register configurations follows a generic approach.

To verify the current register configuration of a PM module, a dedicated verification APIs are provided.

When invoking the verification APIs, it collects the current configuration for devices present on the platform. Subsequently, it compares this configuration with the received register configuration.

The comparison process ensures that any changes between the current configuration and the reference configuration are identified and returns an error message to the application.

For the PM module, the safety checker API monitors the following configuration registers:

PSC config registers

PLL config registers

Upon confirmation of the safety loop, the Safety Application initiates the generation of a golden reference. This is achieved by calling the PSC and PLL register read APIs via the Safety Checker APIs. The retrieved configuration data serves as the benchmark for subsequent validations and is saved for one-time use. Following the establishment of the golden reference, the Safety Application continuously monitors the configuration registers within the safety loop. This is accomplished by calling the PSC and PLL verify APIs at regular intervals. Any deviation from the golden reference receives an error message, signaling potential changes to the configuration.

By adopting this design, the system can efficiently manage and verify the configuration of various modules.

Safety application shall consider below recommendations for robust operation of the safety checker APIs:

Memory allocated for golden register reference shall be firewall protected
Implement appropriate MPU configurations to isolate safety application memory from other applications
Implement a watchdog timeout for safety checker API handling

4.21.2.1.1.1. Read the configuration data for PSC and PLL modules¶

The first step involves reading the configuration registers of PSC and PLL modules. This initialization step is performed once at the start of the safety loop. Call the PSC and PLL read APIs to access the configuration registers via the Safety Checkers APIs running in the Safety Core. This step initializes the Safety Application and gathers the initial configuration data.

For PM, utilize the following APIs to read PSC and PLL configuration registers:

SafetyCheckers_pmGetPscRegCfg

SafetyCheckers_pmGetPllRegCfg

4.21.2.1.1.2. Saving as Golden Reference¶

After the Safety Application reads the configuration registers for PSC and PLL modules using the Safety Checker library API, the configuration data shall be saved as the golden reference. This serves as the benchmark for subsequent validations. This is accomplished by saving the received pointer data to a file. The saved data represents the golden configuration, against which subsequent readings will be compared.

After saving the register configurations into a header file, the user shall call the PSC and PLL verify register config APIs inside the safety loop, passing the register buffer pointer from the saved header file. The user’s application has to be rebuilt with the golden reference array buffer to incorporate the changes in the array buffer. Now, the user application shall include only PSC and PLL modules verify APIs, passing the golden dump array pointer, which will be executed inside the safety loop.

The user should implement firewall based protection for golden reference and also create a checksum for the golden reference to ensure validity of the golden reference data.

Note: This step of reading and saving the configuration data should be done only once, upon freezing the safety loop. The saved data serves as the benchmark for comparison in later validations.

4.21.2.1.1.3. Verify the configuration data for PSC and PLL modules¶

After saving the golden reference, rebuild the application with the golden registers incorporated into it. This ensures that the safety checker verify APIs have access to the correct golden reference for comparison during runtime. Call the PSC and PLL verify APIs which continuously monitor the configuration registers within the safety loop. Verify API compares the current configuration registers against the golden reference to detect any changes. If changes are detected, verify API returns the error message to notify users of potential alterations to the configuration.

For PM, utilize the following APIs to verify the current PSC and PLL configuration registers:

SafetyCheckers_pmVerifyPscRegCfg

SafetyCheckers_pmVerifyPllRegCfg

4.21.2.1.1.4. Features Supported¶

The PM safety checker module supports below API’s for the application

API to get the configurations registers for PSC and PLL control registers.
API to read PLL and PSC registers at run time and validate they are matching with golden state for modules in the safety loop.
API to lock the PLL configuration registers.

4.21.2.1.2. APIs¶

PM Safety Checker (PM-SC) provides APIs to read the PSC / PLL configuration registers and validate the current PSC / PLL configuration against the Golden Reference.

1. SafetyCheckers_pmGetPscRegCfg(uintptr_t * pscRegCfg,uint32_t size)

API to get register configuration for PSC module. E.g. When the PSC register config is requested, SafetyCheckers_pmGetPscRegCfg API collects the PSC configuration for devices present on the given platform. Register configuration includes PDSTAT and MDSTAT register values. The collected configuration will be stored in pscRegCfg array.

Parameters :

pscRegCfg    [IN/OUT] Pointer to store the PSC Register configuration
size       [IN]     Size of register configuration memory

Returns :

SAFETY_CHECKERS_SOK in case of success,else failure.

2. SafetyCheckers_pmVerifyPscRegCfg(const uintptr_t * pscRegCfg,uint32_t size)

API to read back and compares the current register configuration for PSC module. E.g. When the PSC register verify is requested, SafetyCheckers_pmVerifyPscRegCfg API collects the PSC configuration for devices present on the given platform and compares with the received register configuration.

Parameters :

pscRegCfg    [IN/OUT] Pointer to store the PSC golden register configuration
size       [IN]     Size of golden configuration memory

Returns :

SAFETY_CHECKERS_SOK in case of success else failure

3. SafetyCheckers_pmGetPllRegCfg(uintptr_t * pllRegCfg,uint32_t size)

API to get register configuration for PLL module. E.g. When the PLL register config is requested, SafetyCheckers_pmGetPllRegCfg API collects the PLL configuration for devices present on the given platform. Register configuration includes PLL register values. The collected configuration will be stored in pllRegCfg array.

Parameters :

pllRegCfg    [IN/OUT] Pointer to store the PLL Register configuration
size       [IN]     Size of register configuration memory

Returns :

SAFETY_CHECKERS_SOK in case of success else failure

4. SafetyCheckers_pmVerifyPllRegCfg(const uintptr_t * pllRegCfg,uint32_t size)

API to read back and compares the current register configuration for PLL module. E.g. When the PLL register verify is requested, SafetyCheckers_pmVerifyPllRegCfg API collects the PLL configuration for devices present on the given platform and compares with the received register configuration.

Parameters :

pllRegCfg    [IN/OUT] Pointer to store the PLL golden register configuration
size       [IN]     Size of golden configuration memory

Returns :

SAFETY_CHECKERS_SOK in case of success else failure

5. SafetyCheckers_pmRegisterLock(void)

API to lock the PLL control module registers. E.g. When the PLL register lock is requested, SafetyCheckers_pmRegisterLock API performs write operations to KICK registers which prevents the stray writes to PLL control module registers.

Returns :

SAFETY_CHECKERS_SOK in case of success else failure

4.21.2.1.3. Example Usage¶

The following shows an example of PM safety checker API usage

Include the below file to access the PM library APIs:

#include "../../src/safety_checkers_pm.h"

1. PSC read and verify APIs

Below API returns the pscRegCfg with register configuration for PSC module which shall be saved as golden reference:

SafetyCheckers_pmGetPscRegCfg(pscRegCfg, size);

Below API compares the saved pscRegCfg with runtime PSC configuration values and return success or failure:

if(gflag == 1)
{
     gflag = 0;
     retVal = SafetyCheckers_pmVerifyPscRegCfg(pscRegCfg, size);

     if(retVal != 0)
     {
             DebugP_log("Register Mismatch\r\n");
     } else{
             DebugP_log("No Register Mismatch\r\n");
     }
}

2. PLL read and verify APIs Below API returns the pllRegCfg with register configuration for PLL module which shall be saved as golden reference:

SafetyCheckers_pmGetPllRegCfg(pllRegCfg, size);

Below API compares the saved pllRegCfg with runtime PLL configuration values and return success or failure:

if(gflag == 1)
{
     gflag = 0;
     retVal = SafetyCheckers_pmVerifyPllRegCfg(pllRegCfg, size);

     if(retVal != 0)
     {
             DebugP_log("Register Mismatch\r\n");
     } else{
             DebugP_log("No Register Mismatch\r\n");
     }
}

3. PLL lock API Below API locks the PLL control module registers:

if(gflag == 1)
{
     gflag = 0;
     retVal = SafetyCheckers_pmRegisterLock();

     if(retVal != 0)
     {
             DebugP_log("PLL register lock failed\r\n");
     } else{
             DebugP_log("PLL register lock passes\r\n");
     }
}

4.21.2.1.4. PM SAFETY CHECKERS APP¶

4.21.2.1.4.1. Introduction¶

PM Safety Checker (PM-SC) provided APIs which are integrated into the safety application to verify the PSC/PLL configuration and validate the runtime PSC/PLL configuration against golden reference. Also includes the API to lock the PLL control module registers of PM for the prevention of stray writes.

SAFETY_CHECKERS-PM library includes the following implementation:

Reading the configuration registers of PSC/PLL modules.
Validation of current PLL/PSC configuration registers against golden reference.
Locking the PLL control module registers of PM.

This example demonstrates the validation of PM messages by passing the valid and invalid parameters and how to use SAFETY_CHECKERS-PM library APIs.

Below are the cases included in the PM safety example:

Validation of PM messages by using the valid and invalid Device ID. PM messages are listed below:
- TISCI_MSG_SET_DEVICE,
- TISCI_MSG_GET_DEVICE,
- TISCI_MSG_SET_DEVICE_RESETS,
- TISCI_MSG_SET_CLOCK,
- TISCI_MSG_SET_CLOCK_PARENT,
- TISCI_MSG_SET_FREQ,
- TISCI_MSG_GET_CLOCK,
- TISCI_MSG_GET_CLOCK_PARENT,
- TISCI_MSG_GET_NUM_CLOCK_PARENTS,
- TISCI_MSG_QUERY_FREQ,
- TISCI_MSG_GET_FREQ
Validation of PM messages by using the valid and invalid Clock ID. PM messages are listed below:
- TISCI_MSG_SET_CLOCK,
- TISCI_MSG_SET_CLOCK_PARENT,
- TISCI_MSG_SET_FREQ,
- TISCI_MSG_GET_CLOCK,
- TISCI_MSG_GET_CLOCK_PARENT,
- TISCI_MSG_GET_NUM_CLOCK_PARENTS,
- TISCI_MSG_QUERY_FREQ,
- TISCI_MSG_GET_FREQ
Validation of PM messages by using the valid and invalid Device state. PM message is listed below:
- TISCI_MSG_SET_DEVICE
Validation of PM messages by using the valid and invalid Device resets. PM message is listed below:
- TISCI_MSG_SET_DEVICE_RESETS
Validation of PM messages by using the valid and invalid Clock State. PM message is listed below:
- TISCI_MSG_SET_CLOCK
Validation of PM messages by using the valid and invalid Parent Clock. PM message is listed below:
- TISCI_MSG_SET_CLOCK_PARENT
Validation of PM messages by using the valid and invalid Device group. PM message is listed below:
- TISCI_MSG_SYS_RESET
In generation of PSC/PLL config, Safety application shall call the PSC/PLL read APIs to access the configuration registers from the Safety Checkers library running in the Safety Core. Safety checker returns PSC/PLL config to the safety application. Safety application validates the PSC/PLL configuration and save it as a golden reference in a non-volatile memory. This initializes the Safety Application and gathers the initial configuration data.
In validate PSC/PLL config stage, Safety application provides golden reference to the PM safety checker and Safety checker will validates at defined intervals. PM safety checker reads the PSC/PLL registers at runtime and validate they are matching with the golden state for modules in safety loop. Safety checker will return success or failure after validates against the golden reference. The user should implement firewall based protection for golden reference and also create a checksum for the golden reference to ensure validity of the golden reference data.
Addition to the above stages, PLL lock will be called to make sure the PLL configuration registers are not modified.

4.21.2.1.4.2. Sample Output¶

Clock ID boundary validation passed
Clock State boundary validation passed
Device ID boundary validation passed
Device Reset boundary validation passed
Device State boundary validation passed
Parent Clock boundary validation passed
PSC register dump and readback test passed
PLL register dump and readback test passed
PSC and PLL register dump test passed
PLL register Lock test Passed
Device Group boundary validation passed
PM error condition check test Passed
*****   Starting negative test cases   *****
Error: Clock ID boundary validation failed !!!
Error: Clock State boundary validation failed !!!
Error: Device ID boundary validation failed !!!
Error: Device Reset boundary validation failed !!!
Error: Device State boundary validation failed !!!
Error: Parent Clock boundary validation failed !!!
Error: PSC and PLL register dump test failed !!!
Error: PLL register Lock test failed !!!
Ending negative test cases
Time taken for the execution of PSC register dump and readback : 49 usecs
Time taken for the execution of PLL register dump and readback : 56 usecs
Time taken for the execution of PLL register lock : 13 usecs
All tests have PASSED.

4.21.2.1.5. PM SAFETY CHECKERS WARM RESET¶

4.21.2.1.5.1. Introduction¶

This example validates the warm reset API is indeed done. Below are the steps used for the validation of warm reset

Call warm reset function and wait for reset happen; failure if function returns without reset.
Check for the warm reset status in the second execution due to the successful reset. If the status is true return SUCCESS.

4.21.2.1.5.2. Sample Output¶

Sciserver Testapp Built On: Feb  7 2024 10:19:18
Sciserver Version: v2023.11.0.0REL.MCUSDK.MM.NN.PP.bb
RM_PM_HAL Version: vMM.NN.PP
Starting Sciserver..... PASSED
PM Safety Checkers App for Warm Reset Started
Doing MCU warm reset resetSciserver Testapp Built On: Feb  7 2024 10:19:18
Sciserver Version: v2023.11.0.0REL.MCUSDK.MM.NN.PP.bb
RM_PM_HAL Version: vMM.NN.PP
Starting Sciserver..... PASSED
PM Safety Checkers App for Warm Reset Started
MCU reset occured due to warm reset
Warm Reset example Passed