4.22.2.3. TIFS safety checker¶

4.22.2.3.1. Introduction¶

TIFS Safety Checkers (TIFS-SC) library APIs can be used to get the firewall configuration and validate the same against the golden reference. The TIFS-SC has two stages, namely generation of firewall config and validation of firewall config. The SafetyCheckersApp_tifs demonstrates the usage of TIFS-SC library APIs.

To generate the firewall config, the user needs to first update the BoardCfg with the necessary values so that the TIFS will open the firewalls for the Safety host. The steps to do so are captured in the ‘Important Usage Guidelines’ section.

Once the BoardCfg is updated and the binaries are built, 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.

The complete list of permitted firewalls for a supported SOC can be found in ‘tifs_checkers_fwl_config.h’ present in the corresponding ‘soc’ folder of the TIFS-SC example. The user can modify the list based on which firewall ids need to be monitored. The safety checker iterates over the number of regions ‘numRegions’ specified in the tifs_checkers_fwl_config to generate the corresponding firewall config for a given firewall.

This list is used as input to ‘SafetyCheckers_tifsGetFwlCfg’ API along with it’s size to generate the static firewall configuration. The Safety application then validates the generated firewall configuration and saves it as a Golden Reference in non-volatile memory. This completes stage 1.

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.

The tifs_checkers_fwl_config.h can be regenerated using the Python script found under ‘safety_checkers/utils/tifs_checkers_create_fwl_config.py’. The script uses a CSL file as input and generates the complete list of permitted firewalls for a given SoC.

In the validate phase, the Safety application provides the Golden Reference to the safety checker using the ‘SafetyCheckers_tifsVerifyFwlCfg’ API. The checker then the validates runtime firewall registers against the Golden Reference at defined intervals in a Safety Loop. The API return status indicates if there was a mismatch with the Golden Reference for any of the firewall ids. Finally the application must call ‘tifsReqFwlClose’ to request TIFS to close the firewall register space.

4.22.2.3.2. Features Supported¶

The module supports below API’s for the application

API to request TIFS to open firewall.

API to generate Golden Reference using the list of firewall registers specified.

API compares the Golden Reference with runtime firewall register values and return success or failure.

API to request TIFS to close firewall.

4.22.2.3.3. Important Usage Guidelines¶

Steps to update board configuration for TIFS Safety Checkers:

Add below lines to the file ” ${mcu_plus_sdk}/source/drivers/sciclient/sciclient_default_boardcfg/{board}/sciclient_defaultBoardcfg_security.c”:

/* SA2UL RM config */
.sa2ul_auth_cfg = {
  .subhdr = {
      .magic = TISCI_BOARDCFG_SA2UL_CFG_MAGIC_NUM_RSVD,
      .size = 0,
  },
  .auth_resource_owner = 0,
  .enable_saul_psil_global_config_writes = 0x5A,
  .safety_host_present = 0x5A,
  .safety_host = host_id
},

Note

host_id = 0x4

Use the following commands to build the Boardcfg changes:

  cd pdk/packages/ti/build

For GP and HS-FS::

  make sciclient_boardcfg BOARD=device_name
  make all BOARD=device_name

For HS-SE::

 make sciclient_boardcfg_hs BOARD=device_name
 make all BOARD=device_name

4.22.2.3.4. APIs¶

TIFS Safety Checker (TIFS-SC) provides APIs to read the firewall configuration registers and validate the firewall configuration against the Golden Reference.

1. SafetyCheckers_tifsReqFwlOpen(void)

API to request TIFS to open firewall.

Returns :

status SAFETY_CHECKERS_SOK : Success, SAFETY_CHECKERS_FAIL: Failure

2. SafetyCheckers_tifsGetFwlCfg(SafetyCheckers_TifsFwlConfig * fwlConfig, uint32_t size)

API uses the pointer to firewall configuration fwlConfig as input and updates fwlConfig with the register dump of the firewall registers specified.

Parameters :

fwlConfig   [IN/OUT] Pointer to static firewall configuration to be populated with register values
size          [IN]   Number of entries in the static firewall configuration

Returns :

status SAFETY_CHECKERS_SOK : Success, SAFETY_CHECKERS_FAIL: Failure

3. SafetyCheckers_tifsVerifyFwlCfg(const SafetyCheckers_TifsFwlConfig * fwlConfig,uint32_t size)

API compares the fwlConfig (golden reference) with runtime firewall register values and return success or failure.

Parameters :

fwlConfig   [IN/OUT] Pointer to static firewall configuration / Golden Reference to be verified against
size          [IN]   Number of entries in the static firewall configuration

Returns :

status SAFETY_CHECKERS_SOK : Success, SAFETY_CHECKERS_FAIL: Failure

4. SafetyCheckers_tifsReqFwlClose(void)

API to request TIFS to close firewall.

Returns :

status SAFETY_CHECKERS_SOK : Success SAFETY_CHECKERS_FAIL: Failure

4.22.2.3.5. Example Usage¶

The following shows an example of TIFS Safety Checkers API usage

Include the below file to access the APIs:

#include "../../src/safety_checkers_tifs.h"

Request the TIFS to open firewall:

SafetyCheckers_tifsReqFwlOpen();

Uses the pointer to firewall configuration pFwlConfig as input and updates pFwlConfig with the register dump of the firewall registers specified:

SafetyCheckers_tifsGetFwlCfg(pFwlConfig, gSize);

Verify and save firewall configuration as Golden Reference

Compare the golden reference with runtime firewall register values and return success or failure:

while (i > 0)
{
   status = SafetyCheckers_tifsVerifyFwlCfg(pFwlConfig, gSafetyCheckersTifsCfgSize);

   if (status == SAFETY_CHECKERS_REG_DATA_MISMATCH)
   {
      SAFETY_CHECKERS_log("\n Firewall register mismatch with Golden Reference !!\r\n");
   }

   SafetyCheckersApp_softwareDelay();
   i--;
}
if (status == SAFETY_CHECKERS_SOK)
{
   SAFETY_CHECKERS_log("\n No firewall register mismatch with Golden Reference \r\n");
}

Request the TIFS to close firewall:

SafetyCheckers_tifsReqFwlClose();

4.22.2.3.6. Sample Output¶

Firewall open successful
Get firewall configuration successful
No firewall register mismatch with Golden Reference
Firewall close successful