5.25.3.1.1. Safety checkers app

5.25.3.1.1.1. Introduction

Safety checkers library APIs are integrated into the boot_app application for the PM, RM and TIFS modules. The Boot App is a tertiary bootloader booted by the SBL. It runs on mcu1_0, from which it boots other cores in different stages. The Safety loop API is executed as a part of Boot app application after all the boot_app instructions are executed. Here, the safety loop obtains the register configurations for PM, RM and TIFS modules and saves them as a golden reference which then validates the current configuations against golden reference.

Modules supported by safety checker library:

1. PM (Power Management)

2. RM (Resource Management)

3. TIFS (Texas Instruments Foundational Security)

The PM Safety Checkers (PM-SC) library APIs shall be used to obtain the PSC/PLL register configurations and validate the current PSC/PLL configurations against the golden reference.

The RM Safety Checkers (RM-SC) library APIs shall be used to obtain the RM modules register configurations (i.e., IR, IA-IMAP, Ring Accelerator, and DMA modules) and validate the current RM modules configurations against the golden reference.

The TIFS Safety Checkers (TIFS-SC) library APIs shall be used to obtain the firewall configuration and validate it against the golden reference. The TIFS-SC operates in two stages: generating the firewall configuration and validating it. To generate the firewall configuration, the Safety application needs to call ‘tifsReqFwlOpen’ to request TIFS to open the firewall register space. The application then sends a list of firewall IDs that are to be monitored in the Safety Loop.

5.25.3.1.1.2. Safety Loop

The BootApp_safetyCheckerLoop API demonstrates the usage of RM, PM, and TIFS safety checker APIs. This includes obtaining the register configurations for PM/RM/TIFS and validating them with the current configurations against the golden reference.

1. Get register configurations

As the register configuration dump is taken for specific module and considered as the golden sample, it should serve as a reference during the execution of the safety loop. Therefore, no configurations should be performed during the execution of the safety loop. If the boot_app application runs with the SC_REGDUMP_ENABLE flag enabled, it provides the register configuration of the requested modules and saves it to a header file, which should be treated as the golden reference.

2. Validate register configurations

Once the golden dump is taken and saved, the current register configurations shall be validated against the golden dump. Therefore SC_REGDUMP_ENABLE flag shall be disabled, to validate the current register configurations with the saved golden reference.

Below are the modules added to get and validate the register configuations:

1. PSC and PLL register configurations for PM module.

2. IR, IA-IMAP, Ring Accelerator and DMA register configuations for RM module.

3. Firewall register configurations for TIFS module.

Each of these configurations shall be validated using the Golden Reference.

5.25.3.1.1.3. Steps to build and execute safety loop

Below are the steps to be followed for the execution of safety Loop from the Boot App via MMCSD

Note

Saving Golden Dump step shall be done whenever user needs to generate the new golden reference. The generated file shall be treated as golden reference.

Saving Golden Dump :

1. Generate lateapps by using the following commands

   • goto <PDK>/packages/ti/boot/sbl/build/boot_app.mk file

   • Enable CFLAGS_LOCAL_COMMON += -DSC_REGDUMP_ENABLE flag

   • goto <PDK>/packages/ti/boot/sbl/example/boot_app/scripts

   • Run ./generate_lateapps.sh <board_name>

   • Multicore images(lateapps) will be generated in <PDK>/packages/ti/boot/sbl/example/boot_app/multicore_images/$BOARD/.

   • Stage1 image corresponds to lateapp1, stage2 image corresponds to lateapp2 and stage3 image corresponds to lateapp3.

2. Copy sbl_mmcsd_img_mcu1_0_release.tiimage as tiboot3.bin to the boot partition of SD card

3. Copy tifs.bin to the boot partition of SD card

4. Build boot_app_mmcsd_safety by using the following command

   • make BOARD=<board_name> CORE=mcu1_0 boot_app_mmcsd_safety -sj

5. Copy boot_app_mmcsd_safety_<board_name>_mcu1_0_freertos_release.appimage image as app to the boot partition of SD card

6. Copy stage1 image as lateapp1, stage2 image as lateapp2 and stage3 image as lateapp3 to the boot partition of SD card

7. Generate register configurations and saving as golden reference.

   • goto <PDK>/packages/ti/boot/sbl/example/boot_app/scripts

   • Update the mcu serial port in generate_safetyCheckers_regCfg.py file if mcu serial port changes from /dev/ttyUSB1

   • Run python generate_safetyCheckers_regCfg.py <board_name>

