Intel® Time Coordinated Computing Tools (Intel® TCC Tools) 2022.1 Developer Guide

Developer Guide

  • 2022.1
  • 09/08/2022
  • Public
Contents

Create an Environment File

The environment file contains information about the tool environment. This file must be a well-formatted JSON document containing all required information. This section covers:

JSON Description

The file defines two main types of information:
  • Information gathered from the target system via target connections scripts.
  • Information that allows the tool to create and apply the capsule.
It is important to escape JSON-specific characters such as double-quotes and backslash:
Character
Escape symbol
"
\"
\
\\
Environment file example:
{
  "targets": {
    "target_name_1": {
      "target_info": "...",
      "capsule_settings": {
        "capsule_generate_script": "bash ./host_scripts/capsule_create_uefi.sh",
        "capsule_apply_script": "bash ./host_scripts/capsule_upload_apply_uefi.sh",
        "target_capsules_path": "/tmp/"
      },
      "scripts": {
        "register_verification": "bash ./host_scripts/target_runner.sh python3 /usr/share/tcc_tools/tools/target_scripts/registers_checker.py",
        "bdf": "bash ./host_scripts/target_runner.sh python3 /usr/share/tcc_tools/tools/target_scripts/bdf_converter.py",
        "processor_checker": "bash ./host_scripts/target_runner.sh python3 /usr/share/tcc_tools/tools/target_scripts/processor_checker.py",
        "rtct_reader": "bash ./host_scripts/target_runner.sh python3 /usr/share/tcc_tools/tools/target_scripts/rtct_reader.py",
        "reboot_command": "bash ./host_scripts/target_reboot.sh"
      }
    }
  }
}
The following table describes each field:
Field
Description
“targets”
List of target systems in the following format: “target_name”: {TARGET_SECTION}
“target_name”
Unique identifier for the target system.
“target_info”
Optional information about the target system, such as a unique name to help you identify the system. The tool does not use this field in the tuning flow.
“processor_name”
Optional. Processor name of the target system. For automated detection of the processor, type
AUTO
. To specify the processor name: For 11th Generation Intel® Core™ processors, type
TGL-U
. For Intel Atom® x6000E Series processors, type
EHL
. For Intel® Xeon® W-11000E Series processors, type
TGL-H
. (Default:
AUTO
) In this release, the field is used by the data streams optimizer but not by the cache configurator.
“capsule_settings”
Capsule-related information: script paths and target capsule path.
“capsule_generate_script”
Command-line executable that generates the capsules on the host system. For more information about this script, see Capsule Create Script.
“capsule_apply_script”
Command-line executable that copies and applies the capsules to the target system. For more information about this script, see Capsule Upload and Apply Script.
“target_capsules_path”
Directory on the target system that will be used to store capsules from the host.
“scripts”
Customizable executables. For more information about scripts, see Custom OS/Firmware Support for DSO.

Tool Flow

In the context of the Host-Target Reference Implementation, the environment file affects the following steps:
  • Capsule-related fields are used to create, move, and apply the capsule.
  • The
    "reboot_command"
     is used to reboot the target system.

Capsule

The data streams optimizer changes the configuration of the target system by updating the firmware. For the reference implementation, the tool uses a capsule (binary file) to update certain areas of the boot firmware, known as “subregions.”
In the context of the Host-Target Reference Implementation, the capsule-related fields affect the following steps:
  1. When it is time to create the capsule, the tool runs the script specified in the
    "capsule_generate_script"
     field.
  2. The tool moves the capsule to the location identified in the
    "target_capsules_path"
     field.
  3. The tool applies the image via the command specified in the
    "capsule_apply_script"
     field.

Using Your Own Bootloader

The reference implementation uses scripts to support UEFI BIOS and Slim Bootloader (SBL). You can copy and modify these scripts in order to use a different bootloader with the data streams optimizer. For more information, see Custom OS/Firmware Support for DSO.
If you are using a UEFI BIOS other than the reference BIOS binary, you can use the subregion capsule tool to sign the capsule and subregion. In this case, you will need to generate and enroll your certificate or public key into the BIOS. The flow requires working with your BIOS vendor to enroll the certificates/keys. The subregion data and the capsule must always be signed when generated to ensure the integrity of the generated capsule. The signature of the signed capsule and its payload (signed subregion data) will be authenticated by the BIOS before it is consumed.
See the white paper Intel® Time Coordinated Computing (Intel® TCC) Security for UEFI BIOSor see Security Features section of the Slim Bootloader documentation.
If you are using a different bootloader, such as Coreboot*, replace the Capsule Create Script and Capsule Upload and Apply Script according to the documentation that accompanies the bootloader.

Samples

The tool provides samples in the following directory:
${TCC_TOOLS_PATH}/demo/environment
When you are ready to create your own file, you can make a copy of the example and modify it as needed.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.