4.25.2.4. CSIRX safety checker

The CSIRX Safety Checker is designed to ensure the integrity of register configurations within the Camera Serial Interface (CSIRX) module. The Safety Application utilizes the Safety Checker APIs, to manage configuration registers. These APIs involve reading the configuration data, and periodically validating the configuration to ensure it remains unchanged.

4.25.2.4.1. Introduction

CSIRX safety checker library APIs are integrated into the safety application to verify the various CSIRX module configurations and validate the current configurations against golden reference.

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

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

  2. When invoking the configuration register read APIs, it collects the corresponding configuration for corresponding MMR block. 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.

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

  2. When invoking the verification APIs, it collects the current configuration for corresponding MMR block. Subsequently, it compares this configuration with the received register configuration.

  3. 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 CSIRX module, the safety checker API monitors the following configuration registers:

  1. Stream control registers

  2. Virtual Channel configuration registers

  3. DPHY config registers

  4. DPHY PLL registers

  5. DPHY Lane configuration registers

  6. Data type & Framesize configuration registers

  7. VIM registers for CSIRX

  8. QoS configuration registers

  9. Sensor configuration registers

Checkers also provide API to verify if the provided configuration of framesize and fps is within the bandwidth limits of CSIRX.

Golden reference should be generated offline. This is achieved by calling the 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 register 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:

  1. Memory allocated for golden register reference shall be firewall protected

  2. Implement appropriate MPU configurations to isolate safety application memory from other applications

  3. Implement a watchdog timeout for safety checker API handling

4.25.2.4.1.1. Read the configuration data for CSIRX module registers

The first step involves reading the configuration registers of CSIRX module. This initialization step is performed once at the start of the safety loop. Call the 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 CSIRX, utilize the following APIs to read the configuration registers:

  1. SafetyCheckers_csirxGetRegCfg

  2. SafetyCheckers_csirxGetVimCfg

  3. SafetyCheckers_csirxGetSensorCfg

  4. SafetyCheckers_csirxGetQoSCfg

../../_images/CSIRX_regRead.png

4.25.2.4.1.2. Saving as Golden Reference

After the Safety Application reads the configuration registers for CSIRX 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.

After saving the register configurations into a header file, the user shall call the 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 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.25.2.4.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 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 CSIRX, utilize the following APIs to verify the current PSC and PLL configuration registers:

  1. SafetyCheckers_csirxVerifyRegCfg

  2. SafetyCheckers_csirxVerifyVimCfg

  3. SafetyCheckers_csirxVerifySensorCfg

  4. SafetyCheckers_csirxVerifyQoSCfg

../../_images/CSIRX_regValidate.png

4.25.2.4.1.4. Features Supported

The CSIRX safety checker module supports below API’s for the application APIs to read and Verify the following configuration registers of CSIRX:

  1. Stream control registers

  2. Virtual Channel configuration registers

  3. DPHY config registers

  4. DPHY PLL registers

  5. DPHY Lane configuration registers

  6. Data type & Framesize configuration registers

  7. VIM registers for CSIRX

  8. QoS configuration registers

  9. Sensor configuration registers

API to verify if the provided configuration of framesize and fps is within the bandwidth limits of CSIRX.

4.25.2.4.2. APIs

1. SafetyCheckers_csirxGetRegCfg(uintptr_t *regCfg, uint32_t regType, uint32_t instance)

API to get register configuration of regType registers of CSIRX instance instance Based on the regType input, one of the following registers are read and copied to the array regCfg

  1. SAFETY_CHECKERS_CSIRX_REG_TYPE_STRM_CTRL

  2. SAFETY_CHECKERS_CSIRX_REG_TYPE_DPHY_CONFIG

  3. SAFETY_CHECKERS_CSIRX_REG_TYPE_DPHY_PLL

  4. SAFETY_CHECKERS_CSIRX_REG_TYPE_DPHY_LANE_CONFIG

  5. SAFETY_CHECKERS_CSIRX_REG_TYPE_VIRTUAL_CHANNEL

  6. SAFETY_CHECKERS_CSIRX_REG_TYPE_DATATYPE_FRAMESIZE