8. Do not open the terminal for logging as the port shall be opened by the python script running.

9. Boot with the SD card, python script opens the terminal and the logs shall be displayed there.

10. The register configuations shall be saved to a file <PDK>/packages/ti/boot/sbl/example/boot_app/soc/<board>/safety_checkers_regcfg.h

Execution of safety loop :

1. Generate lateapps by using the following command

   • goto <PDK>/packages/ti/boot/sbl/build/boot_app.make file

   • Disable #CFLAGS_LOCAL_COMMON += -DSC_REGDUMP_ENABLE flag.

   • goto <PDK>/packages/ti/boot/sbl/example/boot_app/scripts

   • Run ./generate_lateapps.sh <board_name>

   • Multicore images(lateapps) will be generated in <PDK>/packages/ti/boot/sbl/example/boot_app/multicore_images/$BOARD/.

   • Stage1 image corresponds to lateapp1, stage2 image corresponds to lateapp2 and stage3 image corresponds to lateapp3.

2. Copy sbl_mmcsd_img_mcu1_0_release.tiimage as tiboot3.bin to the boot partition of SD card

3. Copy tifs.bin to the boot partition of SD card

4. Build boot_app_mmcsd_safety by using the following command

   • make BOARD=<board_name> CORE=mcu1_0 boot_app_mmcsd_safety -sj

5. Copy boot_app_mmcsd_safety_<board_name>_mcu1_0_freertos_release.appimage image as app to the boot partition of SD card

6. Copy stage1 image as lateapp1, stage2 image as lateapp2 and stage3 image as lateapp3 to the boot partition of SD card

7. Keep the board in SD boot and boot with the SD card.

5.25.3.1.1.4. Example Usage

The following shows an example of Safety Checker APIs usage

APIs to get PM Checkers Register Configuration:

SafetyCheckers_pmGetPscRegCfg(pscRegisterData, SAFETY_CHECKERS_PM_PSC_REGDUMP_SIZE);
SafetyCheckers_pmGetPllRegCfg(pllRegisterData, SAFETY_CHECKERS_PM_PLL_REGDUMP_SIZE);

API to get RM Checkers Register Configuration:

SafetyCheckers_rmGetRegCfg(rmRegisterData, SAFETY_CHECKERS_RM_REGDUMP_SIZE);

API to request the TIFS to open firewall:

SafetyCheckers_tifsReqFwlOpen();

API to get TIFS Checkers Register Configuration:

SafetyCheckers_tifsGetFwlCfg(pFwlConfig, gSafetyCheckersTifsCfgSize);

Verify the run time register configuration against the golden reference for each of the checkers

numInt = 10;
while (numInt > 0)
{
   if (gtimerIsrCount == 1)
   {
      gtimerIsrCount = 0U;
      /* validate PSC register config with current value */
      retVal = SafetyCheckers_pmVerifyPscRegCfg(pm_pscRegCfg, SAFETY_CHECKERS_PM_PSC_REGDUMP_SIZE);
      if(retVal == CSL_PASS)
      {
          /* validate PLL register config with current value */
          retVal = SafetyCheckers_pmVerifyPllRegCfg(pm_pllRegCfg, SAFETY_CHECKERS_PM_PLL_REGDUMP_SIZE);
      }
      if(retVal == CSL_PASS)
      {
          /* validate RM register config with current value */
          retVal = SafetyCheckers_rmVerifyRegCfg(rm_regCfg, SAFETY_CHECKERS_RM_REGDUMP_SIZE);
      }
      if(retVal == CSL_PASS)
      {
          retVal = SafetyCheckers_tifsReqFwlOpen();
          /* validate TIFS FW register config with current value */
          retVal = SafetyCheckers_tifsVerifyFwlCfg(tifs_fwlConfig, TIFS_CHECKER_FWL_MAX_NUM);
      }
      if(retVal == CSL_PASS)
      {
          retVal = SafetyCheckers_pmRegisterLock();
      }
      if(retVal != CSL_PASS)
      {
          TimerP_stop(handle);
          break;
      }
      numInt--;
   }
}

API to request the TIFS to close firewall:

SafetyCheckers_tifsReqFwlClose();

5.25.3.1.1.5. Booting in HS devices

1. To boot the boot app on HS devices add _hs while building boot app image i.e boot_app_mmcsd_hs or boot_app_ospi_hs.

2. Use .appimage.signed images instead of .appimage for HS devices.