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

Developer Guide

  • 2021.2
  • 06/11/2021
  • Public
Contents

Create a Requirements File

The data streams optimizer selects tuning configurations based on the information in the requirements file. This file must be a well-formatted JSON* document containing all required information. This section covers:

Requirements Workflow

In the context of the Host-Target Reference Implementation, the requirements file affects the steps highlighted in the following diagram:

Requirements File Sections

The requirements file is a JSON file that contains two main sections:
"workload"
 and
"requirements"
.
  • The
    "workload"
     section contains information that allows the tool to run a workload validation script, such as the command and arguments for the script. A requirements file can contain only one
    "workload"
     section, meaning the tool can run only one workload validation script during a particular run.
    If the workload validation script indicates that the validation passed, the tool creates the tuning configuration file. If the workload validation script indicates that the validation failed, the tool attempts to find another tuning configuration.
    For details about workload validation scripts, see Create a Workload Validation Script.
  • The
    "requirements"
     section contains a list of requirements for the data stream to be tuned. The tool uses these requirements to select tuning configurations. You can specify one or more data streams in the
    "requirements"
     section.
Example requirements file for one data stream:
{
    "workload": {
        "command": "python3 /usr/share/tcc_tools/tools/demo/workloads/bin/mrl_validation_script.py",
        "arguments": [
            "--device I225",
            "--iterations 10000000",
            "--latency_us 80",
            "--core 3"
        ]
    },
    "requirements": {
        "compatibility": "SoftwareSRAM",
        "streams":[
            {
                "producer": "aa:00.0",
                "traffic_class": 0,
                "consumer": "Core3",
                "latency_us": 100,
                "bytes_per_transfer": 4,
                "relative_priority": 0
            }
        ]
    }
}
Example requirements file for two data streams:
{
   "workload": {
       "command": "python3 /usr/share/tcc_tools/tools/demo/workloads/bin/mrl_validation_script.py",
        "arguments": [
            "--device I225",
            "--iterations 10000000",
            "--latency_us 80",
            "--core 3"
        ]
   },
   "requirements": {
       "compatibility": "SoftwareSRAM",
       "streams":[
           {
               "producer": "01:00.0",
               "traffic_class": 0,
               "consumer": "Memory",
               "latency_us": 2.5,
               "bytes_per_transfer": 64,
               "relative_priority": 1
           },
           {
               "producer": "Memory",
               "consumer": "02:00.0",
               "traffic_class": 1,
               "latency_us": 5,
               "bytes_per_transfer": 64,
               "relative_priority": 2
           }
       ]
   }
}

Requirements File Fields

It is important to escape JSON-specific characters such as double-quotes and backslash:
Character
Escape Symbol
"
\"
\
\\
The following table describes each field:
Field
Description
Note
“command”
Command to run the workload validation script (command-line executable).
“arguments”
Optional. List of arguments to be passed to the workload validation script. The arguments are specific to the script.
“requirements”
List of requirements for tuning configuration.
“compatibility”
When this option is set, the data streams optimizer tool will select only the configurations compatible with the specified feature. Valid value:
SoftwareSRAM
.
“streams”
List of requirements for data streams.
“producer”
The producer of the data stream. It can be a processor core, a PCIe device, or memory.
  • If a core, the format is CoreNumber. For example,
    Core3
    .
  • If a PCIe device, the format is Bus:Device.Function (BDF) notation. For example,
    01:00.0
    .
  • If memory, the value is
    Memory
    .
“consumer”
The consumer of the data stream. It can be a processor core, a PCIe device, or memory. See the next table for possible producer-consumer pairs.
  • If a core, the format is CoreNumber. For example,
    Core3
    .
  • If a PCIe device, the format is Bus:Device.Function (BDF) notation. For example,
    01:00.0
    .
  • If memory, the value is
    Memory
    .
“traffic_class”
If the producer or consumer is a PCIe device, this field is required to specify the Traffic Class of the endpoint. For example,
0
.
“latency_us”
Maximum tolerable latency of the data stream in microseconds. - A possible value is a floating point value. - If this field is absent, the data streams optimizer tool will select all configurations that satisfy all remaining requirements. This is equivalent to specifying a very high latency value for this field.
There is no minimum latency value. If the latency value is very low, the tool will validate the workload with the most aggressive tuning configuration.
“bytes_per_transfer”
Bytes per transfer.
  • A possible value is an integer.
  • If this field is absent, the data streams optimizer tool will select all configurations that satisfy all remaining requirements. This is equivalent to specifying a very low bytes-per-transfer value for this field.
“relative_priority”
Priority of this data stream relative to other data streams specified in this requirements file.
  • A possible value is an integer from 0–255. Specify 0 for your highest priority stream, 1 for the next, and so on. You can specify the same priority for multiple streams.
Not used in this release.
If the board support package (BSP) is used with the tool, Core 0 is not recommended to be used as the real-time core since the BSP kernel parameters offload kernel scheduler tasks, low-priority interrupts, and other non-real-time services to Core 0. If the requirement producer or consumer is Core 0, you may see worse performance due to the BSP assuming Core 0 is best effort.

Samples

The tool provides sample requirements files with example values. When you are ready to create a requirements file for your workload, you can modify one of these samples as needed.
The samples are:
These samples are located on the host system in the directory
${TCC_TOOLS_PATH}/demo/requirements
The following table shows you the JSON file name and the current settings of the Requirements File Fields for the samples.
Core-from-PCIe Stream
Sample Requirements File
Producer
Consumer
Latency
Bytes per Transfer
single_corepcierd_0.json
BDF 00:1e.4, TC 0
Core 3
40
4
single_corepcierd_1.json
BDF aa:00.0, TC 0
Core 3
90
4
single_corepcierd_2.json
BDF a9:00.0, TC 0
Core 3
8
4
single_corepcierd_3.json
BDF 01:00.0, TC 0
Core 3
10
4
Core-to-PCIe Stream
Sample Requirements File
Producer
Consumer
Latency
Bytes per Transfer
single_corepciewr_0.json
Core 3
BDF a9:00.0, TC 0
6
4
single_corepciewr_1.json
Core 3
BDF 01:00.0, TC 0
5
4
PCIe-from-Memory Stream
Sample Requirements File
Producer
Consumer
Latency
Bytes per Transfer
single_pciememrd_0.json
Memory
BDF a9:00.0, TC 0
25
4096
single_pciememrd_1.json
Memory
BDF 01:00.0, TC 0
3
64
single_pciememrd_2.json
Memory
BDF 00:1e.4, TC 0
3
64
single_pciememrd_3.json
Memory
BDF 01:00.0, TC 1
20
2048
PCIe-to-Memory Stream
Sample Requirements File
Producer
Consumer
Latency
Bytes per Transfer
single_pciememwr_0.json
BDF a9:00.0, TC 0
Memory
5
64
single_pciememwr_1.json
BDF 01:00.0, TC 1
Memory
2.5
512
Multiple Streams
Sample Requirements File
Producer
Consumer
Latency
Bytes per Transfer
multiple_pciememwr_pciememrd_0.json
BDF 01:00.0, TC 0
Memory
Memory
BDF 02:00.0, TC 1
5
15
64
64
To explore the effects of different requirements, you can use your own workloads or a provided sample.

Product and Performance Information

1

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