TSN

Overview

TSN (Time Sensitive Networking) solution is a set of capabilities that offers Time Synchronization, Traffic Shaping, set of IEEE open standard communication by bringing industrial-grade robustness and reliability to Ethernet . TSN removes the need for physical separation of critical and non-critical communication networks, thus allowing open data exchange between operations and enterprise - a concept at the heart of the Industrial Internel of Things (IIoT). To learn more about TSN, see TSN for details.

TSN container

Container support is a generic SBL feature. Please refer to Container and Container Security for generic details.

SBL defines a container called ‘IPFW’ for settings related to various silicon IP and settings related to TSN are managed as a component inside this ‘IPFW’ container. SBL loads this container and processes it as required including passing the relevant settings to Intel® Firmware Support Package (Intel® FSP) during Runtime. SBL defines this container in each platform’s build config file BoardConfig.py.

TSN MAC Address

User needs to provide TSN MAC address that is unique per board and that can be independently updateable. FBU (Firmware and BIOS Utility) tool is used to create a raw TSN MAC binary. Details on how this is all generated and packaged will be discussed in the later sections.

TSN enable

For each platform, there is a build configuration file BoardConfig.py. User can check this build configuration file to make sure self.ENABLE_TCC is set to 1 to enable TSN feature. For other TSN related configuration data, please refer to TSN configuration settings.

Take Tiger Lake as an example.

https://github.com/slimbootloader/slimbootloader/blob/master/Platform/TigerlakeBoardPkg/BoardConfig.py:

self.ENABLE_TSN = 1
if self.ENABLE_TSN:
    self.TMAC_SIZE = 0x00001000

# Name | Image File     | CompressAlg |         AuthType          |                 Key File                   | Region Align   | Region Size  | Svn Info
# ===============================================================================================================================================================
('IPFW',  'SIIPFW.bin',      ''    ,     container_list_auth_type,   'KEY_ID_CONTAINER'+'_'+self._RSA_SIGN_TYPE,          0,          0      ,        0),   # Container Header
('TMAC',     ''       ,     'Lz4'  ,     container_list_auth_type,   'KEY_ID_CONTAINER_COMP'+'_'+self._RSA_SIGN_TYPE,     0,   self.TMAC_SIZE,        0),   # TSN MAC Address

In the build configuration file, user can set self.ENABLE_TSN to 1 to enable TSN component and adjust the size if needed. Inside the IPFW container, the TSN MAC component is identified by 4 unique characters. SBL would use it when loading container and update it via firmware update. For TSN, the unique name is TMAC that SBL looks at while loading the TSN binary.

Different options to update TSN container

1. Specify in Board Config file and rebuild SBL

Specify the raw TSN binary Image file (that is generated by FBU tool) name in build config file BoardConfig.py. Copy the binary into Platform/<Platform>BoardPkg/Binaries folder in SBL source code before building SBL. User can also specify different compression and authentication method for this binary as desired. Rebuild SBL successfully. Now, the TSN MAC binary will be created and embedded in the IPFW container and be part of the IFWI. When flashed onto the board, SBL will process this container.

In addition, if the user decide to take this option, SBL that was rebuilt need to be stitched with TSN stitching option.

TSN Stitch Option for Soft Straps

User need to enable TSN soft straps into the final IFWI image. To do this, stitch the IFWI with TSN softstrap option, example: “-o tsn” option using StitchIFWIConfig python script, or use FIT tool to change the straps and then stitch the changes. As an example, you can refer to this file and search for TSN stitch otion (tsn7):

For Tiger Lake, it is -o tsn7 to enable TSN softstraps in the stitched IFWI. Other platforms may have similar option for TSN in the Stitch scripts.

2. Update using firmware update flow

Update TSN container without rebuilding SBL by the help of capsule generation and firmware update flow. Details will be provided in the TSN capsule generation section.

TSN configuration settings

SBL provides several configuration items for TSN settings. Take Tiger Lake as an example.

https://github.com/slimbootloader/slimbootloader/blob/master/Platform/TigerlakeBoardPkg/CfgData/CfgData_Silicon.yaml:

- PchTsnEnable :
    name         : Enable PCH TSN
    type         : Combo
    option       : $EN_DIS
    help         : >
                   Enable/disable TSN on the PCH.
    length       : 0x01
    value        : 0x0
