Attention

You are viewing an older version of the documentation. The latest version is v3.3.

Intel® Elkhart Lake Functional Safety (FuSa) Software Package¶

ECI integrates the ‘PV release’ Intel® Elkhart Lake Functional Safety (FuSa) Software Package (Revision 1.0)

FuSa Prerequisites¶

The Intel® Functional Safety Software Package requires certain hardware, bootloader, and software configurations present on the target system to function correctly. The list below details these specific requirements.

Intel Atom® x6425RE / x6427FE (Elkhart Lake FuSa SKU 11 [QWW2 / RKLH])
Compatible Intel® SlimBootLoader (Intel® SBL) Integrated FirmWare Image (IFWI) to boot the target system. Refer to section: Building Intel® Firmware Image (IFWI)
xenomai-poky image built with the Functional Safety feature option enabled

Attention

When the Intel® Functional Safety Software Package is enabled in the ECI image, no isolated real-time cores are defined. This is in contrast to the default behavior which is described in section How ECI Achieves Determinism.

Deploying a FuSa enabled ECI image¶

The following section is applicable to:

Follow the sections below to deploy a FuSa enabled ECI image.

Building Intel® Firmware Image (IFWI)¶

The Integrated Firmware Image (IFWI) a.k.a ‘BIOS’ is a 32MB binary file written on SPI-NOR of the target system. This image contains various components that are necessary to reliably initialize the Elkhart Lake SOC and successfully boot to an Operating System. The IFWI must be built and flashed to the target system to enable FuSa.

