Developer Guide

  • 2021.1
  • 11/03/2021
  • Public
Contents

Create a Requirements File

The data streams optimizer selects tuning configurations based on the information in the requirements file. The format of the file is JSON. This page covers:

JSON Description

A requirements file 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.
It is important to escape JSON-specific characters such as double-quotes and backslash:
Character
Escape Symbol
"
\"
\
\\
Example of the workload section of the file:
"workload": { "command": "executable command with \"quotes\" and backslash: \\", "arguments": [ "argument1 value1", "argument2" ] },
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 as shown in the examples below.
Example requirements file for one data stream:
{ "workload": { "command": "python3 /usr/share/tcc_tools/tools/demo/workloads/bin/rtcp_validation_script.py", "arguments": [ "--latency_us 100 ", "--ssh root@192.168.0.2", "--pci_rtcp 0000:01:00.0", "--pci_pglm 0000:01:00.0", "--no-compute", "--cpuid 3" ] }, "requirements": [ { "producer": "Memory", "consumer": "01:00.0", "traffic_class": 0, "latency_us": 4, "bytes_per_transfer": 64, "relative_priority": 0 } ] }
Example requirements file for two data streams:
{ "workload": { "command": "python3 /usr/share/tcc_tools/tools/demo/workloads/bin/rtcp_validation_script.py", "arguments": [ "--latency_us 80", "--ssh root@192.168.0.2", "--pci_rtcp 0000:01:00.0", "--pci_pglm 0000:01:00.0", "--no-compute", "--cpuid 3" ] }, "requirements": [ { "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 } ] }
The following table describes each field:
Field
Description
“command”
Command to run the workload validation script (command-line executable). See Create a Workload Validation Script:.
“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 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.
Note:
In this release, 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.
“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.
Note:
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 RT 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.
Directory on the host system:
${TCC_TOOLS_PATH}/demo/requirements
Core-from-PCIe Stream
Sample Requirements File
Producer
Consumer
Latency
Bytes per Transfer
single_corepcierd_0.json
BDF a9:00.0, TC 0
Core 3
12
4
single_corepcierd_1.json
BDF 01:00.0, TC 0
Core 3
10
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
25
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
10
64
single_pciememrd_1.json
Memory
BDF 01:00.0, TC 0
3
64
single_pciememrd_2.json
Memory
BDF a9:00.0, TC 1
5
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 the RTCP Sample.

Tool Flow

In the context of the Host-Target Reference Implementation, the requirements file affects the steps highlighted in the following diagram:
  • The tool uses the
    "requirements"
    fields to find a suitable tuning configuration.
  • The tool uses the
    "workload"
    fields to run the workload validation script. If the validation passes, the tool creates the output file. If the validation fails, it attempts to find another configuration.

Product and Performance Information

1

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