- PchTsnLinkSpeed :
    name         : TSN Link Speed
    type         : Combo
    option       :   0: Reserved, 1: Reserved, 2: 38.4Mhz 2.5Gbps, 3: 38.4Mhz 1Gbps
    help         : >
                   Set TSN Link Speed.
    length       : 0x01
    value        : 0x03
- PchTsnMultiVcEnable :
    name         : Enable TSN Multi-VC
    type         : Combo
    option       : $EN_DIS
    help         : >
                   Enable/disable Multi Virtual Channels(VC) in TSN.
    length       : 0x01
    value        : 0x0

User can directly change the default values in CfgData_Silicon.yaml, but the default values will be overridden if same fields exist in a board specific delta file. It is preferred to use SBL ConfigEditor.py tool GUI to change SBL configuration data to update the board specific delta file before building SBL.

To use SBL configuration tool and to change the delta file, run the ConfigEditor.py tool from SBL source code:

BootloaderCorePkg\Tools\ConfigEditor.py

Following these steps to change SBL configuration data.

1. Open SBL default configuration data

Open default configuration file CfgDataDef.yaml from platform configuration data folder. Take Tiger Lake as example, open file Platform\TigerlakeBoardPkg\CfgData\CfgDataDef.yaml in this step.

../_images/tcc_open_yaml.png

2. Load the delta file

Same SBL image can boot multiple boards based on board ID. Each board delta file would override the default SBL configuration data. So need to load the board delta file if it already exists. The board delta file would be in same folder with CfgDataDef.yaml. Open CfgData_Int_Tglu_Ddr4.dlt as an example.

../_images/tcc_open_delta.png

3. Change option to enable tsn

Find TSN settings from ConfigEditor and update the options if required.

../_images/tsn_settings.png

4. Save the change to delta file

After changing option, save the changes back to the same delta file (CfgData_Int_Tglu_Ddr4.dlt in this example) to override the original one.

../_images/tsn_settings_save.png

After saving the delta file, the following lines will be added to the new delta file:

SILICON_CFG_DATA.PchTsnEnable               | 0x1
SILICON_CFG_DATA.PchTsnLinkSpeed         | 0x02

5. Build SBL

With above configuration data change, rebuild SBL. Then the TSN configuration settings would be enabled and effective in new SBL IFWI image.

TSN capsule generation

The raw TSN MAC binary can be generated using FBU tool, then signed and be encapsulated into IPFW container. Finally, container can be updated using a capsule update flow. Details on each of the steps will be discussed in this section.

Step 1: TSN raw binary generation

The raw TSN MAC Address binary can be generated using Firmware and BIOS Utilities (FBU) tool as follows:

  1. Download FBU tool from here: https://github.com/intel/iotg-fbu

  2. Python v3.6+ is needed if not already present on your host.

  3. Install python modules “click” and “cryptography” using the cmds:

    python -m pip install click

    python -m pip install cryptography

  4. Install OpenSSL for your host and add it to Windows PATH.

  5. Create tsn_mac_config.json file per your platform. A sample screenshot is presented here:

../_images/tsn_config_sample.png

Understanding the BDF definition:

The BDF value is defined as

typedef struct {

UINT32 RsvdBits1 : 12; ///< [11:0] Reserved bits

UINT32 Func : 3; ///< [14:12] Function Id

UINT32 Dev : 5; ///< [19:15] Device Id

UINT32 Bus : 8; ///< [27:20] Bus Id

UINT32 RsvdBits0 : 4; ///< [31:28] Reserved bits

} BDF;

To give an example, value 0x000F4000 in [“BDF”, “HEXADECIMAL”, 4, “000F4000”] decodes to

[14:12] Function Id = 100b = 4

[19:15] Device Id = 1 1110b = 30

[27:20] Bus Id = 0000 0000b = 0

The MAC addresses are specified in two four-byte hexadecimal values, where only the lower six values are being used. For example, to configure FC:F8:AE:00:30:04, the notation is

[“MacAddressLow”, “HEXADECIMAL”, 4, “00AEF8FC”],

[“MacAddressHigh”, “HEXADECIMAL”, 4, “00000430”],

  1. Open cmd prompt and cd to fbu\iotg-fbu\siiptool\common. Run the cmd:

python subregion_image.py <config_json-file> <out-file-name>

Example: python subregion_image.py tsn_mac_config.json TsnMacAddr.bin

