config - Configuration Package

Testbed configuration and test suite specification.

This package offers classes that hold real-time information about the testbed, hold test run configuration describing the tested testbed and a loader function, load_config(), which loads the YAML test run configuration file and validates it against the Configuration Pydantic model.

The YAML test run configuration file is parsed into a dictionary, parts of which are used throughout this package. The allowed keys and types inside this dictionary map directly to the Configuration model, its fields and sub-models.

The test run configuration has two main sections:

• The TestRunConfiguration which defines what tests are going to be run and how DPDK will be built. It also references the testbed where these tests and DPDK are going to be run,

• The nodes of the testbed are defined in the other section, a list of NodeConfiguration objects.

The real-time information about testbed is supposed to be gathered at runtime.

The classes defined in this package make heavy use of pydantic. Nearly all of them are frozen:

• Frozen makes the object immutable. This enables further optimizations, and makes it thread safe should we ever want to move in that direction.

class FrozenModel

Bases: BaseModel

A pre-configured BaseModel.

model_config

Fields are set as read-only and any extra fields are forbidden.

class Architecture

Bases: StrEnum

The supported architectures of Nodes.

i686 = 'i686'

x86_64 = 'x86_64'

x86_32 = 'x86_32'

arm64 = 'arm64'

ppc64le = 'ppc64le'

class OS

Bases: StrEnum

The supported operating systems of Nodes.

linux = 'linux'

freebsd = 'freebsd'

windows = 'windows'

class CPUType

Bases: StrEnum

The supported CPUs of Nodes.

native = 'native'

armv8a = 'armv8a'

dpaa2 = 'dpaa2'

thunderx = 'thunderx'

xgene1 = 'xgene1'

class Compiler

Bases: StrEnum

The supported compilers of Nodes.

gcc = 'gcc'

clang = 'clang'

icc = 'icc'

msvc = 'msvc'

class TrafficGeneratorType

Bases: str, Enum

The supported traffic generators.

SCAPY = 'SCAPY'

__new__(value)

class HugepageConfiguration

Bases: FrozenModel

The hugepage configuration of Nodes.

number_of: int

The number of hugepages to allocate.

force_first_numa: bool

If True, the hugepages will be configured on the first NUMA node.

class PortConfig

Bases: FrozenModel

The port configuration of Nodes.

pci: str

The PCI address of the port.

os_driver_for_dpdk: str

The driver that the kernel should bind this device to for DPDK to use it.

os_driver: str

The operating system driver name when the operating system controls the port.

peer_node: str

The name of the peer node this port is connected to.

peer_pci: str

The PCI address of the peer port connected to this port.

class TrafficGeneratorConfig

Bases: FrozenModel

A protocol required to define traffic generator types.

type: TrafficGeneratorType

The traffic generator type the child class is required to define to be distinguished among others.

class ScapyTrafficGeneratorConfig

Bases: TrafficGeneratorConfig

Scapy traffic generator specific configuration.

type: SCAPY: 'SCAPY'>]

The traffic generator type the child class is required to define to be distinguished among others.

TrafficGeneratorConfigTypes

A union type discriminating traffic generators by the type field.

alias of ScapyTrafficGeneratorConfig[ScapyTrafficGeneratorConfig]

LogicalCores

Comma-separated list of logical cores to use. An empty string means use all lcores.

alias of Annotated[str]

class NodeConfiguration

Bases: FrozenModel

The configuration of Nodes.

name: str

The name of the Node.

hostname: str

The hostname of the Node. Can also be an IP address.

user: str

The name of the user used to connect to the Node.

password: str | None = None

The password of the user. The use of passwords is heavily discouraged, please use SSH keys.

arch: Architecture

The architecture of the Node.

os: OS

The operating system of the Node.

lcores: str = '1'

A comma delimited list of logical cores to use when running DPDK.

use_first_core: bool = False

If True, the first logical core won’t be used.

hugepages: framework.config.HugepageConfiguration | None = None

An optional hugepage configuration.

ports: list[framework.config.PortConfig]

The ports that can be used in testing.

class SutNodeConfiguration

Bases: NodeConfiguration

SutNode specific configuration.

memory_channels: int = 1

The number of memory channels to use when running DPDK.