This regCfg can be used as the golden reference in the safety loop.

Parameters :

regCfg      Pointer to register configuration
regType     Type of register configuration
instance    CSIRX instance ID

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed

2. SafetyCheckers_csirxVerifyRegCfg(const uintptr_t *regCfg, uint32_t regType, uint32_t instance);

API to get register configuration of regType registers of CSIRX instance instance Based on the regType input, one of the following registers are verified with the array regCfg

  1. SAFETY_CHECKERS_CSIRX_REG_TYPE_STRM_CTRL

  2. SAFETY_CHECKERS_CSIRX_REG_TYPE_DPHY_CONFIG

  3. SAFETY_CHECKERS_CSIRX_REG_TYPE_DPHY_PLL

  4. SAFETY_CHECKERS_CSIRX_REG_TYPE_DPHY_LANE_CONFIG

  5. SAFETY_CHECKERS_CSIRX_REG_TYPE_VIRTUAL_CHANNEL

  6. SAFETY_CHECKERS_CSIRX_REG_TYPE_DATATYPE_FRAMESIZE

Parameters :

regCfg      Pointer to register configuration
regType     Type of register configuration
instance    CSIRX instance ID

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed SAFETY_CHECKERS_REG_DATA_MISMATCH if verification is failed

3. SafetyCheckers_csirxVerifyCsiAvailBandwidth(void *drvHandle, uint32_t fps)

API to verify if the provided configuration of framesize and fps is within the bandwidth limits of CSIRX IP. This API will extract the creteparams from drvHandle provided and calculates the bandwidth required for given fps and verifies if IP bandwidth limits are exceeded.

Parameters :

drvHandle   Fvid2 driver handle for CSIRX
vimCfg      Pointer to vim register configuration

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed

4. SafetyCheckers_csirxGetVimCfg(void *drvHandle, SafetyCheckers_CsirxVimCfg *vimCfg)

API to read VIM register configuration for events of given CSIRX instance driver handle drvHandle and populates in the provided vimCfg structure. This API verifies if for the given drvHandle , if CSIRX events are registered. If registered, reads VIM configuration for the event and populates the vimCfg structure.

Parameters :

drvHandle   Fvid2 driver handle
vimCfg      Pointer to vim register configuration

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed

5. SafetyCheckers_csirxVerifyVimCfg(void *drvHandle, SafetyCheckers_CsirxVimCfg *vimCfg)

API to verify the given vimCfg with current VIM register configuration of CSIRX event corresponding to drvHandle From drvHandle, this API identifies the CSIRX event registered and gets the VIM configuration of that event and compares with provided vimCfg.

Parameters :

drvHandle   Fvid2 driver handle
vimCfg      Pointer to vim register configuration

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed SAFETY_CHECKERS_REG_DATA_MISMATCH if verification is failed

6. SafetyCheckers_csirxGetSensorCfg(void *i2cHandle, uint32_t slaveAddr, uint16_t (*regData)[3U])

API to get the sensor configuration. i2cHandle is the I2C driver handle, slaveAddr is the I2C address of the sensor and regData is an array with register addresses, data and timeout value for the sensor. for example, regData {{address0, data0, timeout0},{address1, data1, timeout1}….} User should provide address0, address1 ,…etc in the regData structure. This API reads from those addresses and populates the data0, data1…etc fields in the regData

Parameters :

i2cHandle   I2C driver handle to access sensor
slaveAddr   I2C slave address of sensor
regData     Pointer to sensor configuration

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed

7. SafetyCheckers_csirxVerifySensorCfg(void *i2cHandle, uint32_t slaveAddr, uint16_t (*regData)[3])

API to verify the sensor configuration. i2cHandle is the I2C driver handle, slaveAddr is the I2C address of the sensor and regData is an array with register addresses, data and timeout value for the sensor. this API compare the data values in the regData array and reports if there is a mismatch.

Parameters :

i2cHandle   I2C driver handle to access sensor
slaveAddr   I2C slave address of sensor
regData     Pointer to sensor configuration

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed SAFETY_CHECKERS_REG_DATA_MISMATCH if verification is failed