Follow the section Slim Bootloader Stitching in Sbl_Ehl_ReleaseNotes.pdf (part of Intel® Elkhart Lake Slim Bootloader (SBL) (Intel RDC#616714)) to build and stitch compatible IFWI binary.

Note

This document also lists various firmware components that are used as part of the IFWI binary stitching and their availability in Intel® Resource Design Center.
After building the IFWI, refer to the following guide to flash the IFWI to the target system: Flashing an Integrated FirmWare Image (IFWI).
Note

SlimBootLoader (SBL) boots Linux in Container Boot Image format.
- ECI installation (section Boot & Install Image) also installs Container Boot Image appropriately so that SBL can boot to OS successfully
For signing Container image, ECI uses example file cert/OS1_TestKey_Pub_RSA2048_priv.pem present under meta-fusa layer.
- Signing key is used sign Container Boot Image. SBL authenticates the Container Boot Image during boot.
- User can point to a different key file by using PREGENERATED_SIGNING_KEY_SLIMBOOT_KEY_SHA256 variable in targets/kas/opt-fusa.yml. Same key file should also be used in place of ./SblPlatform/SblKeys/OS1_TestKey_Pub_RSA2048_priv.pem in Intel® Elkhart Lake Slim Bootloader (SBL) (Intel RDC#616714) to build SBL and IFWI binary file.
- Refer to section Create Container Boot Image in Sbl_Ehl_ReleaseNotes.pdf (part of Intel® Elkhart Lake Slim Bootloader (SBL) (Intel RDC#616714)) for information regarding SBL bootable Container Boot Image format.
- Steps to generate signing keys is outside of the scope of this documentation.

Building ECI Image with FuSa Feature¶

Follow section Building ECI Targets to build an image with FuSa feature enabled. Creating an ECI image that contains the FuSa feature can be accomplished by selecting the Functional Safety feature option during image setup (under xenomai-poky target). See section xenomai-poky for more information.
Follow section Create Bootable USB to create a bootable USB flash drive with `xenomai-poky image.
Follow section Boot & Install Image to install ECI image to target system.

System Overview¶

The following sections provide a brief overview of components in the FuSa Software Package.

Safety Monitoring Integrated Suite (SMIS)¶

Safety Monitoring Integrated Suite (SMIS) is a generic framework to demonstrate the usage of ODCC while implementing the safety workloads, executing periodic STLs and interacting with Intel® Safety Island (ISI) through Safety Monitor Communication Library (SMCL) framework. ECI builds CLI variant of SMIS. SMIS is a reference application with certain SC3 capable components. ECI build uses GCC 9.3 to build SMIS. It is up to the end user to select a compiler and version appropriately for certification purposes.

Software Test Library (STL)¶

The Software Test Library (STL) is a collection of diagnostic tests that detect and report silicon/hardware failures to the application. The STL contains core STLs, uncore STLs, error configuration checks and error status checks. STL is SC3 (Systematic Development Capability 3) capable and can be reused on another OS of choice. FuSa SW suite provides Host STL Driver (for Yocto Linux) to access Elkhart Lake IPs necessary for STL functions.

The Startup STLs help to the configuration setting on the Elkhart Lake SoC and is executed only in the beginning of StlManager
The Periodic STLs are invoked periodically every PST interval to check the health of the EHL SOC
The On-demand STLs are needed to be called when some errors are raised and a notification is sent by the Intel® SI

STL Manager¶

STL Manager is custom application that helps to schedule runs of available STLs and ensures that STL results are delivered to Intel® Safety Island (ISI) within Diagnostic Time Interval (DTI)

On Demand Cross Comparison (ODCC)¶

On Demand Cross Comparison is a diagnostic measure able to detect HW random failures affecting the core and other associated IPs by comparing snapshots between two redundant safety applications getting executed from two cores

Safety Monitor Communication Library (SMCL)¶

Safety Monitor Communication Library (SMCL) is responsible for providing interface to upper layers (STL, ODCC) to communicate with Intel® Safety Island (ISI) on Elkhart Lake. SMCL is SC3 (Systematic Development Capability 3) capable and ensures safety of the packets that are sent from the workloads to Intel® Safety Island (ISI). Packets to be sent to the ISI are entirely wrapped and unwrapped by the SMCL. ISI Linux kernel module drivers/platform/x86/intel_isi_mb.ko acts as an intermediary that writes the packet to the ISI Hardware Mailbox interface and routes the response packets back to the desired Workload.

Operation System Adaptation Layer (OSAL)¶

Operation System Adaptation Layer (OSAL) API provides a set of APIs for abstracting the OS interfaces and features. Current implementation is a reference code for Yocto Linux and can be ported to different OS of choice

SlimBootLoader (SBL)¶

Intel® SlimBootLoader (Intel® SBL) is the chosen boot firmware for Elkhart Lake FuSa application. SBL is responsible for correct Elkhart Lake hardware initialization for FuSa operation and booting the operating system. Intel® SlimBootLoader is a Quality Managed (QM) component. In order to achieve the SC3 capability Pre-OS Checker (POSC) is used to verify the safety critical platform configuration done by SBL during boot. POSC is SC3 capable and acts as a STL for Intel® SBL.

FuSa Sanity-Check Testing¶

Tip

journalctl -f contains SMIS messages on progress and status of various STL and ODCC execution. It is recommended to watch the output of journalctl -f.

Run following command in a new console to capture the SMIS logs:

$ journalctl -f

Sanity-Check #1: Install Intel® Safety Island Mailbox (ISI-MB) driver and Host STL Driver (HSTD)¶

It is necessary that platform has a cold-reset/power-cycle to ensure that Intel® Safety Island (ISI) is in OK state. Power cycle of Elkhart Lake platform before executing below steps.

Enable the ISI driver and verify that the /dev/ISI_DRIVER interface is available:

$ insmod /opt/intel/ehl_fusa_sw_v1.0/isi_kernel_driver.ko
$ ls /dev/ISI_DRIVER

Enable the HSTD driver and verify that string hstd: Module version 1.1 successfully initilized appears in the dmesg log:
```
$ insmod /opt/intel/ehl_fusa_sw_v1.0/hstd.ko
$ dmesg | tail
```

Sanity-Check #2: Establish Communication with Intel® Safety Island (ISI)¶

Complete section Sanity-Check #1 before executing below steps.
Below command checks the health of ISI

Look for string ‘[SMIS] ISI Status is 0’ after below command execution.

$ cd /opt/intel/ehl_fusa_sw_v1.0/
$ ./Smis -a workload_api -t ok_nok_status_read

Note

Refer to Intel® Elkhart Lake Safety Monitoring Integrated Suite-User Guide (Intel RDC#616713) for more information of ./smis command options for stl and odcc.

Sanity-Check #3: Execute StlManager Startup STL¶

Complete section Sanity-Check #2 before executing below steps.
Perform the following commands to run startup stl on all cores

Look for string ‘[SMIS] ISI Status is 2’ after below command execution.

$ cd /opt/intel/ehl_fusa_sw_v1.0/
$ ./Smis --startup
$ ./Smis -a workload_api -t ok_nok_status_read

Sanity-Check #4: Execute StlManager for Core and Uncore STL¶

Complete section Sanity-Check #3 before executing below steps.

Perform the following commands to enable core-stl on all cores, enable uncore-stl on core 0, and start the STL manager:

$ cd /opt/intel/ehl_fusa_sw_v1.0/
$ ./Smis --core_stl 0,1,2,3 --uncore_stl 0 --oem 0,1,2,3 --sl_time 100000 --tmax 220000 --tmin 99940 --to_ideal 90000 --to_max 80000

Above command execution is not expected to return/exit to prompt. It exits in case of a failure or a NOK generated from ISI. Verify that no error/failure occurs at the prompt and that no unknown error/failure appears in the SMIS logs at journalctl -f. Use a new terminal for executing other commands.

Note

As PLL may not lock to desired 1900 MHz with 38.4 MHz crystal, stlclockmonitoring tolerance is updated to 0.1% of expected 1900 MHz.

Sanity-Check #5: Execute ODCC workload¶

Complete section Sanity-Check #4 before executing below steps.

Perform the following commands to run the ODCC workload on 2 cores for on-demand cross comparison:

$ cd /opt/intel/ehl_fusa_sw_v1.0/
$ ./Smis -a odcc -t odcc_start --sl_time 100000 --tmax 220000 --tmin 99940 --to_ideal 90000 --to_max 80000 --cr_ch_drift 99480 -e 2,3

Wait 30 minutes and verify that no error/failure occurs and that no error/failure appears in the ODCC & SMIS logs at journalctl -f.

Note

It is a known observation that due to the nature of non-realtime scheduler, the ODCC threads on the cores 0 and 1 could drift apart in timing. As a workaround :

use echo 4 > /proc/irq/##/smp_affinity or echo 8 > /proc/irq/##/smp_affinity to assign interrupts to cores 3 and 4. ## is the IRQ number where larger number of interrupts are serviced by only cores 0 and 1 (determined by cat /proc/interrupts)
‘DOWN’ unused network adapter, for e.g. ip link set eth0 down

Refer to section Known Limitations for list of known issues with PV release of Intel® FuSa Software Package