class TGNodeConfiguration

Bases: NodeConfiguration

TGNode specific configuration.

traffic_generator: ScapyTrafficGeneratorConfig

The configuration of the traffic generator present on the TG node.

NodeConfigurationTypes = framework.config.TGNodeConfiguration | framework.config.SutNodeConfiguration

Union type for all the node configuration types.

resolve_path(path: Path) → Path

Resolve a path into a real path.

class BaseDPDKLocation

Bases: FrozenModel

DPDK location base class.

The path to the DPDK sources and type of location.

remote: bool = False

Specifies whether to find DPDK on the SUT node or on the local host. Which are respectively represented by RemoteDPDKLocation and LocalDPDKTreeLocation.

class LocalDPDKLocation

Bases: BaseDPDKLocation

Local DPDK location base class.

This class is meant to represent any location that is present only locally.

remote: Literal[False] = False

Specifies whether to find DPDK on the SUT node or on the local host. Which are respectively represented by RemoteDPDKLocation and LocalDPDKTreeLocation.

class LocalDPDKTreeLocation

Bases: LocalDPDKLocation

Local DPDK tree location.

This class makes a distinction from RemoteDPDKTreeLocation by enforcing on the fly validation.

dpdk_tree: Path

The path to the DPDK source tree directory on the local host passed as string.

resolve_dpdk_tree_path() → Path

Resolve the local DPDK tree path.

validate_dpdk_tree_path() → typing_extensions.Self

Validate the provided DPDK tree path.

class LocalDPDKTarballLocation

Bases: LocalDPDKLocation

Local DPDK tarball location.

This class makes a distinction from RemoteDPDKTarballLocation by enforcing on the fly validation.

tarball: Path

The path to the DPDK tarball on the local host passed as string.

resolve_tarball_path() → Path

Resolve the local tarball path.

validate_tarball_path() → typing_extensions.Self

Validate the provided tarball.

class RemoteDPDKLocation

Bases: BaseDPDKLocation

Remote DPDK location base class.

This class is meant to represent any location that is present only remotely.

remote: Literal[True] = True

Specifies whether to find DPDK on the SUT node or on the local host. Which are respectively represented by RemoteDPDKLocation and LocalDPDKTreeLocation.

class RemoteDPDKTreeLocation

Bases: RemoteDPDKLocation

Remote DPDK tree location.

This class is distinct from LocalDPDKTreeLocation which enforces on the fly validation.

dpdk_tree: PurePath

The path to the DPDK source tree directory on the remote node passed as string.

class RemoteDPDKTarballLocation

Bases: RemoteDPDKLocation

Remote DPDK tarball location.

This class is distinct from LocalDPDKTarballLocation which enforces on the fly validation.

tarball: PurePath

The path to the DPDK tarball on the remote node passed as string.

DPDKLocation = framework.config.LocalDPDKTreeLocation | framework.config.LocalDPDKTarballLocation | framework.config.RemoteDPDKTreeLocation | framework.config.RemoteDPDKTarballLocation

Union type for different DPDK locations.

class BaseDPDKBuildConfiguration

Bases: FrozenModel

The base configuration for different types of build.

The configuration contain the location of the DPDK and configuration used for building it.

dpdk_location: framework.config.LocalDPDKTreeLocation | framework.config.LocalDPDKTarballLocation | framework.config.RemoteDPDKTreeLocation | framework.config.RemoteDPDKTarballLocation

The location of the DPDK tree.

class DPDKPrecompiledBuildConfiguration

Bases: BaseDPDKBuildConfiguration

DPDK precompiled build configuration.

precompiled_build_dir: str

If it’s defined, DPDK has been pre-compiled and the build directory is located in a subdirectory of ~dpdk_location.dpdk_tree or ~dpdk_location.tarball root directory.

class DPDKBuildOptionsConfiguration

Bases: FrozenModel

DPDK build options configuration.

The build options used for building DPDK.

arch: Architecture

The target architecture to build for.

os: OS

The target OS to build for.

cpu: CPUType

The target CPU to build for.

compiler: Compiler

The compiler executable to use.

compiler_wrapper: str = ''

This string will be put in front of the compiler when executing the build. Useful for adding wrapper commands, such as ccache.