8. SafetyCheckers_csirxGetQoSCfg(SafetyCheckers_CsirxQoSSettings *qosSettings, void *drvHandle)

API to get Quality of Service settings for CSIRX. for the given drvHandle, this API reads the UDMA channel registers, gets the QoS settings and copies into qosSettings

Parameters :

qosSettings Pointer to QoS settings
drvHandle   Fvid2 driver handle

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed

9. SafetyCheckers_csirxVerifyQoSCfg(SafetyCheckers_CsirxQoSSettings *qosSettings, void *drvHandle)

API to verify the QoS settings of CSIRX with the provided qosSettings. This API reads from udma channel registers from drvHandle and verifies with qosSettings.

Parameters :

qosSettings Pointer to QoS settings
drvHandle   Fvid2 driver handle

Returns :

SAFETY_CHECKERS_SOK if successful SAFETY_CHECKERS_FAIL if NULL params are passed SAFETY_CHECKERS_REG_DATA_MISMATCH if verification is failed

4.25.2.4.3. Example Usage

The following shows an example of CSIRX safety checker API usage

An example is included to demonstrate the usage of CSIRX safety checkers.

1. Get configuration APIs

Below APIs are used to get the register configuration:

1.SafetyCheckers_csirxGetRegCfg 2.SafetyCheckers_csirxGetVimCfg 3.SafetyCheckers_csirxGetSensorCfg 4.SafetyCheckers_csirxGetQoSCfg

These APIs are used to generate the golden reference, to be further used in the safety loop.

eg:

status = SafetyCheckers_csirxGetRegCfg(regCfg,
                                       SAFETY_CHECKERS_CSIRX_REG_TYPE_STRM_CTRL,
                                       CSISRX_SAFETY_CHECKERS_APP_INSTANCE_ID );

Here, regType is SAFETY_CHECKERS_CSIRX_REG_TYPE_STRM_CTRL. Hence stream control register configuration is read and populated in regCfg.

2. verify configuration APIs

Below APIs are used to get the register configuration

SafetyCheckers_csirxVerifyRegCfg SafetyCheckers_csirxVerifyVimCfg SafetyCheckers_csirxVerifySensorCfg SafetyCheckers_csirxVerifyQoSCfg

These APIs are used to verify the current configuration with the golden reference.

eg:

status = SafetyCheckers_csirxVerifyRegCfg(regCfg,
                                          SAFETY_CHECKERS_CSIRX_REG_TYPE_STRM_CTRL,
                                          CSISRX_SAFETY_CHECKERS_APP_INSTANCE_ID);

Here, regType is SAFETY_CHECKERS_CSIRX_REG_TYPE_STRM_CTRL. Hence stream control register configuration is read and verified with regCfg.

3. bandwidth limit verification API

Below API is used to verify if the current configuration is within the bandwidth limitations of CSIRX IP.

SafetyCheckers_csirxVerifyCsiAvailBandwidth

eg:

status = SafetyCheckers_csirxVerifyCsiAvailBandwidth(channel , 30);

Here, channel is the Fvid2 driver handle for CSIRX and 30 is the required fps. this API should verify if 30 fps is possible with requested framesize and avialable CSIRX bandwidth.

4.25.2.4.4. CSIRX SAFETY CHECKERS APP

4.25.2.4.4.1. Introduction

CSIRX safety checkers application demonstrates the usage of all the features provided by the CSIRX safety checkers library.

Following are the testcases provided in this application

  1. Get & verify register configuration APIs with possible input parameters.

  2. Verify available CSIRX bandwidth with provided framesize and fps

  3. Negative testcases with NULL parameters to verify error handling

4.25.2.4.4.2. Sample Output

CSIRX_SAFETY_CHECKERS_APP:[Channel No: 0] | Frame Queue Count: 303 | Frame De-queue Count: 303 | Frame Drop Count: 0
CSIRX_SAFETY_CHECKERS_APP: 299 frames captured in 10000 msec at the rate of 29.90 frames/sec.
src/csirx_checkers_app_main.c @ Line 2435: CSIRX_SAFETY_CHECKERS_APP: [ERROR] CSIRX vim configuration validation failed