A raw TSN MAC binary is generated successfully. Sample screenshot of the generated binary with sample tsn_mac_config json is as follows:

../_images/tsn_mac_bin_sample.png

Step 2: Sign and generate container for TSN

Generate a signed file from the raw TSN MAC binary (lets name it as TsnMacAddr.bin as referred in Step 1). Use SBL GenContainer.py tool to sign the raw binary and get a signed component file:

python BootloaderCorePkg\Tools\GenContainer.py sign -f TsnMacAddr.bin -o SignedTsnMacAddr.bin -a RSA3072_PSS_SHA2_384 -k ContainerCompTestKey_Priv_RSA3072.pem

The output file (SignedTsnMacAddr.bin) generated from the above command is a signed binary that will be verified by SBL during boot. So make sure the signing key ContainerCompTestKey_Priv_RSA3072.pem is same from Sblkeys folder when SBL is built.

SBL supports compression during signing the raw binary. SBL would automatically decompress it during the loading time. Take LZ4 compression as example on yocto:

python BootloaderCorePkg\Tools\GenContainer.py sign -f TsnMacAddr.bin -o SignedTsnMacAddr.bin -a RSA3072_PSS_SHA2_384 -k ContainerCompTestKey_Priv_RSA3072.pem  -c lz4 -td BaseTools/BinWrappers/PosixLike/Lz4Compress

NOTE: The compression tool Lz4Compress will be generated from SBL source code during SBL build at BaseTools/BinWrappers/PosixLike/Lz4Compress in Linux. For windows system, the compression tool will be generated at BaseTools\Bin\Win32\Lz4Compress.exe. so the windows compress command is:

python BootloaderCorePkg\Tools\GenContainer.py sign -f TsnMacAddr.bin -o SignedTsnMacAddr.bin -a RSA3072_PSS_SHA2_384 -k ContainerCompTestKey_Priv_RSA3072.pem -c lz4 -td BaseTools\Bin\Win32

More compression info could be found from command “python BootloaderCorePkg\Tools\GenContainer.py -h”.

Step 3: Generate capsule image

Create a capsule Image from the signed file for the firmware update using SBL GenCapsuleFirmware.py tool:

python BootloaderCorePkg\Tools\GenCapsuleFirmware.py -p TMAC:IPFW SignedTsnMacAddr.bin -k FirmwareUpdateTestKey_Priv_RSA3072.pem -o FwuImage.bin

Use SBL GenCapsuleFirmware.py tool to encapsulate the file SignedTsnMacAddr.bin generated in previous step in order to get a capsule file (FwuImage.bin). The output file (FwuImage.bin) generated from the above command is a signed capsule that will be verified by SBL during firmware update. Make sure the signing key FirmwareUpdateTestKey_Priv_RSA3072.pem is same from Sblkeys folder when SBL is built.

The above command uses “-p” parameter to specify capsule payload including the container and binary unique identifiers such as “TMAC:IPFW” and the signed container file name “SignedTsnMacAddr.bin”. The container (IPFW) and binary(TMAC) unique names should match with the ones defined in SBL build config file BoardConfig.py as referred in the TSN container section.

Step 4: Copy capsule image

During SBL firmware update, SBL will try to find the capsule image from the location specified from SBL configuration file CfgData_CapsuleInformation.yaml. CfgData_CapsuleInformation.yaml is platform specific config data file in YAML format and it can be customized for the capsule location including capsule storage device (USB, NVMe, SATA, etc.), boot partition, file system and capsule image name. On most platforms, SBL would set the capsule location to file /boot/efi/FwuImage.bin under USB or NVMe FAT32 boot partition by default.

Copy the capsule image FwuImage.bin to the location specified in SBL configuration file CfgData_CapsuleInformation.yaml.

Step 5: Trigger firmware update

To support triggering firmware update from an OS, SBL exposes an ACPI method. OS can call the ACPI method to trigger firmware update. Following the reset, SBL will boot into the firmware update mode.

Trigger firmware update from Yocto:

echo 1 > /sys/bus/wmi/devices/44FADEB1-B204-40F2-8581-394BBDC1B651/firmware_update_request

Finally, reboot the machine to let SBL run into firmware update mode. Once the board reboots, the firmware update flow in SBL will begin. There may be few reboots during this flow before finally booting to Yocto.