Developer Guide

  • 2021.3
  • 11/18/2021
  • Public
Contents

Create an Environment File

The environment file contains information about the tool environment. This file must be a well-formatted JavaScript* Object Notation (JSON) document containing all required information. This page 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 Gen 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

For the reference implementation, the environment file affects the following steps:
  • Capsule-related fields are used to create, move, and apply the capsule.
  • SSH-related fields are used to connect the host to the target system via SSH.
  • The
    "reboot_command"
    is used to reboot the target system.

Capsule

The cache configurator 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 BIOS, known as “subregions.”
For 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 capsule 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. In this release, you cannot use other bootloaders.
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.
For Slim Bootloader you should follow the security key generation/signing procedure, described in details in Security Features section of the Slim Bootloader documentation.

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.