property name: str

The name of the compiler.

class DPDKUncompiledBuildConfiguration

Bases: BaseDPDKBuildConfiguration

DPDK uncompiled build configuration.

build_options: DPDKBuildOptionsConfiguration

The build options to compiled DPDK with.

DPDKBuildConfiguration = framework.config.DPDKPrecompiledBuildConfiguration | framework.config.DPDKUncompiledBuildConfiguration

Union type for different build configurations.

class TestSuiteConfig

Bases: FrozenModel

Test suite configuration.

Information about a single test suite to be executed. This can also be represented as a string instead of a mapping, example:

test_runs:
- test_suites:
    # As string representation:
    - hello_world # test all of `hello_world`, or
    - hello_world hello_world_single_core # test only `hello_world_single_core`
    # or as model fields:
    - test_suite: hello_world
      test_cases: [hello_world_single_core] # without this field all test cases are run

test_suite_name: str

The name of the test suite module without the starting TestSuite_.

test_cases_names: list[str]

The names of test cases from this test suite to execute. If empty, all test cases will be executed.

property test_suite_spec: TestSuiteSpec

The specification of the requested test suite.

convert_from_string()

Convert the string representation of the model into a valid mapping.

validate_names() → typing_extensions.Self

Validate the supplied test suite and test cases names.

This validator relies on the cached property test_suite_spec to run for the first time in this call, therefore triggering the assertions if needed.

class TestRunSUTNodeConfiguration

Bases: FrozenModel

The SUT node configuration of a test run.

node_name: str

The SUT node to use in this test run.

vdevs: list[str]

The names of virtual devices to test.

class TestRunConfiguration

Bases: FrozenModel

The configuration of a test run.

The configuration contains testbed information, what tests to execute and with what DPDK build.

dpdk_config: framework.config.DPDKPrecompiledBuildConfiguration | framework.config.DPDKUncompiledBuildConfiguration

The DPDK configuration used to test.

perf: bool

Whether to run performance tests.

func: bool

Whether to run functional tests.

skip_smoke_tests: bool = False

Whether to skip smoke tests.

test_suites: list[framework.config.TestSuiteConfig]

The names of test suites and/or test cases to execute.

system_under_test_node: TestRunSUTNodeConfiguration

The SUT node configuration to use in this test run.

traffic_generator_node: str

The TG node name to use in this test run.

random_seed: int | None = None

The seed to use for pseudo-random generation.

class TestRunWithNodesConfiguration

Bases: NamedTuple

Tuple containing the configuration of the test run and its associated nodes.

test_run_config: TestRunConfiguration

sut_node_config: SutNodeConfiguration

tg_node_config: TGNodeConfiguration

static __new__(_cls, test_run_config: TestRunConfiguration, sut_node_config: SutNodeConfiguration, tg_node_config: TGNodeConfiguration)

Create new instance of TestRunWithNodesConfiguration(test_run_config, sut_node_config, tg_node_config)

class Configuration

Bases: FrozenModel

DTS testbed and test configuration.

test_runs: list[framework.config.TestRunConfiguration]

Test run configurations.

nodes: list[framework.config.TGNodeConfiguration | framework.config.SutNodeConfiguration]

Node configurations.

property test_runs_with_nodes: list[framework.config.TestRunWithNodesConfiguration]

List of test runs with the associated nodes.

validate_node_names()

Validate that the node names are unique.

validate_ports() → typing_extensions.Self

Validate that the ports are all linked to valid ones.

validate_test_runs_with_nodes() → typing_extensions.Self

Validate the test runs to nodes associations.

This validator relies on the cached property test_runs_with_nodes to run for the first time in this call, therefore triggering the assertions if needed.

load_config(config_file_path: Path) → Configuration

Load DTS test run configuration from a file.

Load the YAML test run configuration file, validate it, and create a test run configuration object.

The YAML test run configuration file is specified in the --config-file command line argument or the DTS_CFG_FILE environment variable.

Parameters:

config_file_path (Path) – The path to the YAML test run configuration file.

Returns:

The parsed test run configuration.

Raises:

ConfigurationError – If the supplied configuration file is invalid.

Return type:

Configuration