Developer Guide

  • 2021.2
  • 06/11/2021
  • 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 that allows the host to connect to the target system via SSH, such as hostname, username, password, and port.
  • 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": "...", "processor_name": "AUTO", "reboot_command": "reboot", "connections_settings": { "hostname": "...", "username": "...", "password": "...", "port": 22, "connection_timeout":5, "reconnection_timeout":10, "reconnection_attempts":10 }, "capsule_settings": { "capsule_generate_script": "bash ./host_scripts/capsule_create_uefi.sh", "capsule_apply_script": "bash /usr/share/tcc_tools/tools/target_scripts/capsule_apply_uefi.sh", "target_capsules_path": "/tmp/capsules", } } } }
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
. (Default:
AUTO
) In this release, the field is used by the data streams optimizer but not by the cache configurator.
“reboot_command”
Valid values are
reboot
or an empty line if no reboot is required. You can also create your own script (for example, to check something before rebooting) and input the command here.
“connection_settings”
Section that stores all connection-related data: hostname, username, password, and so on.
“hostname”
IP address or hostname of the target system.
“username”
Username to connect to the target system via SSH. An Authenticated User must have read/write permissions for the capsule location; for data streams optimizer, also must be able to execute the workload validation script.
“password”
Password to connect to the target system via SSH. If the SSH connection to the target system does not need a password or if you have created an SSH key and installed the SSH key on the target system, you can leave the password field empty. The tool also accepts environment files that do not contain a password field.
“port”
Port to connect to the target system via SSH.
“connection_timeout”
Wait time before the SSH connection between the host and target system is considered failed, in seconds.
“reconnection_timeout”
Delay between the next attempt to reconnect the host and target system via SSH, in seconds.
“reconnection_attempts”
Optional. The maximum number of SSH reconnection attempts. Possible value is an integer from 1 to 255. (Default: 10)
“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 applies the capsules to the target system. For more information about this script, see Capsule Apply Script.
“target_capsules_path”
Directory on the target system that will be used to store capsules from the host.

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.
  • SSH-related fields are used to SSH from the host to the target system.
  • 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 BIOS, known as “subregions.”
The sample environment file defines all capsule-related fields for the reference BIOS. If you are using the reference BIOS, you do not need to update those fields.
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. 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.
When using an Intel-provided BIOS binary with Intel CRB/RVP, you can turn off authentication since you might not be able to to provision your keys.
If you are using a different bootloader, such as Coreboot*, replace the Capsule Create Script and Capsule 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.
If you decide to copy the environment file to another location on your host system, be sure to change the relative paths in the environment file or replace them with full paths.

Product and Performance Information

1

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