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.
| |
“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.
| |
“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.
| |
“relative_priority” | Priority of this data stream relative to other data streams specified
in this requirements file.
| 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.