2. Python Library

2.9. Adl suite

ADL utilities library.

class resources.libraries.python.Adl.Adl

Bases: object

ADL utilities.

static adl_add_allowlist_entry(node, interface, ip_version, fib_id, default_adl=0)

Add adl allowlisted entry.

Parameters
  • node (dict) – Node to add ADL allowlist on.

  • interface (str) – Interface of the node where the ADL is added.

  • ip_version (str) – IP version. ‘ip4’ and ‘ip6’ are valid values.

  • fib_id (int) – Specify the fib table ID.

  • default_adl (int) – 1 => enable non-ip4, non-ip6 filtration, 0 => disable it.

Raises

ValueError – If parameter ‘ip_version’ has incorrect value.

static adl_interface_enable_or_disable(node, interface, state)

Enable or disable ADL on the interface.

Parameters
  • node (dict) – Node to add ADL allowlist on.

  • interface (str) – Interface of the node where the ADL is added.

  • state (str) – Enable or disable ADL on the interface.

Raises

ValueError – If parameter ‘state’ has incorrect value.

2.10. Classify suite

Classify utilities library.

class resources.libraries.python.Classify.Classify

Bases: object

Classify utilities.

static add_del_macip_acl_interface(node, interface, action, acl_idx)

Apply/un-apply the MACIP ACL to/from a given interface.

Parameters
  • node (dict) – VPP node to set MACIP ACL on.

  • interface (str or int) – Interface name or sw_if_index.

  • action (str) – Required action - add or del.

  • acl_idx (str or int) – ACL index to be applied on the interface.

Raises

RuntimeError – If unable to set MACIP ACL for the interface.

static add_macip_acl_multi_entries(node, rules='')

Add a new MACIP ACL.

Parameters
  • node (dict) – VPP node to set MACIP ACL on.

  • rules (str) – Required MACIP rules.

static add_replace_acl_multi_entries(node, acl_idx=None, rules=None, tag='')

Add a new ACL or replace the existing one. To replace an existing ACL, pass the ID of this ACL.

Parameters
  • node (dict) – VPP node to set ACL on.

  • acl_idx (int) – ID of ACL. (Optional)

  • rules (str) – Required rules. (Optional)

  • tag (str) – ACL tag (Optional).

static get_classify_session_data(node, table_index)

Retrieve settings for all classify sessions in a table.

Parameters
  • node (dict) – VPP node to retrieve classify data from.

  • table_index (int) – Index of a classify table.

Returns

List of classify session settings.

Return type

list or dict

static get_classify_table_data(node, table_index)

Retrieve settings for classify table by ID.

Parameters
  • node (dict) – VPP node to retrieve classify data from.

  • table_index (int) – Index of a specific classify table.

Returns

Classify table settings.

Return type

dict

static set_acl_list_for_interface(node, interface, acl_type, acl_idx=None)

Set the list of input or output ACLs applied to the interface. It unapplies any previously applied ACLs.

Parameters
  • node (dict) – VPP node to set ACL on.

  • interface (str or int) – Interface name or sw_if_index.

  • acl_type (str) – Type of ACL(s) - input or output.

  • acl_idx (list) – Index(ies) of ACLs to be applied on the interface.

static show_classify_tables_verbose(node)

Show classify tables verbose.

Parameters

node (dict) – Topology node.

Returns

Classify tables verbose data.

Return type

str

static vpp_configures_classify_session_l3(node, acl_method, table_index, skip_n, match_n, ip_version, direction, address, hit_next_index=None, opaque_index=4294967295, action=0, metadata=0)

Configuration of classify session for IP address filtering.

Parameters
  • node (dict) – VPP node to setup classify session.

  • acl_method (str) – ACL method - deny/permit.

  • table_index (int) – Classify table index.

  • skip_n (int) – Number of skip vectors.

  • match_n (int) – Number of vectors to match.

  • ip_version (str) – Version of IP protocol.

  • direction (str) – Direction of traffic - src/dst.

  • address (str) – IPv4 or IPv6 address.

  • hit_next_index (int) – hit_next_index of new session. (Default value = None)

  • opaque_index (int) – opaque_index of new session. (Default value = ~0)

  • action (int) – 0: No action (by default) metadata is not used. 1: Classified IP packets will be looked up from the specified ipv4 fib table (configured by metadata as VRF id). Only valid for L3 input ACL node 2: Classified IP packets will be looked up from the specified ipv6 fib table (configured by metadata as VRF id). Only valid for L3 input ACL node 3: Classified packet will be steered to source routing policy of given index (in metadata). This is only valid for IPv6 packets redirected to a source routing node.

  • metadata (int) – Valid only if action != 0. VRF id if action is 1 or 2. SR policy index if action is 3. (Default value = 0)

Raises

ValueError – If the parameter ‘direction’ has incorrect value.

static vpp_creates_classify_table_l3(node, ip_version, direction, netmask)

Create classify table for IP address filtering.

Parameters
  • node (dict) – VPP node to create classify table.

  • ip_version (str) – Version of IP protocol.

  • direction (str) – Direction of traffic - src/dst.

  • netmask (str) – IPv4 or Ipv6 (depending on the parameter ‘ip_version’) netmask (decimal, e.g. 255.255.255.255).

Returns

(table_index, skip_n, match_n) table_index: Classify table index. skip_n: Number of skip vectors. match_n: Number of match vectors.

Return type

tuple(int, int, int)

Raises

ValueError – If the parameters ‘ip_version’ or ‘direction’ have incorrect values.

static vpp_log_macip_acl_interface_assignment(node)

Get interface list and associated MACIP ACLs and write to robot log.

Parameters

node (dict) – VPP node.

static vpp_log_macip_acl_settings(node)

Retrieve configured MACIP settings from the ACL plugin and write to robot log.

Parameters

node (dict) – VPP node.

static vpp_log_plugin_acl_interface_assignment(node)

Retrieve interface assignment from the ACL plugin and write to robot log.

Parameters

node (dict) – VPP node.

static vpp_log_plugin_acl_settings(node)

Retrieve configured settings from the ACL plugin and write to robot log.

Parameters

node (dict) – VPP node.

2.11. Constants suite

Constants used in CSIT.

“Constant” means a value that keeps its value since initialization. The value does not need to be hard coded here, but can be read from environment variables.

class resources.libraries.python.Constants.Constants

Bases: object

Constants used in CSIT.

ASTF_N_DATA_FRAMES = 5
BITWISE_NON_ZERO = 4294967295
CORE_DUMP_DIR = '/tmp'
CPU_CNT_MAIN = 1
CPU_CNT_SYSTEM = 1
DATAPATH_INTERFACES_MAX = 100
DEFAULT_HUGEPAGE_SIZE = '2M'
DEFAULT_IP4_PREFIX_LENGTH = '24'
DEVICE_TYPE_TO_KEYWORD = {'scapy': None}
DOCKER_SUT_IMAGE_UBUNTU = 'csit_sut-ubuntu2004:local'
DOCKER_SUT_IMAGE_UBUNTU_ARM = 'csit_sut-ubuntu2004:local'
DPDK_NIC_DRIVER_TO_SUITE_PREFIX = {'mlx5_core': 'mlx5-', 'vfio-pci': ''}
DPDK_NIC_DRIVER_TO_TAG = {'mlx5_core': 'DRV_MLX5_CORE', 'vfio-pci': 'DRV_VFIO_PCI'}
DPDK_NIC_NAME_TO_DRIVER = {'Amazon-Nitro-50G': ['vfio-pci'], 'Intel-E810CQ': ['vfio-pci'], 'Intel-E810XXV': ['vfio-pci'], 'Intel-X520-DA2': ['vfio-pci'], 'Intel-X553': ['vfio-pci'], 'Intel-X710': ['vfio-pci'], 'Intel-XL710': ['vfio-pci'], 'Intel-XXV710': ['vfio-pci'], 'Mellanox-CX556A': ['mlx5_core']}
DUT1_UUID = ''
EXPORT_JSON = True
EXTENDED_DEBUG = False
FAIL_ON_CRC_MISMATCH = False
FORBIDDEN_SUITE_PREFIX_LIST = ['avf-', 'rdma-', 'af-xdp-', 'mlx5-']
GRAPH_NODE_VARIANT = ''
KERNEL_CORE_PATTERN = '/tmp/%p-%u-%g-%s-%t-%h-%e.core'
MODEL_VERSION = '1.0.1'
NIC_CODE_TO_SHORT_NAME = {'100ge2p1cx556a': 'cx556a', '100ge2p1e810cq': 'e810cq', '10ge2p1x520': 'x520', '10ge2p1x553': 'x553', '10ge2p1x710': 'x710', '25ge2p1e810xxv': 'e810xxv', '25ge2p1xxv710': 'xxv710', '40ge2p1xl710': 'xl710', '50ge1p1ena': 'ena'}
NIC_DRIVER_TO_PLUGINS = {'af_xdp': 'af_xdp_plugin.so', 'avf': 'avf_plugin.so', 'rdma-core': 'rdma_plugin.so', 'vfio-pci': 'dpdk_plugin.so'}
NIC_DRIVER_TO_SUITE_PREFIX = {'af_xdp': 'af-xdp-', 'avf': 'avf-', 'rdma-core': 'rdma-', 'vfio-pci': ''}
NIC_DRIVER_TO_TAG = {'af_xdp': 'DRV_AF_XDP', 'avf': 'DRV_AVF', 'rdma-core': 'DRV_RDMA_CORE', 'vfio-pci': 'DRV_VFIO_PCI'}
NIC_DRIVER_TO_VFS = {'af_xdp': 'nic_vfs}= | 0', 'avf': 'nic_vfs}= | 1', 'rdma-core': 'nic_vfs}= | 0', 'vfio-pci': 'nic_vfs}= | 0'}
NIC_NAME_TO_BPS_LIMIT = {'Amazon-Nitro-50G': 10000000000, 'Intel-E810CQ': 100000000000, 'Intel-E810XXV': 24500000000, 'Intel-X520-DA2': 10000000000, 'Intel-X553': 10000000000, 'Intel-X710': 10000000000, 'Intel-XL710': 24500000000, 'Intel-XXV710': 24500000000, 'Mellanox-CX556A': 100000000000, 'virtual': 100000000}
NIC_NAME_TO_CODE = {'Amazon-Nitro-50G': '50ge1p1ena', 'Intel-E810CQ': '100ge2p1e810cq', 'Intel-E810XXV': '25ge2p1e810xxv', 'Intel-X520-DA2': '10ge2p1x520', 'Intel-X553': '10ge2p1x553', 'Intel-X710': '10ge2p1x710', 'Intel-XL710': '40ge2p1xl710', 'Intel-XXV710': '25ge2p1xxv710', 'Mellanox-CX556A': '100ge2p1cx556a'}
NIC_NAME_TO_CRYPTO_HW = {'Intel-X553': 'HW_C3xxx', 'Intel-X710': 'HW_DH895xcc', 'Intel-XL710': 'HW_DH895xcc'}
NIC_NAME_TO_DRIVER = {'Amazon-Nitro-50G': ['vfio-pci'], 'Intel-E810CQ': ['vfio-pci', 'avf', 'af_xdp'], 'Intel-E810XXV': ['vfio-pci', 'avf', 'af_xdp'], 'Intel-X520-DA2': ['vfio-pci', 'af_xdp'], 'Intel-X553': ['vfio-pci', 'af_xdp'], 'Intel-X710': ['vfio-pci', 'avf', 'af_xdp'], 'Intel-XL710': ['vfio-pci', 'avf', 'af_xdp'], 'Intel-XXV710': ['vfio-pci', 'avf', 'af_xdp'], 'Mellanox-CX556A': ['rdma-core', 'af_xdp']}
NIC_NAME_TO_PPS_LIMIT = {'Amazon-Nitro-50G': 1200000, 'Intel-E810CQ': 58500000, 'Intel-E810XXV': 29000000, 'Intel-X520-DA2': 14880952, 'Intel-X553': 14880952, 'Intel-X710': 14880952, 'Intel-XL710': 18750000, 'Intel-XXV710': 18750000, 'Mellanox-CX556A': 148809523, 'virtual': 14880952}
PERF_STAT_EVENTS = 'cpu-clock,context-switches,cpu-migrations,page-faults,cycles,instructions,branches,branch-misses,L1-icache-load-misses'
PERF_TRIAL_ASTF_DELAY = 0.112
PERF_TRIAL_DURATION = 1.0
PERF_TRIAL_LATENCY_DURATION = 5.0
PERF_TRIAL_MULTIPLICITY = 10
PERF_TRIAL_STL_DELAY = 0.0
PERF_TYPE_TO_KEYWORD = {'mrr': 'Traffic should pass with maximum rate', 'ndrpdr': 'Find NDR and PDR intervals using optimized search', 'soak': 'Find critical load using PLRsearch'}
PERF_TYPE_TO_SUITE_DOC_VER = {'mrr': 'fication:** In MaxReceivedRate tests TG sends traffic at \\\n| ... | line rate and reports total received packets over trial period. \\', 'ndrpdr': 'rification:** TG finds and reports throughput NDR (Non \\\n| ... | Drop Rate) with zero packet loss tolerance and throughput PDR \\\n| ... | (Partial Drop Rate) with non-zero packet loss tolerance (LT) \\\n| ... | expressed in percentage of packets transmitted. NDR and PDR are \\\n| ... | discovered for different Ethernet L2 frame sizes using MLRsearch \\\n| ... | library.', 'soak': 'rification:** TG sends traffic at dynamically computed \\\n| ... | rate as PLRsearch algorithm gathers data and improves its estimate \\\n| ... | of a rate at which a prescribed small fraction of packets \\\n| ... | would be lost. After set time, the serarch stops \\\n| ... | and the algorithm reports its current estimate. \\'}
PERF_TYPE_TO_TEMPLATE_DOC_VER = {'mrr': 'Measure MaxReceivedRate for ${frame_size}B frames \\\n| | ... | using burst trials throughput test. \\', 'ndrpdr': 'Measure NDR and PDR values using MLRsearch algorithm.', 'soak': 'Estimate critical rate using PLRsearch algorithm. \\'}
PERF_USE_LATENCY = False
QEMU_BIN_PATH = '/usr/bin'
QEMU_VM_DPDK = '/opt/dpdk-22.03'
QEMU_VM_IMAGE = '/var/lib/vm/image.iso'
QEMU_VM_KERNEL = '/opt/boot/vmlinuz'
QEMU_VM_KERNEL_INITRD = '/opt/boot/initrd.img'
REMOTE_FW_DIR = '/tmp/openvpp-testing'
RESOURCES_LIB_PY = 'resources/libraries/python'
RESOURCES_LIB_SH = 'resources/libraries/bash'
RESOURCES_PAPI_PROVIDER = 'resources/tools/papi/vpp_papi_provider.py'
RESOURCES_TOOLS = 'resources/tools'
RESOURCES_TPL = 'resources/templates'
RESOURCES_TPL_CONTAINER = 'resources/templates/container'
RESOURCES_TPL_K8S = 'resources/templates/kubernetes'
RESOURCES_TPL_TELEMETRY = 'resources/templates/telemetry'
RESOURCES_TPL_VAT = 'resources/templates/vat'
RESOURCES_TPL_VCL = 'resources/templates/vcl'
SOCKSTAT_PATH = '/run/vpp/stats.sock'
SOCKSVR_PATH = '/run/vpp/api.sock'
TREX_CORE_COUNT = 16
TREX_EXTRA_CMDLINE = '--mbuf-factor 32'
TREX_INSTALL_DIR = '/opt/trex-core-2.97'
TREX_LIMIT_MEMORY = 8192
TREX_PCAP_DIR = '/opt/trex-core-2.97/scripts/avl'
TREX_RX_DESCRIPTORS_COUNT = 0
TREX_SEND_FORCE = False
TREX_TX_DESCRIPTORS_COUNT = 0
VAT_BIN_NAME = 'vpp_api_test'
VCL_LDPRELOAD_LIBRARY = '/usr/lib/x86_64-linux-gnu/libvcl_ldpreload.so'
VPP_UNIT = 'vpp'
resources.libraries.python.Constants.get_float_from_env(env_var_names, default_value)

Attempt to read float from environment variable, return that or default.

String value is read, default is returned also if conversion fails.

Parameters
  • env_var_names (str, or list of str, or tuple of str) – Base names of environment variable to attempt to read.

  • default_value (float) – Value to return if read or conversion fails.

Returns

The value read, or default value.

Return type

float

resources.libraries.python.Constants.get_int_from_env(env_var_names, default_value)

Attempt to read int from environment variable, return that or default.

String value is read, default is returned also if conversion fails.

Parameters
  • env_var_names (str, or list of str, or tuple of str) – Base names of environment variable to attempt to read.

  • default_value (int) – Value to return if read or conversion fails.

Returns

The value read, or default value.

Return type

int

resources.libraries.python.Constants.get_optimistic_bool_from_env(env_var_names)

Attempt to read bool from environment variable, assume True by default.

Conversion is lenient and optimistic, only few strings are considered false.

Parameters

env_var_names (str, or list of str, or tuple of str) – Base names of environment variable to attempt to read.

Returns

The value read, or True.

Return type

bool

resources.libraries.python.Constants.get_pessimistic_bool_from_env(env_var_names)

Attempt to read bool from environment variable, assume False by default.

Conversion is lenient and pessimistic, only few strings are considered true.

Parameters

env_var_names (str, or list of str, or tuple of str) – Base names of environment variable to attempt to read.

Returns

The value read, or False.

Return type

bool

resources.libraries.python.Constants.get_str_from_env(env_var_names, default_value)

Attempt to read string from environment variable, return that or default.

If environment variable exists, but is empty (and default is not), empty string is returned.

Several environment variable names are examined, as CSIT currently supports a mix of naming conventions. Here “several” means there are hard coded prefixes to try, and env_var_names itself can be single name, or a list or a tuple of names.

Parameters
  • env_var_names (str, or list of str, or tuple of str) – Base names of environment variable to attempt to read.

  • default_value (str) – Value to return if the env var does not exist.

Returns

The value read, or default value.

Return type

str

2.12. ContainerUtils suite

Library to manipulate Containers.

class resources.libraries.python.ContainerUtils.Container

Bases: object

Container class.

class resources.libraries.python.ContainerUtils.ContainerEngine

Bases: object

Abstract class for container engine.

acquire(force)

Acquire/download container.

Parameters

force (bool) – Destroy a container if exists and create.

adjust_privileges()

Adjust privileges to control VPP without sudo.

build()

Build container (compile).

create()

Create/deploy container.

create_base_vpp_startup_config(cpuset_cpus=None)

Create base startup configuration of VPP on container.

Parameters

cpuset_cpus (list.) – List of CPU cores to allocate.

Returns

Base VPP startup configuration.

Return type

VppConfigGenerator

create_vpp_exec_config(template_file, **kwargs)

Create VPP exec configuration on container.

Parameters
  • template_file (str) – File name of a template script.

  • kwargs (dict) – Parameters for script.

create_vpp_startup_config()

Create startup configuration of VPP without DPDK on container.

create_vpp_startup_config_ipsec(cpuset_cpus)

Create startup configuration of VPP with IPsec on container.

Parameters

cpuset_cpus (list) – CPU list to run on.

create_vpp_startup_config_vswitch(cpuset_cpus, rxq, *devices)

Create startup configuration of VPP vswitch.

Parameters
  • cpuset_cpus (list) – CPU list to run on.

  • rxq (int) – Number of interface RX queues.

  • devices (list) – PCI devices.

destroy()

Destroy/remove container.

execute(command)

Execute process inside container.

Parameters

command (str) – Command to run inside container.

info()

Info about container.

initialize()

Initialize container object.

is_container_present()

Check if container is present.

is_container_running()

Check if container is running.

restart_vpp(verify=True)

Restart VPP service inside a container.

start_vpp(verify=True)

Start VPP inside a container.

stop()

Stop container.

system_info()

System info.

verify_vpp()

Verify VPP is running and ready.

verify_vpp_papi(retries=120, retry_wait=1)

Verify that VPP is available for PAPI.

This also opens and caches PAPI connection for quick reuse. The connection is disconnected when ContainerManager decides to do so.

Parameters
  • retries – Check for VPP for this number of times Default: 120

  • retry_wait – Wait for this number of seconds between retries.

verify_vppctl(retries=120, retry_wait=1)

Verify that VPP is installed and running inside container.

This function waits a while so VPP can start. PCI interfaces are listed for debug purposes. When the check passes, VPP API socket is created on remote side, but perhaps its directory does not have the correct access rights yet.

Parameters
  • retries – Check for VPP for this number of times Default: 120

  • retry_wait – Wait for this number of seconds between retries.

class resources.libraries.python.ContainerUtils.ContainerManager(engine)

Bases: object

Container lifecycle management class.

acquire_all_containers()

Acquire all containers.

build_all_containers()

Build all containers.

configure_vpp_in_all_containers(chain_topology, **kwargs)

Configure VPP in all containers.

Parameters
  • chain_topology (str) – Topology used for chaining containers can be chain or cross_horiz. Chain topology is using 1 memif pair per container. Cross_horiz topology is using 1 memif and 1 physical interface in container (only single container can be configured).

  • kwargs (dict) – Named parameters.

construct_container(**kwargs)

Construct container object on node with specified parameters.

Parameters
  • kwargs – Key-value pairs used to construct container.

  • kwargs – dict

construct_containers(**kwargs)

Construct 1..N container(s) on node with specified name.

Ordinal number is automatically added to the name of container as suffix.

Parameters
  • kwargs – Named parameters.

  • kwargs – dict

create_all_containers()

Create all containers.

destroy_all_containers()

Destroy all containers.

execute_on_all_containers(command)

Execute command on all containers.

Parameters

command (str) – Command to execute.

execute_on_container(name, command)

Execute command on container with name.

Parameters
  • name (str) – Container name.

  • command (str) – Command to execute.

get_container_by_name(name)

Get container instance.

Parameters

name (str) – Container name.

Returns

Container instance.

Return type

Container

Raises

RuntimeError – If failed to get container with name.

restart_vpp_in_all_containers(verify=True)

Restart VPP in all containers.

start_vpp_in_all_containers(verify=True)

Start VPP in all containers.

stop_all_containers()

Stop all containers.

verify_vpp_in_all_containers()

Verify that VPP is installed and running in all containers.

class resources.libraries.python.ContainerUtils.Docker

Bases: resources.libraries.python.ContainerUtils.ContainerEngine

Docker implementation.

acquire(force=True)

Pull an image or a repository from a registry.

Parameters

force (bool) – Destroy a container if exists.

Raises

RuntimeError – If pulling a container failed.

build()

Build container (compile).

create()

Create/deploy container.

Raises

RuntimeError – If creating a container failed.

destroy()

Remove a container.

Raises

RuntimeError – If removing a container failed.

execute(command)

Start a process inside a running container.

Runs the specified command inside the container specified by name. The container has to be running already.

Parameters

command (str) – Command to run inside container.

Raises

RuntimeError – If running the command in a container failed.

info()

Return low-level information on Docker objects.

Raises

RuntimeError – If getting info about a container failed.

is_container_present()

Check if container is present on node.

Returns

True if container is present.

Return type

bool

Raises

RuntimeError – If getting info about a container failed.

is_container_running()

Check if container is running on node.

Returns

True if container is running.

Return type

bool

Raises

RuntimeError – If getting info about a container failed.

stop()

Stop running container.

Raises

RuntimeError – If stopping a container failed.

system_info()

Display the docker system-wide information.

Raises

RuntimeError – If displaying system information failed.

class resources.libraries.python.ContainerUtils.LXC

Bases: resources.libraries.python.ContainerUtils.ContainerEngine

LXC implementation.

acquire(force=True)

Acquire a privileged system object where configuration is stored.

Parameters

force (bool) – If a container exists, destroy it and create a new container.

Raises

RuntimeError – If creating the container or writing the container config fails.

build()

Build container (compile).

create()

Create/deploy an application inside a container on system.

Raises

RuntimeError – If creating the container fails.

destroy()

Destroy a container.

Raises

RuntimeError – If destroying container failed.

execute(command)

Start a process inside a running container.

Runs the specified command inside the container specified by name. The container has to be running already.

Parameters

command (str) – Command to run inside container.

Raises

RuntimeError – If running the command failed.

info()

Query and shows information about a container.

Raises

RuntimeError – If getting info about a container failed.

is_container_present()

Check if container is existing on node.

Returns

True if container is present.

Return type

bool

Raises

RuntimeError – If getting info about a container failed.

is_container_running()

Check if container is running on node.

Returns

True if container is running.

Return type

bool

Raises

RuntimeError – If getting info about a container failed.

stop()

Stop a container.

Raises

RuntimeError – If stopping the container failed.

system_info()

Check the current kernel for LXC support.

Raises

RuntimeError – If checking LXC support failed.

2.13. CoreDumpUtil suite

Core dump library.

class resources.libraries.python.CoreDumpUtil.CoreDumpUtil

Bases: object

Class contains methods for processing core dumps.

ROBOT_LIBRARY_SCOPE = 'GLOBAL'
static enable_coredump_limit(node, pid)

Enable coredump for PID(s) by setting no core limits.

Parameters
  • node (dict) – Node in the topology.

  • pid (list or int) – Process ID(s) to set core dump limit to unlimited.

enable_coredump_limit_vpp(node)

Enable coredump for VPP PID by setting no core limits on DUT if setting of core limit by this library is enabled.

Parameters

node (dict) – DUT Node in the topology.

enable_coredump_limit_vpp_on_all_duts(nodes)

Enable coredump for all VPP PIDs by setting no core limits on all DUTs if setting of core limit by this library is enabled.

Parameters

nodes (dict) – Nodes in the topology.

get_core_files_on_all_nodes(nodes, disable_on_success=True)

Process all core files and remove the original core files on all nodes.

Parameters
  • nodes (dict) – Nodes in the topology.

  • disable_on_success (bool) – If True, disable setting of core limit by this instance of library. Default: True

is_core_limit_enabled()

Check if core limit is set for process.

Returns

True if core limit is set for process.

Return type

bool

set_core_limit_disabled()

Disable setting of core limit for PID.

set_core_limit_enabled()

Enable setting of core limit for PID.

setup_corekeeper_on_all_nodes(nodes)

Setup core dumps system wide on all nodes.

Parameters

nodes (dict) – Nodes in the topology.

2.14. CpuUtils suite

CPU utilities library.

class resources.libraries.python.CpuUtils.CpuUtils

Bases: object

CPU utilities

NR_OF_THREADS = 2
static cpu_list_per_node(node, cpu_node, smt_used=False)

Return node related list of CPU numbers.

Parameters
  • node (dict) – Node dictionary with cpuinfo.

  • cpu_node (int) – Numa node number.

  • smt_used (bool) – True - we want to use SMT, otherwise false.

Returns

List of cpu numbers related to numa from argument.

Return type

list of int

Raises

RuntimeError – If node cpuinfo is not available or if SMT is not enabled.

static cpu_list_per_node_str(node, cpu_node, skip_cnt=0, cpu_cnt=0, sep=',', smt_used=False)

Return string of node related list of CPU numbers.

Parameters
  • node (dict) – Node dictionary with cpuinfo.

  • cpu_node (int) – Numa node number.

  • skip_cnt (int) – Skip first “skip_cnt” CPUs.

  • cpu_cnt (int) – Count of cpus to return, if 0 then return all.

  • sep (str) – Separator, default: 1,2,3,4,….

  • smt_used (bool) – True - we want to use SMT, otherwise false.

Returns

Cpu numbers related to numa from argument.

Return type

str

static cpu_node_count(node)

Return count of numa nodes.

Parameters

node (dict) – Targeted node.

Returns

Count of numa nodes.

Return type

int

Raises

RuntimeError – If node cpuinfo is not available.

static cpu_range_per_node_str(node, cpu_node, skip_cnt=0, cpu_cnt=0, sep='-', smt_used=False)

Return string of node related range of CPU numbers, e.g. 0-4.

Parameters
  • node (dict) – Node dictionary with cpuinfo.

  • cpu_node (int) – Numa node number.

  • skip_cnt (int) – Skip first “skip_cnt” CPUs.

  • cpu_cnt (int) – Count of cpus to return, if 0 then return all.

  • sep (str) – Separator, default: “-“.

  • smt_used (bool) – True - we want to use SMT, otherwise false.

Returns

String of node related range of CPU numbers.

Return type

str

static cpu_slice_of_list_for_nf(node, cpu_node, nf_chains=1, nf_nodes=1, nf_chain=1, nf_node=1, nf_dtc=1, nf_mtcr=2, nf_dtcr=1, skip_cnt=0)

Return list of DUT node related list of CPU numbers. The main computing unit is physical core count.

Parameters
  • node (dict) – DUT node.

  • cpu_node – Numa node number.

  • nf_chains (int) – Number of NF chains.

  • nf_nodes (int) – Number of NF nodes in chain.

  • nf_chain (int) – Chain number indexed from 1.

  • nf_node (int) – Node number indexed from 1.

  • nf_dtc (int or float) – Amount of physical cores for NF data plane.

  • nf_mtcr (int) – NF main thread per core ratio.

  • nf_dtcr (int) – NF data plane thread per core ratio.

  • skip_cnt (int) – Skip first “skip_cnt” CPUs.

  • cpu_node – int.

Returns

List of CPUs allocated to NF.

Return type

list

Raises

RuntimeError – If we require more cpus than available or if placement is not possible due to wrong parameters.

static cpu_slice_of_list_per_node(node, cpu_node, skip_cnt=0, cpu_cnt=0, smt_used=False)

Return node related subset of list of CPU numbers.

Parameters
  • node (dict) – Node dictionary with cpuinfo.

  • cpu_node (int) – Numa node number.

  • skip_cnt (int) – Skip first “skip_cnt” CPUs.

  • cpu_cnt (int) – Count of cpus to return, if 0 then return all.

  • smt_used (bool) – True - we want to use SMT, otherwise false.

Returns

Cpu numbers related to numa from argument.

Return type

list

Raises

RuntimeError – If we require more cpus than available.

static get_affinity_af_xdp(node, pf_key, cpu_skip_cnt=0, cpu_cnt=1)

Get affinity for AF_XDP interface. Result will be used to pin IRQs.

Parameters
  • node (dict) – Topology node.

  • pf_key (str) – Topology interface.

  • cpu_skip_cnt (int) – Amount of CPU cores to skip.

  • cpu_cnt (int) – CPU threads count.

Returns

List of CPUs allocated to AF_XDP interface.

Return type

list

static get_affinity_iperf(node, pf_key, cpu_skip_cnt=0, cpu_cnt=1)

Get affinity for iPerf3. Result will be used to pin iPerf3 threads.

Parameters
  • node (dict) – Topology node.

  • pf_key (str) – Topology interface.

  • cpu_skip_cnt (int) – Amount of CPU cores to skip.

  • cpu_cnt (int) – CPU threads count.

Returns

List of CPUs allocated to iPerf3.

Return type

str

static get_affinity_nf(nodes, node, nf_chains=1, nf_nodes=1, nf_chain=1, nf_node=1, vs_dtc=1, nf_dtc=1, nf_mtcr=2, nf_dtcr=1)

Get affinity of NF (network function). Result will be used to compute the amount of CPUs and also affinity.

Parameters
  • nodes (dict) – Physical topology nodes.

  • node (dict) – SUT node.

  • nf_chains (int) – Number of NF chains.

  • nf_nodes (int) – Number of NF nodes in chain.

  • nf_chain (int) – Chain number indexed from 1.

  • nf_node (int) – Node number indexed from 1.

  • vs_dtc (int) – Amount of physical cores for vswitch data plane.

  • nf_dtc (int or float) – Amount of physical cores for NF data plane.

  • nf_mtcr (int) – NF main thread per core ratio.

  • nf_dtcr (int) – NF data plane thread per core ratio.

Returns

List of CPUs allocated to NF.

Return type

list

static get_affinity_trex(node, if1_pci, if2_pci, tg_mtc=1, tg_dtc=1, tg_ltc=1)

Get affinity for T-Rex. Result will be used to pin T-Rex threads.

Parameters
  • node (dict) – TG node.

  • if1_pci (str) – TG first interface.

  • if2_pci (str) – TG second interface.

  • tg_mtc (int) – TG main thread count.

  • tg_dtc (int) – TG dataplane thread count.

  • tg_ltc (int) – TG latency thread count.

Returns

List of CPUs allocated to T-Rex including numa node.

Return type

int, int, int, list

static get_affinity_vhost(node, pf_key, skip_cnt=0, cpu_cnt=1)

Get affinity for vhost. Result will be used to pin vhost threads.

Parameters
  • node (dict) – Topology node.

  • pf_key (str) – Topology interface.

  • skip_cnt (int) – Amount of CPU cores to skip.

  • cpu_cnt (int) – CPU threads count.

Returns

List of CPUs allocated to vhost process.

Return type

str

static get_affinity_vswitch(nodes, node, phy_cores, rx_queues=None, rxd=None, txd=None)

Get affinity for vswitch.

Parameters
  • nodes (dict) – Topology nodes.

  • node (str) – Topology node string.

  • phy_cores (int) – Number of physical cores to allocate.

  • rx_queues (int) – Number of RX queues. (Optional, Default: None)

  • rxd (int) – Number of RX descriptors. (Optional, Default: None)

  • txd (int) – Number of TX descriptors. (Optional, Default: None)

Returns

Compute resource information dictionary.

Return type

dict

static get_cpu_idle_list(node, cpu_node, smt_used, cpu_alloc_str, sep=',')

Get idle CPU List.

Parameters
  • node (dict) – Node dictionary with cpuinfo.

  • cpu_node (int) – Numa node number.

  • smt_used (bool) – True - we want to use SMT, otherwise false.

  • cpu_alloc_str (str) – vpp used cores.

  • sep (str) – Separator, default: “,”.

Return type

list

static get_cpu_info_from_all_nodes(nodes)
Assuming all nodes are Linux nodes, retrieve the following
cpu information from all nodes:
  • cpu architecture

  • cpu layout

Parameters

nodes (dict) – DICT__nodes from Topology.DICT__nodes.

Raises

RuntimeError – If an ssh command retrieving cpu information fails.

static is_smt_enabled(cpu_info)

Uses CPU mapping to find out if SMT is enabled or not. If SMT is enabled, the L1d,L1i,L2,L3 setting is the same for two processors. These two processors are two threads of one core.

Parameters

cpu_info (list) – CPU info, the output of “lscpu -p”.

Returns

True if SMT is enabled, False if SMT is disabled.

Return type

bool

2.15. DUTSetup suite

DUT setup library.

class resources.libraries.python.DUTSetup.DUTSetup

Bases: object

Contains methods for setting up DUTs.

static check_huge_page(node, huge_mnt, mem_size, hugesize=2048, allocate=False)

Check if there is enough HugePages in system. If allocate is set to true, try to allocate more HugePages.

Parameters
  • node (dict) – Node in the topology.

  • huge_mnt (str) – HugePage mount point.

  • mem_size (int) – Reqeusted memory in MB.

  • hugesize (int) – HugePage size in KB.

  • allocate (bool) – Whether to allocate more memory if not enough.

Raises

RuntimeError – Mounting hugetlbfs failed or not enough HugePages or increasing map count failed.

static crypto_device_init(node, crypto_type, numvfs)

Init Crypto QAT device virtual functions on DUT.

Parameters
  • node (dict) – DUT node.

  • numvfs (int) – Number of VFs to initialize, 0 - disable the VFs.

Crypto_type

Crypto device type - HW_DH895xcc or HW_C3xxx.

Returns

nothing

Raises

RuntimeError – If failed to stop VPP or QAT failed to initialize.

static crypto_device_verify(node, crypto_type, numvfs, force_init=False)

Verify if Crypto QAT device virtual functions are initialized on all DUTs. If parameter force initialization is set to True, then try to initialize or remove VFs on QAT.

Parameters
  • node (dict) – DUT node.

  • numvfs (int) – Number of VFs to initialize, 0 - disable the VFs.

  • force_init (bool) – If True then try to initialize to specific value.

Crypto_type

Crypto device type - HW_DH895xcc or HW_C3xxx.

Returns

nothing

Raises

RuntimeError – If QAT VFs are not created and force init is set to False.

static get_docker_mergeddir(node, uuid)

Get Docker overlay for MergedDir diff.

Parameters
  • node (dict) – DUT node.

  • uuid (str) – Docker UUID.

Returns

Docker container MergedDir.

Return type

str

Raises

RuntimeError – If getting output failed.

static get_hugepages_info(node, hugesize=None)

Get number of huge pages in system.

Parameters
  • node (dict) – Node in the topology.

  • hugesize (int) – Size of hugepages. Default system huge size if None.

Returns

Number of huge pages in system.

Return type

dict

Raises

RuntimeError – If reading failed.

static get_pci_dev_driver(node, pci_addr)

Get current PCI device driver on node.

Parameters
  • node (dict) – DUT node.

  • pci_addr (str) – PCI device address.

Returns

Driver or None

Raises

RuntimeError – If it is not possible to get the interface driver information from the node.

static get_pid(node, process)

Get PID of running process.

Parameters
  • node (dict) – DUT node.

  • process (str) – process name.

Returns

PID

Return type

int

Raises

RuntimeError – If it is not possible to get the PID.

static get_service_logs(node, service)

Get specific service unit logs from node.

Parameters
  • node (dict) – Node in the topology.

  • service (str) – Service unit name.

static get_service_logs_on_all_duts(nodes, service)

Get specific service unit logs from all DUTs.

Parameters
  • nodes (dict) – Nodes in the topology.

  • service (str) – Service unit name.

static get_sriov_numvfs(node, pf_pci_addr)

Get number of SR-IOV VFs.

Parameters
  • node (dict) – DUT node.

  • pf_pci_addr (str) – Physical Function PCI device address.

Returns

Number of VFs.

Return type

int

Raises

RuntimeError – If PCI device is not SR-IOV capable.

static get_virtfn_pci_addr(node, pf_pci_addr, vf_id)

Get PCI address of Virtual Function.

Parameters
  • node (dict) – DUT node.

  • pf_pci_addr (str) – Physical Function PCI address.

  • vf_id (int) – Virtual Function number.

Returns

Virtual Function PCI address.

Return type

str

Raises

RuntimeError – If failed to get Virtual Function PCI address.

static get_vpp_pids(nodes)

Get PID of running VPP process on all DUTs.

Parameters

nodes (dict) – DUT nodes.

Returns

PIDs

Return type

dict

static install_vpp_on_all_duts(nodes, vpp_pkg_dir)

Install VPP on all DUT nodes. Start the VPP service in case of systemd is not available or does not support autostart.

Parameters
  • nodes (dict) – Nodes in the topology.

  • vpp_pkg_dir (str) – Path to directory where VPP packages are stored.

Raises

RuntimeError – If failed to remove or install VPP.

static kill_program(node, program, namespace=None)

Kill program on the specified topology node.

Parameters
  • node (dict) – Topology node.

  • program (str) – Program name.

  • namespace (str) – Namespace program is running in.

static load_kernel_module(node, module)

Load kernel module on node.

Parameters
  • node (dict) – DUT node.

  • module (str) – Module to load.

Returns

nothing

Raises

RuntimeError – If loading failed.

static pci_driver_bind(node, pci_addr, driver)

Bind PCI device to driver on node.

Parameters
  • node (dict) – DUT node.

  • pci_addr (str) – PCI device address.

  • driver (str) – Driver to bind.

Raises

RuntimeError – If PCI device bind failed.

static pci_driver_unbind(node, pci_addr)

Unbind PCI device from current driver on node.

Parameters
  • node (dict) – DUT node.

  • pci_addr (str) – PCI device address.

Raises

RuntimeError – If PCI device unbind failed.

static pci_vf_driver_bind(node, pf_pci_addr, vf_id, driver)

Bind Virtual Function to driver on node.

Parameters
  • node (dict) – DUT node.

  • pf_pci_addr (str) – PCI device address.

  • vf_id (int) – Virtual Function ID.

  • driver (str) – Driver to bind.

Raises

RuntimeError – If PCI device bind failed.

static pci_vf_driver_unbind(node, pf_pci_addr, vf_id)

Unbind Virtual Function from driver on node.

Parameters
  • node (dict) – DUT node.

  • pf_pci_addr (str) – PCI device address.

  • vf_id (int) – Virtual Function ID.

Raises

RuntimeError – If Virtual Function unbind failed.

static restart_service(node, service)

Restart the named service on node.

Parameters
  • node (dict) – Node in the topology.

  • service (str) – Service unit name.

static restart_service_on_all_duts(nodes, service)

Restart the named service on all DUTs.

Parameters
  • nodes (dict) – Nodes in the topology.

  • service (str) – Service unit name.

static running_in_container(node)

This method tests if topology node is running inside container.

Parameters

node (dict) – Topology node.

Returns

True if running in docker container, false if not or failed to detect.

Return type

bool

static set_sriov_numvfs(node, pf_pci_addr, numvfs=0)

Init or reset SR-IOV virtual functions by setting its number on PCI device on DUT. Setting to zero removes all VFs.

Parameters
  • node (dict) – DUT node.

  • pf_pci_addr (str) – Physical Function PCI device address.

  • numvfs (int) – Number of VFs to initialize, 0 - removes the VFs.

Raises

RuntimeError – Failed to create VFs on PCI.

static start_service(node, service)

Start up the named service on node.

Parameters
  • node (dict) – Node in the topology.

  • service (str) – Service unit name.

static start_service_on_all_duts(nodes, service)

Start up the named service on all DUTs.

Parameters
  • nodes (dict) – Nodes in the topology.

  • service (str) – Service unit name.

static stop_service(node, service)

Stop the named service on node.

Parameters
  • node (dict) – Node in the topology.

  • service (str) – Service unit name.

static stop_service_on_all_duts(nodes, service)

Stop the named service on all DUTs.

Parameters
  • nodes (dict) – Nodes in the topology.

  • service (str) – Service unit name.

static unbind_pci_devices_from_other_driver(node, driver, *pci_addrs)

Unbind PCI devices from driver other than input driver on node.

Parameters
  • node (dict) – DUT node.

  • driver (str) – Driver to not unbind from. If None or empty string, will attempt to unbind from the current driver.

  • pci_addrs (list) – PCI device addresses.

static verify_kernel_module(node, module, force_load=False)

Verify if kernel module is loaded on node. If parameter force load is set to True, then try to load the modules.

Parameters
  • node (dict) – Node.

  • module (str) – Module to verify.

  • force_load (bool) – If True then try to load module.

Raises

RuntimeError – If module is not loaded or failed to load.

static verify_kernel_module_on_all_duts(nodes, module, force_load=False)

Verify if kernel module is loaded on all DUTs. If parameter force load is set to True, then try to load the modules.

Parameters
  • nodes (dict) – DUT nodes.

  • module (str) – Module to verify.

  • force_load (bool) – If True then try to load module.

static verify_program_installed(node, program)

Verify that program is installed on the specified topology node.

Parameters
  • node (dict) – Topology node.

  • program (str) – Program name.

static verify_uio_driver_on_all_duts(nodes)

Verify if uio driver kernel module is loaded on all DUTs. If module is not present it will try to load it.

Parameters

nodes (dict) – DUT nodes.

2.16. Dhcp suite

DHCP utilities for VPP.

class resources.libraries.python.Dhcp.DhcpProxy

Bases: object

DHCP Proxy utilities.

static vpp_get_dhcp_proxy(node, ip_version)

Retrieve DHCP relay configuration.

Parameters
  • node (dict) – VPP node.

  • ip_version (str) – IP protocol version: ipv4 or ipv6.

Returns

DHCP relay data.

Return type

list

2.17. DpdkUtil suite

Dpdk Utilities Library.

class resources.libraries.python.DpdkUtil.DpdkUtil

Bases: object

Utilities for DPDK.

static dpdk_testpmd_start(node, **kwargs)

Start DPDK testpmd app on VM node.

Parameters
  • node (dict) – VM Node to start testpmd on.

  • kwargs (dict) – Key-value testpmd parameters.

static dpdk_testpmd_stop(node)

Stop DPDK testpmd app on node.

Parameters

node (dict) – Node to stop testpmd on.

Returns

nothing

static get_eal_options(**kwargs)

Create EAL parameters options (including -v).

Parameters

kwargs (dict) – Dict of testpmd parameters.

Returns

EAL parameters.

Return type

OptionString

static get_l3fwd_args(**kwargs)

Get DPDK l3fwd command line arguments.

Parameters

kwargs (dict) – Key-value l3fwd parameters.

Returns

Command line string.

Return type

OptionString

static get_l3fwd_pmd_options(**kwargs)

Create PMD parameters options for l3fwd (without –).

Parameters

kwargs (dict) – List of l3fwd parameters.

Returns

PMD parameters.

Return type

OptionString

static get_testpmd_args(**kwargs)

Get DPDK testpmd command line arguments.

Parameters

kwargs (dict) – Key-value testpmd parameters.

Returns

Command line string.

Return type

OptionString

static get_testpmd_cmdline(**kwargs)

Get DPDK testpmd command line arguments with testpmd command.

Parameters

kwargs (dict) – Key-value testpmd parameters.

Returns

Command line string.

Return type

OptionString

static get_testpmd_pmd_options(**kwargs)

Create PMD parameters options for testpmd (without –).

Parameters

kwargs (dict) – List of testpmd parameters.

Returns

PMD parameters.

Return type

OptionString

2.18. DropRateSearch suite

Drop rate search algorithms

class resources.libraries.python.DropRateSearch.DropRateSearch

Bases: object

Abstract class with search algorithm implementation.

Binary search of rate with loss below acceptance criteria.

Parameters
  • b_min (float) – Min range rate.

  • b_max (float) – Max range rate.

  • traffic_profile (str) – Module name to use for traffic generation.

  • skip_max_rate (bool) – Start with max rate first

  • skip_warmup (bool) – Start TRex without warmup traffic if true.

Returns

nothing

Raises

ValueError – If input values are not valid.

Combined search of rate with loss below acceptance criteria.

Parameters
  • start_rate (float) – Initial rate.

  • traffic_profile (str) – Module name to use for traffic generation.

Returns

nothing

Raises

RuntimeError – If linear search failed.

static floats_are_close_equal(num_a, num_b, rel_tol=1e-09, abs_tol=0.0)

Compares two float numbers for close equality.

Parameters
  • num_a (float) – First number to compare.

  • num_b (float) – Second number to compare.

  • rel_tol (float) – The relative tolerance.

  • abs_tol (float) – The minimum absolute tolerance level. (Optional, default value: 0.0)

Returns

Returns True if num_a is close in value to num_b or equal. False otherwise.

Return type

boolean

Raises

ValueError – If input values are not valid.

get_binary_convergence_threshold()

Get convergence for binary search.

Returns

Threshold value number.

Return type

float

get_duration()

Return configured duration of single traffic run.

Returns

Number of seconds for traffic to run.

Return type

int

abstract get_latency()

Return min/avg/max latency.

Returns

Latency stats.

Return type

list

get_loss_acceptance()

Return configured loss acceptance threshold.

Returns

Loss acceptance threshold.

Return type

float

get_max_attempts()

Return maximum number of traffic runs during one rate step.

Returns

Number of traffic runs.

Return type

int

get_rate_type_str()

Return rate type representation.

Returns

String representation of rate type.

Return type

str

Raises

ValueError – If rate type is unknown.

Linear search of rate with loss below acceptance criteria.

Parameters
  • start_rate (float) – Initial rate.

  • traffic_profile (str) – Module name to use for traffic generation.

Returns

nothing

Raises

ValueError – If start rate is not in range.

loss_acceptance_type_is_percentage()
Return true if loss acceptance threshold type is percentage,

false otherwise.

Returns

True if loss acceptance threshold type is percentage.

Return type

boolean

abstract measure_loss(rate, frame_size, loss_acceptance, loss_acceptance_type, traffic_profile, skip_warmup=False)

Send traffic from TG and measure count of dropped frames.

Parameters
  • rate (float) – Offered traffic load.

  • frame_size (str) – Size of frame.

  • loss_acceptance (float) – Permitted drop ratio or frames count.

  • loss_acceptance_type (LossAcceptanceType) – Type of permitted loss.

  • traffic_profile (str) – Module name to use for traffic generation.

  • skip_warmup (bool) – Start TRex without warmup traffic if true.

Returns

Drop threshold exceeded? (True/False)

Return type

bool

set_binary_convergence_threshold(convergence)

Set convergence for binary search.

Parameters

convergence (float) – Threshold value number.

Returns

nothing

set_duration(duration)

Set the duration of single traffic run.

Parameters

duration (int) – Number of seconds for traffic to run.

Returns

nothing

set_loss_acceptance(loss_acceptance)

Set loss acceptance threshold for PDR search.

Parameters

loss_acceptance (str) – Loss acceptance threshold for PDR search.

Returns

nothing

Raises

ValueError – If loss acceptance is lower than zero.

set_loss_acceptance_type_frames()

Set loss acceptance threshold type to frames.

Returns

nothing

set_loss_acceptance_type_percentage()

Set loss acceptance threshold type to percentage.

Returns

nothing

set_max_attempts(max_attempts)

Set maximum number of traffic runs during one rate step.

Parameters

max_attempts (int) – Number of traffic runs.

Returns

nothing

Raises

ValueError – If max attempts is lower than zero.

set_search_frame_size(frame_size)

Set size of frames to send.

Parameters

frame_size (str) – Size of frames.

Returns

nothing

set_search_linear_step(step_rate)

Set step size for linear search.

Parameters

step_rate (float) – Linear search step size.

Returns

nothing

set_search_rate_boundaries(max_rate, min_rate)

Set search boundaries: min,max.

Parameters
  • max_rate (float) – Upper value of search boundaries.

  • min_rate (float) – Lower value of search boundaries.

Returns

nothing

Raises

ValueError – If min rate is lower than 0 or higher than max rate.

set_search_rate_type_bps()

Set rate type to bits per second.

Returns

nothing

set_search_rate_type_percentage()

Set rate type to percentage of linerate.

Returns

nothing

set_search_rate_type_pps()

Set rate type to packets per second.

Returns

nothing

set_search_result_type_best_of_n()

Set type of search result evaluation to Best of N.

Returns

nothing

set_search_result_type_worst_of_n()

Set type of search result evaluation to Worst of N.

Returns

nothing

verify_search_result()

Fail if search was not successful.

Returns

Result rate and latency stats.

Return type

tuple

Raises

Exception – If search failed.

class resources.libraries.python.DropRateSearch.LossAcceptanceType(value)

Bases: enum.Enum

Type of the loss acceptance criteria.

FRAMES = 1
PERCENTAGE = 2
class resources.libraries.python.DropRateSearch.RateType(value)

Bases: enum.Enum

Type of rate units.

BITS_PER_SECOND = 3
PACKETS_PER_SECOND = 2
PERCENTAGE = 1
class resources.libraries.python.DropRateSearch.SearchDirection(value)

Bases: enum.Enum

Direction of linear search.

BOTTOM_UP = 2
TOP_DOWN = 1
class resources.libraries.python.DropRateSearch.SearchResultType(value)

Bases: enum.Enum

Type of search result evaluation.

BEST_OF_N = 1
WORST_OF_N = 2
class resources.libraries.python.DropRateSearch.SearchResults(value)

Bases: enum.Enum

Result of the drop rate search.

FAILURE = 2
SUCCESS = 1
SUSPICIOUS = 3

2.19. FilteredLogger suite

Python library for customizing robot.api.logger

As robot.api.logger is a module, it is not easy to copy, edit or inherit from. This module offers a class to wrap it. The main point of the class is to lower verbosity of Robot logging, especially when injected to third party code (such as vpp_papi.VPPApiClient).

Also, String formatting using ‘%’ operator is supported.

Logger.console() is not supported.

class resources.libraries.python.FilteredLogger.FilteredLogger(logger_module, min_level='INFO')

Bases: object

Instances of this class have the similar API to robot.api.logger.

TODO: Support html argument? TODO: Support console with a filtering switch?

debug(message, farg=None)

Forward the message using the DEBUG level.

error(message, farg=None)

Forward the message using the ERROR level.

info(message, farg=None)

Forward the message using the INFO level.

trace(message, farg=None)

Forward the message using the TRACE level.

warn(message, farg=None)

Forward the message using the WARN level.

write(message, farg=None, level='INFO')

Forwards the message to logger if min_level is reached.

Formatting using ‘%’ operator is used when farg argument is suplied.

Parameters
  • message (str) – Message to log.

  • farg (NoneTye, or whatever '%' accepts: str, int, float, dict...) – Value for ‘%’ operator, or None.

  • level (str) – Level to possibly log with.

2.20. FlowUtil suite

Flow Utilities Library.

class resources.libraries.python.FlowUtil.FlowAction(value)

Bases: enum.IntEnum

Flow actions.

FLOW_ACTION_DROP = 64
FLOW_ACTION_MARK = 2
FLOW_ACTION_REDIRECT_TO_QUEUE = 16
class resources.libraries.python.FlowUtil.FlowProto(value)

Bases: enum.IntEnum

Flow protocols.

IP_API_PROTO_AH = 51
IP_API_PROTO_ESP = 50
IP_API_PROTO_L2TP = 115
IP_API_PROTO_TCP = 6
IP_API_PROTO_UDP = 17
class resources.libraries.python.FlowUtil.FlowType(value)

Bases: enum.IntEnum

Flow types.

FLOW_TYPE_ETHERNET = 1
FLOW_TYPE_IP4 = 2
FLOW_TYPE_IP4_GTPU = 14
FLOW_TYPE_IP4_IPSEC_AH = 6
FLOW_TYPE_IP4_IPSEC_ESP = 5
FLOW_TYPE_IP4_L2TPV3OIP = 4
FLOW_TYPE_IP4_N_TUPLE = 7
FLOW_TYPE_IP4_VXLAN = 11
FLOW_TYPE_IP6 = 3
FLOW_TYPE_IP6_N_TUPLE = 8
FLOW_TYPE_IP6_VXLAN = 12
class resources.libraries.python.FlowUtil.FlowUtil

Bases: object

Utilities for flow configuration.

static vpp_create_ip4_flow(node, src_ip, dst_ip, proto, action, value=0)

Create IP4 flow.

Parameters
  • node (dict) – DUT node.

  • src_ip (str) – Source IP4 address.

  • dst_ip (str) – Destination IP4 address.

  • proto (str) – TCP or UDP.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_create_ip4_gtpu_flow(node, src_ip, dst_ip, teid, action, value=0)

Create IP4_GTPU flow.

Parameters
  • node (dict) – DUT node.

  • src_ip (str) – Source IP4 address.

  • dst_ip (str) – Destination IP4 address.

  • teid (int) – Tunnel endpoint identifier.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_create_ip4_ipsec_flow(node, proto, spi, action, value=0)

Create IP4_IPSEC flow.

Parameters
  • node (dict) – DUT node.

  • proto (str) – TCP or UDP.

  • spi (int) – Security Parameters Index.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_create_ip4_l2tp_flow(node, session_id, action, value=0)

Create IP4_L2TPV3OIP flow.

Parameters
  • node (dict) – DUT node.

  • session_id (int) – PPPoE session ID

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_create_ip4_n_tuple_flow(node, src_ip, dst_ip, src_port, dst_port, proto, action, value=0)

Create IP4_N_TUPLE flow.

Parameters
  • node (dict) – DUT node.

  • src_ip (str) – Source IP4 address.

  • dst_ip (str) – Destination IP4 address.

  • src_port (int) – Source port.

  • dst_port (int) – Destination port.

  • proto (str) – TCP or UDP.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_create_ip4_vxlan_flow(node, src_ip, dst_ip, vni, action, value=0)

Create IP4_VXLAN flow.

Parameters
  • node (dict) – DUT node.

  • src_ip (str) – Source IP4 address.

  • dst_ip (str) – Destination IP4 address.

  • vni (int) – Virtual network instance.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

static vpp_create_ip6_flow(node, src_ip, dst_ip, proto, action, value=0)

Create IP6 flow.

Parameters
  • node (dict) – DUT node.

  • src_ip (str) – Source IP6 address.

  • dst_ip (str) – Destination IP6 address.

  • proto (str) – TCP or UDP.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_create_ip6_n_tuple_flow(node, src_ip, dst_ip, src_port, dst_port, proto, action, value=0)

Create IP6_N_TUPLE flow.

Parameters
  • node (dict) – DUT node.

  • src_ip (str) – Source IP6 address.

  • dst_ip (str) – Destination IP6 address.

  • src_port (int) – Source port.

  • dst_port (int) – Destination port.

  • proto (str) – TCP or UDP.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

static vpp_flow_add(node, flow, flow_type, pattern, action, value=0)

Flow add.

Parameters
  • node (str) – DUT node.

  • flow – Name of flow.

  • flow_type (str) – Type of flow.

  • pattern (dict) – Pattern of flow.

  • action (str) – Mark, drop or redirect-to-queue.

  • value (int) – Action value.

Returns

flow_index.

Return type

int

Raises

ValueError – If action type is not supported.

static vpp_flow_del(node, flow_index=0)

Flow delete.

Parameters
  • node (dict) – DUT node.

  • flow_index (int) – Flow index.

Returns

Nothing.

static vpp_flow_disable(node, interface, flow_index=0)

Flow disable.

Parameters
  • node (dict) – DUT node.

  • interface (int) – Interface sw_if_index.

  • flow_index (int) – Flow index.

Returns

Nothing.

static vpp_flow_enable(node, interface, flow_index=0)

Flow enable.

Parameters
  • node (dict) – DUT node.

  • interface (int) – Interface sw_if_index.

  • flow_index (int) – Flow index.

Returns

Nothing.

static vpp_show_flow_entry(node)

Show flow entry.

Parameters

node (dict) – DUT node.

Returns

flow entry.

Return type

str

static vpp_verify_flow_action(node, action, value, src_mac='11:22:33:44:55:66', dst_mac='11:22:33:44:55:66', src_ip=None, dst_ip=None)

Verify the correctness of the flow action.

Parameters
  • node (dict) – DUT node.

  • action (str) – Action.

  • value (int) – Action value.

  • src_mac (str) – Source mac address.

  • dst_mac (str) – Destination mac address.

  • src_ip (str) – Source IP address.

  • dst_ip (str) – Destination IP address.

Returns

Nothing.

Raises
  • RuntimeError – If the verification of flow action fails.

  • ValueError – If action type is not supported.

2.21. GeneveUtil suite

VPP GENEVE Plugin utilities library.

class resources.libraries.python.GeneveUtil.GeneveUtil

Bases: object

VPP GENEVE Plugin Keywords.

static add_geneve_tunnel(node, local_address, remote_address, vni, multicast_if=None, encap_vrf=0, l3_mode=False, next_index=None)

Add GENEVE tunnel on the specified VPP node.

Parameters
  • node (dict) – Topology node.

  • local_address (str) – Local IP address.

  • remote_address (str) – Remote IP address.

  • vni (int) – Virtual network ID.

  • multicast_if (str) – Interface key of multicast interface; used only if remote is multicast. (Default value = None)

  • encap_vrf (int) – The FIB ID for sending unicast GENEVE encap packets or receiving multicast packets. (Default value = 0)

  • l3_mode (bool) – Use geneve tunnel in L3 mode (ip routing) if Tue else in L2 mode (L2 switching). (Default value = False)

  • next_index (int) – The index of the next node.

Returns

SW interface index of created geneve tunnel.

Return type

int

static enable_interface_geneve_bypass(node, interface, is_ipv6=False)

Add ipv4/ipv6-geneve-bypass graph node for a given interface on the specified VPP node.

Parameters
  • node (dict) – Topology node.

  • interface (str) – Interface key from topology file of interface to add geneve bypass node for.

  • is_ipv6 (bool) – Enable ipv6-geneve-bypass graph node if True else enable ipv4-geneve-bypass graph node.

static show_geneve_tunnel_data(node)

Show the GENEVE tunnels data.

Parameters

node (dict) – DUT node.

static vpp_geneve_add_multiple_tunnels(node, gen_tunnel, n_tunnels, dut_if1, dut_if2, tg_if1_ip4, tg_if2_ip4, tg_pf2_mac, next_idx)

Create multiple GENEVE tunnels.

Parameters
  • node (dict) – DUT node.

  • gen_tunnel (dict) – Parameters of the GENEVE tunnel.

  • n_tunnels (int) – Number of tunnels.

  • dut_if1 (str) – The first DUT interface.

  • dut_if2 (str) – The second DUT interface.

  • tg_if1_ip4 (str) – TG interface 1 IP address.

  • tg_if2_ip4 (str) – TG interface 2 IP address.

  • tg_pf2_mac (str) – TG interface 2 MAC address.

  • next_idx (int) – The index of the next node.

2.22. HoststackUtil suite

Host Stack util library.

class resources.libraries.python.HoststackUtil.HoststackUtil

Bases: object

Utilities for Host Stack tests.

static analyze_hoststack_test_program_output(node, role, nsim_attr, program)

Gather HostStack test program output and check for errors.

The [defer_fail] return bool is used instead of failing immediately to allow the analysis of both the client and server instances of the test program for debugging a test failure. When [defer_fail] is true, then the string returned is debug output instead of JSON formatted test program results.

Parameters
  • node (dict) – DUT node.

  • role (str) – Role (client|server) of test program.

  • nsim_attr (dict) – Network Simulation Attributes.

  • program (dict) – Test program.

  • program_args – List of test program args.

Returns

tuple of [defer_fail] bool and either JSON formatted hoststack test program output or failure debug output.

Return type

bool, str

Raises

RuntimeError – If node subtype is not a DUT.

static get_hoststack_test_program_logs(node, program)

Get HostStack test program stdout log.

Parameters
  • node (dict) – DUT node.

  • program (dict) – test program.

static get_iperf3_command(iperf3_attributes)

Construct the iperf3 command using the specified attributes.

Parameters

iperf3_attributes (dict) – iperf3 test program attributes.

Returns

Command line components of the iperf3 command ‘env_vars’ - environment variables ‘name’ - program name ‘args’ - command arguments.

Return type

dict

static get_nginx_command(nginx_attributes, nginx_version, nginx_ins_dir)

Construct the NGINX command using the specified attributes.

Parameters
  • nginx_attributes (dict) – NGINX test program attributes.

  • nginx_version (str) – NGINX version.

  • nginx_ins_dir (str) – NGINX install dir.

Returns

Command line components of the NGINX command ‘env_vars’ - environment variables ‘name’ - program name ‘args’ - command arguments. ‘path’ - program path.

Return type

dict

static get_vpp_echo_command(vpp_echo_attributes)

Construct the vpp_echo command using the specified attributes.

Parameters

vpp_echo_attributes (dict) – vpp_echo test program attributes.

Returns

Command line components of the vpp_echo command ‘name’ - program name ‘args’ - command arguments.

Return type

dict

static hoststack_test_program_defer_fail(server_defer_fail, client_defer_fail)

Return True if either HostStack test program fail was deferred.

Parameters
  • server_defer_fail (bool) – server no results value.

  • client_defer_fail (bool) – client no results value.

Return type

bool

static hoststack_test_program_finished(node, program_pid)

Wait for the specified HostStack test program process to complete.

Parameters
  • node (dict) – DUT node.

  • program_pid (str) – test program pid.

Raises

RuntimeError – If node subtype is not a DUT.

static log_vpp_hoststack_data(node)

Retrieve and log VPP HostStack data.

Parameters

node (dict) – DUT node.

Raises

RuntimeError – If node subtype is not a DUT or startup failed.

static set_hoststack_quic_crypto_engine(node, quic_crypto_engine, fail_on_error=False)

Set the Hoststack QUIC crypto engine on node

Parameters
  • node (dict) – Node to enable/disable HostStack.

  • quic_crypto_engine (str) – type of crypto engine

static set_hoststack_quic_fifo_size(node, fifo_size)

Set the QUIC protocol fifo size.

Parameters
  • node (dict) – Node to set the QUIC fifo size on.

  • fifo_size (str) – fifo size, passed to the quic set fifo-size command.

static start_hoststack_test_program(node, namespace, core_list, program)

Start the specified HostStack test program.

Parameters
  • node (dict) – DUT node.

  • namespace (str) – Net Namespace to run program in.

  • core_list (str) – List of cpu’s to pass to taskset to pin the test program to a different set of cores on the same numa node as VPP.

  • program (dict) – Test program.

Returns

Process ID

Return type

int

Raises

RuntimeError – If node subtype is not a DUT or startup failed.

static stop_hoststack_test_program(node, program, pid)

Stop the specified Hoststack test program.

Parameters
  • node (dict) – DUT node.

  • program (dict) – Test program.

  • pid (int) – Process ID of test program.

2.23. IPAddress suite

Common IP utilities library.

class resources.libraries.python.IPAddress.AddressFamily(value)

Bases: enum.IntEnum

IP address family.

ADDRESS_IP4 = 0
ADDRESS_IP6 = 1
class resources.libraries.python.IPAddress.IPAddress

Bases: object

Common IP address utilities

static create_ip_address_object(ip_addr)

Create IP address object.

Parameters

ip_addr (IPv4Address or IPv6Address) – IPv4 or IPv6 address

Returns

IP address object.

Return type

dict

static union_addr(ip_addr)

Creates union IP address.

Parameters

ip_addr (IPv4Address or IPv6Address) – IPv4 or IPv6 address.

Returns

Union IP address.

Return type

dict

2.24. IPUtil suite

Common IP utilities library.

class resources.libraries.python.IPUtil.FibPathFlags(value)

Bases: enum.IntEnum

FIB path flags.

FIB_PATH_FLAG_NONE = 0
FIB_PATH_FLAG_RESOLVE_VIA_ATTACHED = 1
FIB_PATH_FLAG_RESOLVE_VIA_HOST = 2
class resources.libraries.python.IPUtil.FibPathNhProto(value)

Bases: enum.IntEnum

FIB path next-hop protocol.

FIB_PATH_NH_PROTO_BIER = 4
FIB_PATH_NH_PROTO_ETHERNET = 3
FIB_PATH_NH_PROTO_IP4 = 0
FIB_PATH_NH_PROTO_IP6 = 1
FIB_PATH_NH_PROTO_MPLS = 2
class resources.libraries.python.IPUtil.FibPathType(value)

Bases: enum.IntEnum

FIB path types.

FIB_PATH_TYPE_BIER_IMP = 4
FIB_PATH_TYPE_CLASSIFY = 10
FIB_PATH_TYPE_DROP = 2
FIB_PATH_TYPE_DVR = 8
FIB_PATH_TYPE_ICMP_PROHIBIT = 6
FIB_PATH_TYPE_ICMP_UNREACH = 5
FIB_PATH_TYPE_INTERFACE_RX = 9
FIB_PATH_TYPE_LOCAL = 1
FIB_PATH_TYPE_NORMAL = 0
FIB_PATH_TYPE_SOURCE_LOOKUP = 7
FIB_PATH_TYPE_UDP_ENCAP = 3
class resources.libraries.python.IPUtil.IPUtil

Bases: object

Common IP utilities

static add_fib_table(node, table_id, ipv6=False)

Create new FIB table according to ID.

Parameters
  • node (dict) – Node to add FIB on.

  • table_id (int) – FIB table ID.

  • ipv6 (bool) – Is this an IPv6 table

static add_linux_route(node, ip_addr, prefix, gateway, namespace=None)

Add linux route in namespace.

Parameters
  • node (dict) – Node where to execute command.

  • ip_addr (str) – Route destination IP address.

  • prefix (int) – IP prefix.

  • namespace (str) – Execute command in namespace. Optional.

  • gateway (str) – Gateway address.

static compose_vpp_route_structure(node, network, prefix_len, **kwargs)

Create route object for ip_route_add_del api call.

Parameters
  • node (dict) – VPP node.

  • network (str) – Route destination network address.

  • prefix_len (int) – Route destination network prefix length.

  • kwargs (dict) –

    Optional key-value arguments:

    gateway: Route gateway address. (str) interface: Route interface. (str) vrf: VRF table ID. (int) count: number of IP addresses to add starting from network IP (int) local: The route is local with same prefix (increment is 1). If None, then is not used. (bool) lookup_vrf: VRF table ID for lookup. (int) weight: Weight value for unequal cost multipath routing. (int) (Multipath value enters at higher level.)

Returns

route parameter basic structure

Return type

dict

static create_prefix_object(ip_addr, addr_len)

Create prefix object.

Parameters
  • ip_addr (IPv4Address or IPv6Address) – IPv4 or IPv6 address.

  • addr_len (int) – Length of IP address.

Returns

Prefix object.

Return type

dict

static delete_linux_interface_ip(node, interface, ip_addr, prefix_length, namespace=None)

Delete IP address from interface in linux.

Parameters
  • node (dict) – VPP/TG node.

  • interface (str) – Interface in namespace.

  • ip_addr (str) – IP to be deleted from interface.

  • prefix_length (int) – IP prefix length.

  • namespace (str) – Execute command in namespace. Optional

Raises

RuntimeError – IP could not be deleted.

static flush_ip_addresses(node, interface)

Flush all IP addresses from specified interface.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Interface name.

static get_interface_vrf_table(node, interface, ip_version='ipv4')

Get vrf ID for the given interface.

Parameters
  • node (dict) – VPP node.

  • interface (str or int) – Name or sw_if_index of a specific interface.

  • ip_version (str) – IP protocol version (ipv4 or ipv6).

Returns

vrf ID of the specified interface.

Return type

int

static get_linux_interface_name(node, pci_addr)

Get the interface name.

Parameters
  • node (dict) – VPP/TG node.

  • pci_addr (str) – PCI address

Returns

Interface name

Return type

str

Raises

RuntimeError – If cannot get the information about interfaces.

static int_to_ip(ip_int)

Convert IP address from integer representation (e.g. 167772161) to string format (10.0.0.1).

Parameters

ip_int (int) – IP address in integer representation.

Returns

String representation of IP address.

Return type

str

static ip_addresses_should_be_equal(ip1, ip2)

Fails if the given IP addresses are unequal.

Parameters
  • ip1 (str) – IPv4 or IPv6 address.

  • ip2 (str) – IPv4 or IPv6 address.

static ip_to_int(ip_str)

Convert IP address from string format (e.g. 10.0.0.1) to integer representation (167772161).

Parameters

ip_str (str) – IP address in string representation.

Returns

Integer representation of IP address.

Return type

int

static linux_enable_forwarding(node, ip_ver='ipv4')

Enable forwarding on a Linux node, e.g. VM.

Parameters
  • node (dict) – VPP node.

  • ip_ver (str) – IP version, ‘ipv4’ or ‘ipv6’.

static linux_interface_has_ip(node, interface, ip_addr, prefix_length, namespace=None)

Return True if interface in linux has IP address.

Parameters
  • node (dict) – VPP/TG node.

  • interface (str) – Interface in namespace.

  • ip_addr (str) – IP to be queried on interface.

  • prefix_length (int) – IP prefix length.

  • namespace (str) – Execute command in namespace. Optional

Return type

boolean

Raises

RuntimeError – Request fails.

static set_linux_interface_ip(node, interface, ip_addr, prefix, namespace=None)

Set IP address to interface in linux.

Parameters
  • node (dict) – VPP/TG node.

  • interface (str) – Interface in namespace.

  • ip_addr (str) – IP to be set on interface.

  • prefix (int) – IP prefix.

  • namespace (str) – Execute command in namespace. Optional

Raises

RuntimeError – IP could not be set.

static set_linux_interface_up(node, interface, namespace=None)

Set the specified interface up. :param node: VPP/TG node. :param interface: Interface in namespace. :param namespace: Execute command in namespace. Optional :type node: dict :type interface: str :type namespace: str :raises RuntimeError: If the interface could not be set up.

static setup_network_namespace(node, namespace_name, interface_name, ip_addr_list, prefix_length)

Setup namespace on given node and attach interface and IP to this namespace. Applicable also on TG node.

Parameters
  • node (dict) – VPP node.

  • namespace_name (str) – Namespace name.

  • interface_name (str) – Interface name.

  • ip_addr_list (list) – List of IP addresses of namespace’s interface.

  • prefix_length (int) – IP address prefix length.

static vpp_add_ip_neighbor(node, iface_key, ip_addr, mac_address)

Add IP neighbor on DUT node.

Parameters
  • node (dict) – VPP node.

  • iface_key (str) – Interface key.

  • ip_addr (str) – IP address of the interface.

  • mac_address (str) – MAC address of the interface.

static vpp_get_interface_ip_addresses(node, interface, ip_version)

Get list of IP addresses from an interface on a VPP node.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Name of an interface on the VPP node.

  • ip_version (str) – IP protocol version (ipv4 or ipv6).

Returns

List of dictionaries, each containing IP address, subnet prefix length and also the subnet mask for ipv4 addresses. Note: A single interface may have multiple IP addresses assigned.

Return type

list

static vpp_get_ip_table(node)

Get IPv4 FIB table on a VPP node.

Parameters

node (dict) – VPP node.

static vpp_get_ip_table_summary(node)

Get IPv4 FIB table summary on a VPP node.

Parameters

node (dict) – VPP node.

static vpp_get_ip_tables(node)

Get dump of all IP FIB tables on a VPP node.

Parameters

node (dict) – VPP node.

static vpp_get_ip_tables_prefix(node, address)

Get dump of all IP FIB tables on a VPP node.

Parameters
  • node (dict) – VPP node.

  • address (str) – IP address.

static vpp_interface_set_ip_address(node, interface, address, prefix_length=None)

Set IP address to VPP interface.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Interface name.

  • address (str) – IP address.

  • prefix_length (int) – Prefix length.

static vpp_interface_set_ip_addresses(node, interface, ip_addr_list, prefix_length=None)

Set IP addresses to VPP interface.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Interface name.

  • ip_addr_list (list) – IP addresses.

  • prefix_length (int) – Prefix length.

static vpp_ip_probe(node, interface, addr)

Run ip probe on VPP node.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Interface key or name.

  • addr (str) – IPv4/IPv6 address.

static vpp_ip_source_check_setup(node, if_name)

Setup Reverse Path Forwarding source check on interface.

Parameters
  • node (dict) – VPP node.

  • if_name (str) – Interface name to setup RPF source check.

static vpp_route_add(node, network, prefix_len, strict=True, **kwargs)

Add route to the VPP node. Prefer multipath behavior.

Parameters
  • node (dict) – VPP node.

  • network (str) – Route destination network address.

  • prefix_len (int) – Route destination network prefix length.

  • strict (bool) – If true, fail if address has host bits set.

  • kwargs (dict) –

    Optional key-value arguments:

    gateway: Route gateway address. (str) interface: Route interface. (str) vrf: VRF table ID. (int) count: number of IP addresses to add starting from network IP (int) local: The route is local with same prefix (increment is 1 network) If None, then is not used. (bool) lookup_vrf: VRF table ID for lookup. (int) multipath: Enable multipath routing. (bool) Default: True. weight: Weight value for unequal cost multipath routing. (int)

Raises

RuntimeError – If the argument combination is not supported.

class resources.libraries.python.IPUtil.IpDscp(value)

Bases: enum.IntEnum

DSCP code points.

IP_API_DSCP_AF11 = 10
IP_API_DSCP_AF12 = 12
IP_API_DSCP_AF13 = 14
IP_API_DSCP_AF21 = 18
IP_API_DSCP_AF22 = 20
IP_API_DSCP_AF23 = 22
IP_API_DSCP_AF31 = 26
IP_API_DSCP_AF32 = 28
IP_API_DSCP_AF33 = 30
IP_API_DSCP_AF41 = 34
IP_API_DSCP_AF42 = 36
IP_API_DSCP_AF43 = 38
IP_API_DSCP_CS0 = 0
IP_API_DSCP_CS1 = 8
IP_API_DSCP_CS2 = 16
IP_API_DSCP_CS3 = 24
IP_API_DSCP_CS4 = 32
IP_API_DSCP_CS5 = 40
IP_API_DSCP_CS6 = 48
IP_API_DSCP_CS7 = 50
IP_API_DSCP_EF = 46
class resources.libraries.python.IPUtil.NetworkIncrement(initial_value, increment=1, format='dash')

Bases: resources.libraries.python.IncrementUtil.ObjIncrement

An iterator object which accepts an IPv4Network or IPv6Network and returns a new network, its address part incremented by the increment number of network sizes, each time it is iterated or when inc_fmt is called. The increment may be positive, negative or 0 (in which case the network is always the same).

Both initial and subsequent IP address can have host bits set, check the initial value before creating instance if needed. String formatting is configurable via constructor argument.

2.25. IPsecUtil suite

IPsec utilities library.

class resources.libraries.python.IPsecUtil.CryptoAlg(value)

Bases: enum.Enum

Encryption algorithms.

AES_CBC_128 = ('aes-cbc-128', 1, 'AES-CBC', 16)
AES_CBC_256 = ('aes-cbc-256', 3, 'AES-CBC', 32)
AES_GCM_128 = ('aes-gcm-128', 7, 'AES-GCM', 16)
AES_GCM_256 = ('aes-gcm-256', 9, 'AES-GCM', 32)
class resources.libraries.python.IPsecUtil.IPsecProto(value)

Bases: enum.IntEnum

IPsec protocol.

IPSEC_API_PROTO_AH = 51
IPSEC_API_PROTO_ESP = 50
class resources.libraries.python.IPsecUtil.IPsecSadFlags(value)

Bases: enum.IntEnum

IPsec Security Association Database flags.

IPSEC_API_SAD_FLAG_IS_INBOUND = 64
IPSEC_API_SAD_FLAG_IS_TUNNEL = 4
IPSEC_API_SAD_FLAG_IS_TUNNEL_V6 = 8
IPSEC_API_SAD_FLAG_NONE = 0
IPSEC_API_SAD_FLAG_UDP_ENCAP = 16
IPSEC_API_SAD_FLAG_USE_ANTI_REPLAY = 2
IPSEC_API_SAD_FLAG_USE_ESN = 1
class resources.libraries.python.IPsecUtil.IPsecUtil

Bases: object

IPsec utilities.

static crypto_alg_aes_cbc_128()

Return encryption algorithm aes-cbc-128.

Returns

CryptoAlg enum AES_CBC_128 object.

Return type

CryptoAlg

static crypto_alg_aes_cbc_256()

Return encryption algorithm aes-cbc-256.

Returns

CryptoAlg enum AES_CBC_256 object.

Return type

CryptoAlg

static crypto_alg_aes_gcm_128()

Return encryption algorithm aes-gcm-128.

Returns

CryptoAlg enum AES_GCM_128 object.

Return type

CryptoAlg

static crypto_alg_aes_gcm_256()

Return encryption algorithm aes-gcm-256.

Returns

CryptoAlg enum AES_GCM_128 object.

Return type

CryptoAlg

static get_crypto_alg_key_len(crypto_alg)

Return encryption algorithm key length.

Parameters

crypto_alg (CryptoAlg) – Encryption algorithm.

Returns

Key length.

Return type

int

static get_crypto_alg_scapy_name(crypto_alg)

Return encryption algorithm scapy name.

Parameters

crypto_alg (CryptoAlg) – Encryption algorithm.

Returns

Algorithm scapy name.

Return type

str

static get_integ_alg_key_len(integ_alg)

Return integrity algorithm key length.

None argument is accepted, returning zero.

Parameters

integ_alg (Optional[IntegAlg]) – Integrity algorithm.

Returns

Key length.

Return type

int

static get_integ_alg_scapy_name(integ_alg)

Return integrity algorithm scapy name.

Parameters

integ_alg (IntegAlg) – Integrity algorithm.

Returns

Algorithm scapy name.

Return type

str

static integ_alg_sha_256_128()

Return integrity algorithm SHA-256-128.

Returns

IntegAlg enum SHA_256_128 object.

Return type

IntegAlg

static integ_alg_sha_512_256()

Return integrity algorithm SHA-512-256.

Returns

IntegAlg enum SHA_512_256 object.

Return type

IntegAlg

static ipsec_proto_ah()

Return IPSec protocol AH.

Returns

IPsecProto enum AH object.

Return type

IPsecProto

static ipsec_proto_esp()

Return IPSec protocol ESP.

Returns

IPsecProto enum ESP object.

Return type

IPsecProto

static policy_action_bypass()

Return policy action bypass.

Returns

PolicyAction enum BYPASS object.

Return type

PolicyAction

static policy_action_discard()

Return policy action discard.

Returns

PolicyAction enum DISCARD object.

Return type

PolicyAction

static policy_action_protect()

Return policy action protect.

Returns

PolicyAction enum PROTECT object.

Return type

PolicyAction

static show_ipsec_security_association(node)

Show IPSec security association.

Parameters

node (dict) – DUT node.

static vpp_create_ipsec_flows_on_dut(node, n_flows, rx_queues, spi_start, interface)

Create mutiple ipsec flows and enable flows onto interface.

Parameters
  • node (dict) – DUT node.

  • n_flows (int) – Number of flows to create.

  • rx_queues (int) – NUmber of RX queues.

  • spi_start (int) – The start spi.

  • interface (str) – Name of the interface.

Returns

flow_index.

static vpp_ipsec_add_multiple_tunnels(nodes, interface1, interface2, n_tunnels, crypto_alg, integ_alg, tunnel_ip1, tunnel_ip2, raddr_ip1, raddr_ip2, raddr_range, tunnel_addr_incr=True)

Create multiple IPsec tunnels between two VPP nodes.

Parameters
  • nodes (dict) – VPP nodes to create tunnels.

  • interface1 (str or int) – Interface name or sw_if_index on node 1.

  • interface2 (str or int) – Interface name or sw_if_index on node 2.

  • n_tunnels (int) – Number of tunnels to create.

  • crypto_alg (CryptoAlg) – The encryption algorithm name.

  • integ_alg (Optional[IntegAlg]) – The integrity algorithm name.

  • tunnel_ip1 (str) – Tunnel node1 IPv4 address.

  • tunnel_ip2 (str) – Tunnel node2 IPv4 address.

  • raddr_ip1 (string) – Policy selector remote IPv4 start address for the first tunnel in direction node1->node2.

  • raddr_ip2 (string) – Policy selector remote IPv4 start address for the first tunnel in direction node2->node1.

  • raddr_range (int) – Mask specifying range of Policy selector Remote IPv4 addresses. Valid values are from 1 to 32.

  • tunnel_addr_incr (bool) – Enable or disable tunnel IP address incremental step.

static vpp_ipsec_add_sad_entries(node, n_entries, sad_id, spi, crypto_alg, crypto_key, integ_alg=None, integ_key='', tunnel_src=None, tunnel_dst=None, tunnel_addr_incr=True)

Create multiple Security Association Database entries on VPP node.

Parameters
  • node (dict) – VPP node to add SAD entry on.

  • n_entries (int) – Number of SAD entries to be created.

  • sad_id (int) – First SAD entry ID. All subsequent SAD entries will have id incremented by 1.

  • spi (int) – Security Parameter Index of first SAD entry. All subsequent SAD entries will have spi incremented by 1.

  • crypto_alg (CryptoAlg) – The encryption algorithm name.

  • crypto_key (str) – The encryption key string.

  • integ_alg (Optional[IntegAlg]) – The integrity algorithm name.

  • integ_key (str) – The integrity key string.

  • tunnel_src (str) – Tunnel header source IPv4 or IPv6 address. If not specified ESP transport mode is used.

  • tunnel_dst (str) – Tunnel header destination IPv4 or IPv6 address. If not specified ESP transport mode is used.

  • tunnel_addr_incr (bool) – Enable or disable tunnel IP address incremental step.

static vpp_ipsec_add_sad_entry(node, sad_id, spi, crypto_alg, crypto_key, integ_alg=None, integ_key='', tunnel_src=None, tunnel_dst=None)

Create Security Association Database entry on the VPP node.

Parameters
  • node (dict) – VPP node to add SAD entry on.

  • sad_id (int) – SAD entry ID.

  • spi (int) – Security Parameter Index of this SAD entry.

  • crypto_alg (CryptoAlg) – The encryption algorithm name.

  • crypto_key (str) – The encryption key string.

  • integ_alg (Optional[IntegAlg]) – The integrity algorithm name.

  • integ_key (str) – The integrity key string.

  • tunnel_src (str) – Tunnel header source IPv4 or IPv6 address. If not specified ESP transport mode is used.

  • tunnel_dst (str) – Tunnel header destination IPv4 or IPv6 address. If not specified ESP transport mode is used.

static vpp_ipsec_add_spd(node, spd_id)

Create Security Policy Database on the VPP node.

Parameters
  • node (dict) – VPP node to add SPD on.

  • spd_id (int) – SPD ID.

static vpp_ipsec_add_spd_entries(node, n_entries, spd_id, priority, action, inbound, sa_id=None, proto=None, laddr_range=None, raddr_range=None, lport_range=None, rport_range=None, is_ipv6=False)

Create multiple Security Policy Database entries on the VPP node.

Parameters
  • node (dict) – VPP node to add SPD entries on.

  • n_entries (int) – Number of SPD entries to be added.

  • spd_id (int) – SPD ID to add entries on.

  • priority (IPsecUtil.ObjIncrement) – SPD entries priority, higher number = higher priority.

  • action (IPsecUtil.PolicyAction) – Policy action.

  • inbound (bool) – If True policy is for inbound traffic, otherwise outbound.

  • sa_id (IPsecUtil.ObjIncrement) – SAD entry ID for action PolicyAction.PROTECT.

  • proto (int) – Policy selector next layer protocol number.

  • laddr_range (IPsecUtil.NetworkIncrement) – Policy selector local IPv4 or IPv6 address range in format IP/prefix or IP/mask. If no mask is provided, it’s considered to be /32.

  • raddr_range (IPsecUtil.NetworkIncrement) – Policy selector remote IPv4 or IPv6 address range in format IP/prefix or IP/mask. If no mask is provided, it’s considered to be /32.

  • lport_range (string) – Policy selector local TCP/UDP port range in format <port_start>-<port_end>.

  • rport_range (string) – Policy selector remote TCP/UDP port range in format <port_start>-<port_end>.

  • is_ipv6 (bool) – True in case of IPv6 policy when IPv6 address range is not defined so it will default to address ::/0, otherwise False.

static vpp_ipsec_add_spd_entry(node, spd_id, priority, action, inbound=True, sa_id=None, proto=None, laddr_range=None, raddr_range=None, lport_range=None, rport_range=None, is_ipv6=False)

Create Security Policy Database entry on the VPP node.

Parameters
  • node (dict) – VPP node to add SPD entry on.

  • spd_id (int) – SPD ID to add entry on.

  • priority (int) – SPD entry priority, higher number = higher priority.

  • action (IPsecUtil.PolicyAction) – Policy action.

  • inbound (bool) – If True policy is for inbound traffic, otherwise outbound.

  • sa_id (int) – SAD entry ID for action PolicyAction.PROTECT.

  • proto (int) – Policy selector next layer protocol number.

  • laddr_range (string) – Policy selector local IPv4 or IPv6 address range in format IP/prefix or IP/mask. If no mask is provided, it’s considered to be /32.

  • raddr_range (string) – Policy selector remote IPv4 or IPv6 address range in format IP/prefix or IP/mask. If no mask is provided, it’s considered to be /32.

  • lport_range (string) – Policy selector local TCP/UDP port range in format <port_start>-<port_end>.

  • rport_range (string) – Policy selector remote TCP/UDP port range in format <port_start>-<port_end>.

  • is_ipv6 (bool) – True in case of IPv6 policy when IPv6 address range is not defined so it will default to address ::/0, otherwise False.

static vpp_ipsec_create_spds_match_nth_entry(node, dir1_interface, dir2_interface, entry_amount, local_addr_range, remote_addr_range, action=<PolicyAction.BYPASS: ('bypass', 0)>, inbound=False, bidirectional=True)

Create one matching SPD entry for inbound or outbound traffic on a DUT for each traffic direction and also create entry_amount - 1 non-matching SPD entries. Create a Security Policy Database on each outbound interface where these entries will be configured. The matching SPD entry will have the lowest priority, input action and will be configured to match the IP flow. The non-matching entries will be the same, except with higher priority and non-matching IP flows.

Action Protect is currently not supported.

Parameters
  • node (dict) – VPP node to configured the SPDs and their entries.

  • dir1_interface (Union[string, int]) – The interface in direction 1 where the entries will be checked.

  • dir2_interface (Union[string, int]) – The interface in direction 2 where the entries will be checked.

  • entry_amount (int) – The number of SPD entries to configure. If entry_amount == 1, no non-matching entries will be configured.

  • local_addr_range (Union[string, ipaddress.IPv4Address, ipaddress.IPv6Address]) – Matching local address range in direction 1 in format IP/prefix or IP/mask. If no mask is provided, it’s considered to be /32.

  • remote_addr_range (Union[string, ipaddress.IPv4Address, ipaddress.IPv6Address]) – Matching remote address range in direction 1 in format IP/prefix or IP/mask. If no mask is provided, it’s considered to be /32.

  • action (IPsecUtil.PolicyAction) – Policy action.

  • inbound (bool) – If True policy is for inbound traffic, otherwise outbound.

  • bidirectional (bool) – When True, will create SPDs in both directions of traffic. When False, only in one direction.

Raises

NotImplementedError – When the action is PolicyAction.PROTECT.

static vpp_ipsec_create_tunnel_interfaces(nodes, tun_if1_ip_addr, tun_if2_ip_addr, if1_key, if2_key, n_tunnels, crypto_alg, integ_alg, raddr_ip1, raddr_ip2, raddr_range, existing_tunnels=0, return_keys=False)

Create multiple IPsec tunnel interfaces between two VPP nodes.

Some deployments (e.g. devicetest) need to know the generated keys. But other deployments (e.g. scale perf test) would get spammed if we returned keys every time.

Parameters
  • nodes (dict) – VPP nodes to create tunnel interfaces.

  • tun_if1_ip_addr (str) – VPP node 1 ipsec tunnel interface IPv4/IPv6 address.

  • tun_if2_ip_addr (str) – VPP node 2 ipsec tunnel interface IPv4/IPv6 address.

  • if1_key (str) – VPP node 1 interface key from topology file.

  • if2_key (str) – VPP node 2 / TG node (in case of 2-node topology) interface key from topology file.

  • n_tunnels (int) – Number of tunnel interfaces to be there at the end.

  • crypto_alg (CryptoAlg) – The encryption algorithm name.

  • integ_alg (Optonal[IntegAlg]) – The integrity algorithm name.

  • raddr_ip1 (string) – Policy selector remote IPv4/IPv6 start address for the first tunnel in direction node1->node2.

  • raddr_ip2 (string) – Policy selector remote IPv4/IPv6 start address for the first tunnel in direction node2->node1.

  • raddr_range (int) – Mask specifying range of Policy selector Remote IPv4/IPv6 addresses. Valid values are from 1 to 32 in case of IPv4 and to 128 in case of IPv6.

  • existing_tunnels (int) – Number of tunnel interfaces before creation. Useful mainly for reconf tests. Default 0.

  • return_keys (bool) – Whether generated keys should be returned.

Returns

Ckeys, ikeys, spi_1, spi_2.

Return type

Optional[List[bytes], List[bytes], int, int]

static vpp_ipsec_create_tunnel_interfaces_in_containers(nodes, if1_ip_addr, if2_ip_addr, n_tunnels, crypto_alg, integ_alg, raddr_ip1, raddr_ip2, raddr_range, n_instances)

Create multiple IPsec tunnel interfaces between two VPP nodes.

Parameters
  • nodes (dict) – VPP nodes to create tunnel interfaces.

  • if1_ip_addr (str) – VPP node 1 interface IP4 address.

  • if2_ip_addr (str) – VPP node 2 interface IP4 address.

  • n_tunnels (int) – Number of tunnell interfaces to create.

  • crypto_alg (CryptoAlg) – The encryption algorithm name.

  • integ_alg (Optional[IntegAlg]) – The integrity algorithm name.

  • raddr_ip1 (string) – Policy selector remote IPv4 start address for the first tunnel in direction node1->node2.

  • raddr_ip2 (string) – Policy selector remote IPv4 start address for the first tunnel in direction node2->node1.

  • raddr_range (int) – Mask specifying range of Policy selector Remote IPv4 addresses. Valid values are from 1 to 32.

  • n_instances (int) – Number of containers.

static vpp_ipsec_crypto_sw_scheduler_set_worker(node, workers, crypto_enable=False)

Enable or disable crypto on specific vpp worker threads.

Parameters
  • node (dict) – VPP node to enable or disable crypto for worker threads.

  • workers (Iterable[int]) – List of VPP thread numbers.

  • crypto_enable (bool) – Disable or enable crypto work.

Raises

RuntimeError – If failed to enable or disable crypto for worker thread or if no API reply received.

static vpp_ipsec_crypto_sw_scheduler_set_worker_on_all_duts(nodes, workers, crypto_enable=False)

Enable or disable crypto on specific vpp worker threads.

Parameters
  • node (dict) – VPP node to enable or disable crypto for worker threads.

  • workers (Iterable[int]) – List of VPP thread numbers.

  • crypto_enable (bool) – Disable or enable crypto work.

Raises

RuntimeError – If failed to enable or disable crypto for worker thread or if no API reply received.

static vpp_ipsec_flow_enale_rss(node, proto, type, function='default')

Ipsec flow enable rss action.

Parameters
  • node (dict) – DUT node.

  • proto (str) – The flow protocol.

  • type (str) – RSS type.

  • function (str) – RSS function.

Returns

flow_index.

static vpp_ipsec_select_backend(node, protocol, index=1)

Select IPsec backend.

Parameters
  • node (dict) – VPP node to select IPsec backend on.

  • protocol (IPsecProto) – IPsec protocol.

  • index (int) – Backend index.

Raises

RuntimeError – If failed to select IPsec backend or if no API reply received.

static vpp_ipsec_set_async_mode(node, async_enable=1)

Set IPsec async mode on|off.

Parameters
  • node (dict) – VPP node to set IPsec async mode.

  • async_enable (int) – Async mode on or off.

Raises

RuntimeError – If failed to set IPsec async mode or if no API reply received.

static vpp_ipsec_set_ip_route(node, n_tunnels, tunnel_src, traffic_addr, tunnel_dst, interface, raddr_range, dst_mac=None)

Set IP address and route on interface.

Parameters
  • node (dict) – VPP node to add config on.

  • n_tunnels (int) – Number of tunnels to create.

  • tunnel_src (str) – Tunnel header source IPv4 or IPv6 address.

  • traffic_addr (str) – Traffic destination IP address to route.

  • tunnel_dst (str) – Tunnel header destination IPv4 or IPv6 address.

  • interface (str) – Interface key on node 1.

  • raddr_range (int) – Mask specifying range of Policy selector Remote IP addresses. Valid values are from 1 to 32 in case of IPv4 and to 128 in case of IPv6.

  • dst_mac (str) – The MAC address of destination tunnels.

static vpp_ipsec_show_all(node)

Run “show ipsec all” debug CLI command.

Parameters

node (dict) – Node to run command on.

static vpp_ipsec_spd_add_if(node, spd_id, interface)

Add interface to the Security Policy Database.

Parameters
  • node (dict) – VPP node.

  • spd_id (int) – SPD ID to add interface on.

  • interface (str or int) – Interface name or sw_if_index.

class resources.libraries.python.IPsecUtil.IntegAlg(value)

Bases: enum.Enum

Integrity algorithm.

SHA_256_128 = ('sha-256-128', 4, 'SHA2-256-128', 32)
SHA_512_256 = ('sha-512-256', 6, 'SHA2-512-256', 64)
class resources.libraries.python.IPsecUtil.PolicyAction(value)

Bases: enum.Enum

Policy actions.

BYPASS = ('bypass', 0)
DISCARD = ('discard', 1)
PROTECT = ('protect', 3)
class resources.libraries.python.IPsecUtil.TunnelEncpaDecapFlags(value)

Bases: enum.IntEnum

Flags controlling tunnel behaviour.

TUNNEL_API_ENCAP_DECAP_FLAG_ENCAP_COPY_DF = 1
TUNNEL_API_ENCAP_DECAP_FLAG_ENCAP_COPY_DSCP = 4
TUNNEL_API_ENCAP_DECAP_FLAG_ENCAP_COPY_ECN = 8
TUNNEL_API_ENCAP_DECAP_FLAG_ENCAP_SET_DF = 2
TUNNEL_API_ENCAP_DECAP_FLAG_ENCAP_SET_ECN = 16
TUNNEL_API_ENCAP_DECAP_FLAG_NONE = 0
class resources.libraries.python.IPsecUtil.TunnelMode(value)

Bases: enum.IntEnum

Tunnel modes.

TUNNEL_API_MODE_MP = 1
TUNNEL_API_MODE_P2P = 0
resources.libraries.python.IPsecUtil.gen_key(length)

Generate random string as a key.

Parameters

length (int) – Length of generated payload.

Returns

The generated payload.

Return type

bytes

2.26. IPv6Util suite

IPv6 utilities library.

class resources.libraries.python.IPv6Util.IPv6Util

Bases: object

IPv6 utilities

static vpp_interface_ra_suppress(node, interface)

Disable sending ICMPv6 router-advertisement messages on an interface on a VPP node.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Interface name.

static vpp_interfaces_ra_suppress_on_all_nodes(nodes)

Disable sending ICMPv6 router-advertisement messages on all IPv6 enabled interfaces on all VPP nodes in the topology.

Parameters

nodes (dict) – Nodes of the test topology.

static vpp_ra_send_after_interval(node, interface, interval=2)

Setup vpp router advertisement(RA) in such way it sends RA packet after every interval value.

Parameters
  • node (dict) – VPP node.

  • interface (str) – Interface name.

  • interval (int) – Interval in seconds for RA resend.

2.27. IncrementUtil suite

Increment utilities library.

class resources.libraries.python.IncrementUtil.ObjIncrement(initial_value, increment)

Bases: object

An iterator class used to generate incremented values in each iteration or when inc_fmt is called.

Subclasses should override:

_incr: when a simple ‘+’ binary operation isn’t sufficient. _str_fmt: when a simple str representation of the incremented object isn’t the proper format.

inc_fmt()

Return a string representation and increment the current value.

2.28. InterfaceUtil suite

Interface util library.

class resources.libraries.python.InterfaceUtil.AfXdpMode(value)

Bases: enum.IntEnum

AF_XDP interface mode.

AF_XDP_API_MODE_AUTO = 0
AF_XDP_API_MODE_COPY = 1
AF_XDP_API_MODE_ZERO_COPY = 2
class resources.libraries.python.InterfaceUtil.IfType(value)

Bases: enum.IntEnum

Interface type

IF_API_TYPE_HARDWARE = 0
IF_API_TYPE_P2P = 2
IF_API_TYPE_PIPE = 3
IF_API_TYPE_SUB = 1
class resources.libraries.python.InterfaceUtil.InterfaceStatusFlags(value)

Bases: enum.IntEnum

Interface status flags.

IF_STATUS_API_FLAG_ADMIN_UP = 1
class resources.libraries.python.InterfaceUtil.InterfaceUtil

Bases: object

General utilities for managing interfaces

static add_eth_interface(node, ifc_name=None, sw_if_index=None, ifc_pfx=None, host_if_key=None)

Add ethernet interface to current topology.

Parameters
  • node (dict) – DUT node from topology.

  • ifc_name (str) – Name of the interface.

  • sw_if_index (int) – SW interface index.

  • ifc_pfx (str) – Interface key prefix.

  • host_if_key (str) – Host interface key from topology file.

static all_vpp_interfaces_ready_wait(nodes, retries=15)

Wait until all interfaces with admin-up are in link-up state for all nodes in the topology.

Parameters
  • nodes (dict) – Nodes in the topology.

  • retries (int) – Number of retries to check interface status (optional, default 15).

Returns

Nothing.

static assign_interface_to_fib_table(node, interface, table_id, ipv6=False)

Assign VPP interface to specific VRF/FIB table.

Parameters
  • node (dict) – VPP node where the FIB and interface are located.

  • interface (str or int) – Interface to be assigned to FIB.

  • table_id (int) – VRF table ID.

  • ipv6 (bool) – Assign to IPv6 table. Default False.

static create_gre_tunnel_interface(node, source_ip, destination_ip)

Create GRE tunnel interface on node.

Parameters
  • node (dict) – VPP node to add tunnel interface.

  • source_ip (str) – Source of the GRE tunnel.

  • destination_ip (str) – Destination of the GRE tunnel.

Returns

Name and index of created GRE tunnel interface.

Return type

tuple

Raises

RuntimeError – If unable to create GRE tunnel interface.

static create_gtpu_tunnel_interface(node, teid, source_ip, destination_ip)

Create GTPU interface and return sw if index of created interface.

Parameters
  • node (dict) – Node where to create GTPU interface.

  • teid (int) – GTPU Tunnel Endpoint Identifier.

  • source_ip (str) – Source IP of a GTPU Tunnel End Point.

  • destination_ip (str) – Destination IP of a GTPU Tunnel End Point.

Returns

SW IF INDEX of created interface.

Return type

int

Raises

RuntimeError – if it is unable to create GTPU interface on the node.

static create_subinterface(node, interface, sub_id, outer_vlan_id=None, inner_vlan_id=None, type_subif=None)

Create sub-interface on node. It is possible to set required sub-interface type and VLAN tag(s).

Parameters
  • node (dict) – Node to add sub-interface.

  • interface (str or int) – Interface name on which create sub-interface.

  • sub_id (int) – ID of the sub-interface to be created.

  • outer_vlan_id (int) – Optional outer VLAN ID.

  • inner_vlan_id (int) – Optional inner VLAN ID.

  • type_subif (str) – Optional type of sub-interface. Values supported by VPP: [no_tags] [one_tag] [two_tags] [dot1ad] [exact_match] [default_sub]

Returns

Name and index of created sub-interface.

Return type

tuple

Raises

RuntimeError – If it is not possible to create sub-interface.

static create_vlan_subinterface(node, interface, vlan)

Create VLAN sub-interface on node.

Parameters
  • node (dict) – Node to add VLAN subinterface on.

  • interface (str on int) – Interface name or index on which create VLAN subinterface.

  • vlan (int) – VLAN ID of the subinterface to be created.

Returns

Name and index of created subinterface.

Return type

tuple

Raises

RuntimeError – if it is unable to create VLAN subinterface on the node or interface cannot be converted.

static create_vxlan_interface(node, vni, source_ip, destination_ip)

Create VXLAN interface and return sw if index of created interface.

Parameters
  • node (dict) – Node where to create VXLAN interface.

  • vni (int) – VXLAN Network Identifier.

  • source_ip (str) – Source IP of a VXLAN Tunnel End Point.

  • destination_ip (str) – Destination IP of a VXLAN Tunnel End Point.

Returns

SW IF INDEX of created interface.

Return type

int

Raises

RuntimeError – if it is unable to create VxLAN interface on the node.

static get_interface_classify_table(node, interface)

Get name of classify table for the given interface.

TODO: Move to Classify.py.

Parameters
  • node (dict) – VPP node to get data from.

  • interface (str or int) – Name or sw_if_index of a specific interface.

Returns

Classify table name.

Return type

str

static get_interface_index(node, interface)

Get interface sw_if_index from topology file.

Parameters
  • node (dict) – Node where the interface is.

  • interface (str or int) – Numeric index or name string of a specific interface.

Returns

SW interface index.

Return type

int

static get_sw_if_index(node, interface_name)

Get sw_if_index for the given interface from actual interface dump.

FIXME: Delete and redirect callers to vpp_get_interface_sw_index.

Parameters
  • node (dict) – VPP node to get interface data from.

  • interface_name (str) – Name of the specific interface.

Returns

sw_if_index of the given interface.

Return type

str

static iface_update_numa_node(node)
For all interfaces from topology file update numa node based on

information from the node.

Parameters

node (dict) – Node from topology.

Returns

Nothing.

Raises
  • ValueError – If numa node ia less than 0.

  • RuntimeError – If update of numa node failed.

static init_generic_interface(node, ifc_key, numvfs=0, osi_layer='L2')

Init PCI device. Bind to proper drivers. Optionally create NIC VFs.

Parameters
  • node (dict) – DUT node.

  • ifc_key (str) – Interface key from topology file.

  • numvfs (int) – Number of VIFs to initialize, 0 - disable the VIFs.

  • osi_layer (str) – OSI Layer type to initialize TG with. Default value “L2” sets linux interface spoof off.

Returns

Virtual Function topology interface keys.

Return type

list

Raises

RuntimeError – If a reason preventing initialization is found.

static init_interface(node, ifc_key, driver, numvfs=0, osi_layer='L2')

Init PCI device. Check driver compatibility and bind to proper drivers. Optionally create NIC VFs.

Parameters
  • node (dict) – DUT node.

  • ifc_key (str) – Interface key from topology file.

  • driver (str) – Base driver to use.

  • numvfs (int) – Number of VIFs to initialize, 0 - disable the VIFs.

  • osi_layer (str) – OSI Layer type to initialize TG with. Default value “L2” sets linux interface spoof off.

Returns

Virtual Function topology interface keys.

Return type

list

Raises

RuntimeError – If a reason preventing initialization is found.

static pci_to_eth(node, pci_str)

Convert PCI address on DUT to Linux ethernet name.

Parameters
  • node (dict) – DUT node

  • pci_str (str) – PCI address.

Returns

Ethernet name.

Return type

str

static pci_to_int(pci_str)

Convert PCI address from string format (0000:18:0a.0) to integer representation (169345024).

Parameters

pci_str (str) – PCI address in string representation.

Returns

Integer representation of PCI address.

Return type

int

static set_interface_channels(node, pf_pcis, num_queues=1, channel='combined')

Set interface channels for specified interfaces.

Parameters
  • node – Topology node.

  • pf_pcis (list) – List of node’s interfaces PCI addresses.

  • num_queues (int) – Number of channels. (Optional, Default: 1)

  • channel (str) – Channel type. (Optional, Default: combined)

static set_interface_flow_control(node, pf_pcis, rxf='off', txf='off')

Set Ethernet flow control for specified interfaces.

Parameters
  • node – Topology node.

  • pf_pcis (list) – List of node’s interfaces PCI addresses.

  • rxf (str) – RX flow. (Optional, Default: off).

  • txf (str) – TX flow. (Optional, Default: off).

static set_interface_mtu(node, pf_pcis, mtu=9200)

Set Ethernet MTU for specified interfaces.

Parameters
  • node – Topology node.

  • pf_pcis (list) – List of node’s interfaces PCI addresses.

  • mtu (int) – MTU to set. Default: 9200.

Raises

RuntimeError – If failed to set MTU on interface.

static set_interface_state(node, interface, state, if_type='key')

Set interface state on a node.

Function can be used for DUTs as well as for TGs.

Parameters
  • node (dict) – Node where the interface is.

  • interface (str or int) – Interface key or sw_if_index or name.

  • state (str) – One of ‘up’ or ‘down’.

  • if_type (str) – Interface type

Returns

Nothing.

Raises
  • ValueError – If the interface type is unknown.

  • ValueError – If the state of interface is unexpected.

  • ValueError – If the node has an unknown node type.

static set_interface_state_pci(node, pf_pcis, namespace=None, state='up')

Set operational state for interface specified by PCI address.

Parameters
  • node – Topology node.

  • pf_pcis (list) – List of node’s interfaces PCI addresses.

  • namespace (str) – Exec command in namespace. (Optional, Default: none)

  • state (str) – Up/Down. (Optional, default: up)

static set_linux_interface_mac(node, interface, mac, namespace=None, vf_id=None)

Set MAC address for interface in linux.

Parameters
  • node (dict) – Node where to execute command.

  • interface (str) – Interface in namespace.

  • mac (str) – MAC to be assigned to interface.

  • namespace (str) – Execute command in namespace. Optional

  • vf_id (int) – Virtual Function id. Optional

static set_linux_interface_promisc(node, interface, namespace=None, vf_id=None, state='on')

Set promisc state for interface in linux.

Parameters
  • node (dict) – Node where to execute command.

  • interface (str) – Interface in namespace.

  • namespace (str) – Exec command in namespace. (Optional, Default: None)

  • vf_id (int) – Virtual Function id. (Optional, Default: None)

  • state (str) – State of feature. (Optional, Default: on)

static set_linux_interface_spoof_off(node, interface, namespace=None, vf_id=None)

Set spoof off for interface in linux.

Parameters
  • node (dict) – Node where to execute command.

  • interface (str) – Interface in namespace.

  • namespace (str) – Execute command in namespace. Optional

  • vf_id (int) – Virtual Function id. Optional

static set_linux_interface_state(node, interface, namespace=None, state='up')

Set operational state for interface in linux.

Parameters
  • node (dict) – Node where to execute command.

  • interface (str) – Interface in namespace.

  • namespace (str) – Execute command in namespace. Optional

  • state (str) – Up/Down.

static set_linux_interface_trust_on(node, interface, namespace=None, vf_id=None)

Set trust on (promisc) for interface in linux.

Parameters
  • node (dict) – Node where to execute command.

  • interface (str) – Interface in namespace.

  • namespace (str) – Execute command in namespace. Optional

  • vf_id (int) – Virtual Function id. Optional

static set_pci_parameter(node, pf_pcis, key, value)

Set PCI parameter for specified interfaces.

Parameters
  • node – Topology node.

  • pf_pcis (list) – List of node’s interfaces PCI addresses.

  • key (str) – Key to set.

  • value (str) – Value to set.

static set_vxlan_bypass(node, interface=None)

Add the ‘ip4-vxlan-bypass’ graph node for a given interface.

By adding the IPv4 vxlan-bypass graph node to an interface, the node checks for and validate input vxlan packet and bypass ip4-lookup, ip4-local, ip4-udp-lookup nodes to speedup vxlan packet forwarding. This node will cause extra overhead to for non-vxlan packets which is kept at a minimum.

Parameters
  • node (dict) – Node where to set VXLAN bypass.

  • interface (int or str) – Numeric index or name string of a specific interface.

Raises

RuntimeError – if it failed to set VXLAN bypass on interface.

static tg_get_interface_driver(node, pci_addr)

Get interface driver from the TG node.

Parameters
  • node (dict) – Node to get interface driver on (must be TG node).

  • pci_addr (str) – PCI address of the interface.

Returns

Interface driver or None if not found.

Return type

str

Raises

RuntimeError – If PCI rescan or lspci command execution failed.

static tg_set_interface_driver(node, pci_addr, driver)

Set interface driver on the TG node.

Parameters
  • node (dict) – Node to set interface driver on (must be TG node).

  • pci_addr (str) – PCI address of the interface.

  • driver (str) – Driver name.

Raises
  • RuntimeError – If unbinding from the current driver fails.

  • RuntimeError – If binding to the new driver fails.

static tg_set_interfaces_default_driver(node)

Set interfaces default driver specified in topology yaml file.

Parameters

node (dict) – Node to setup interfaces driver on (must be TG node).

static update_all_interface_data_on_all_nodes(nodes, skip_tg=False, skip_vpp=False)

Update interface names on all nodes in DICT__nodes.

This method updates the topology dictionary by querying interface lists of all nodes mentioned in the topology dictionary.

Parameters
  • nodes (dict) – Nodes in the topology.

  • skip_tg (bool) – Skip TG node.

  • skip_vpp (bool) – Skip VPP node.

static update_nic_interface_names(node)

Update interface names based on nic type and PCI address.

This method updates interface names in the same format as VPP does.

Parameters

node (dict) – Node dictionary.

static update_nic_interface_names_on_all_duts(nodes)

Update interface names based on nic type and PCI address on all DUTs.

This method updates interface names in the same format as VPP does.

Parameters

nodes (dict) – Topology nodes.

static update_tg_interface_data_on_node(node)

Update interface name for TG/linux node in DICT__nodes.

Note

# for dev in ls /sys/class/net/; > do echo “”cat /sys/class/net/$dev/address”: “$dev””; done “52:54:00:9f:82:63”: “eth0” “52:54:00:77:ae:a9”: “eth1” “52:54:00:e1:8a:0f”: “eth2” “00:00:00:00:00:00”: “lo”

Parameters

node (dict) – Node selected from DICT__nodes.

Raises

RuntimeError – If getting of interface name and MAC fails.

static update_vpp_interface_data_on_node(node)

Update vpp generated interface data for a given node in DICT__nodes.

Updates interface names, software if index numbers and any other details generated specifically by vpp that are unknown before testcase run. It does this by dumping interface list from all devices using python api, and pairing known information from topology (mac address) to state from VPP.

Parameters

node (dict) – Node selected from DICT__nodes.

static vpp_add_bond_member(node, interface, bond_if)

Add member interface to bond interface on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • interface (str) – Physical interface key from topology file.

  • bond_if (str) – Load balance

Raises

RuntimeError – If it is not possible to add member to bond interface on the node.

static vpp_bond_member_dump(node, interface)

Get bond interface slave(s) data on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • interface (str) – Physical interface key from topology file.

Returns

Bond slave interface data.

Return type

dict

static vpp_create_af_xdp_interface(node, if_key, num_rx_queues=None, rxq_size=0, txq_size=0, mode='auto')

Create AF_XDP interface on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • if_key (str) – Physical interface key from topology file of interface to be bound to compatible driver.

  • num_rx_queues (int) – Number of RX queues. (Optional, Default: none)

  • rxq_size (int) – Size of RXQ (0 = Default API; 512 = Default VPP).

  • txq_size (int) – Size of TXQ (0 = Default API; 512 = Default VPP).

  • mode (str) – AF_XDP interface mode. (Optional, Default: auto).

Returns

Interface key (name) in topology file.

Return type

str

Raises

RuntimeError – If it is not possible to create AF_XDP interface on the node.

static vpp_create_avf_interface(node, if_key, num_rx_queues=None, rxq_size=0, txq_size=0)

Create AVF interface on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • if_key (str) – Interface key from topology file of interface to be bound to i40evf driver.

  • num_rx_queues (int) – Number of RX queues.

  • rxq_size (int) – Size of RXQ (0 = Default API; 512 = Default VPP).

  • txq_size (int) – Size of TXQ (0 = Default API; 512 = Default VPP).

Returns

AVF interface key (name) in topology.

Return type

str

Raises

RuntimeError – If it is not possible to create AVF interface on the node.

static vpp_create_bond_interface(node, mode, load_balance=None, mac=None, gso=False)

Create bond interface on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • mode (str) – Link bonding mode.

  • load_balance (str) – Load balance (optional, valid for xor and lacp modes, otherwise ignored). Default: None.

  • mac (str) – MAC address to assign to the bond interface (optional). Default: None.

  • gso (bool) – Enable GSO support (optional). Default: False.

Returns

Interface key (name) in topology.

Return type

str

Raises

RuntimeError – If it is not possible to create bond interface on the node.

static vpp_create_loopback(node, mac=None)

Create loopback interface on VPP node.

Parameters
  • node (dict) – Node to create loopback interface on.

  • mac (str) – Optional MAC address for loopback interface.

Returns

SW interface index.

Return type

int

Raises

RuntimeError – If it is not possible to create loopback on the node.

static vpp_create_rdma_interface(node, if_key, num_rx_queues=None, rxq_size=0, txq_size=0, mode='auto')

Create RDMA interface on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • if_key (str) – Physical interface key from topology file of interface to be bound to rdma-core driver.

  • num_rx_queues (int) – Number of RX queues.

  • rxq_size (int) – Size of RXQ (0 = Default API; 512 = Default VPP).

  • txq_size (int) – Size of TXQ (0 = Default API; 512 = Default VPP).

  • mode (str) – RDMA interface mode - auto/ibv/dv.

Returns

Interface key (name) in topology file.

Return type

str

Raises

RuntimeError – If it is not possible to create RDMA interface on the node.

static vpp_enable_gtpu_offload_rx(node, interface, gtpu_if_index)

Enable GTPU offload RX onto interface.

Parameters
  • node (dict) – Node to run command on.

  • interface (str) – Name of the specific interface.

  • gtpu_if_index – Index of GTPU tunnel interface.

static vpp_enable_input_acl_interface(node, interface, ip_version, table_index)

Enable input acl on interface.

Parameters
  • node (dict) – VPP node to setup interface for input acl.

  • interface (str or int) – Interface to setup input acl.

  • ip_version (str) – Version of IP protocol.

  • table_index (int) – Classify table index.

static vpp_get_interface_data(node, interface=None)

Get all interface data from a VPP node. If a name or sw_interface_index is provided, return only data for the matching interface(s).

Parameters
  • node (dict) – VPP node to get interface data from.

  • interface (int or str) – Numeric index or name string of a specific interface.

Returns

List of dictionaries containing data for each interface, or a single dictionary for the specified interface.

Return type

list or dict

Raises

TypeError – if the data type of interface is neither basestring nor int.

static vpp_get_interface_mac(node, interface)

Get MAC address for the given interface from actual interface dump.

Parameters
  • node (dict) – VPP node to get interface data from.

  • interface (int or str) – Numeric index or name string of a specific interface.

Returns

MAC address.

Return type

str

static vpp_get_interface_name(node, sw_if_index)

Get interface name for the given SW interface index from actual interface dump.

Parameters
  • node (dict) – VPP node to get interface data from.

  • sw_if_index (int) – SW interface index of the specific interface.

Returns

Name of the given interface.

Return type

str

static vpp_get_interface_sw_index(node, interface_name)

Get interface name for the given SW interface index from actual interface dump.

Parameters
  • node (dict) – VPP node to get interface data from.

  • interface_name (str) – Interface name.

Returns

Name of the given interface.

Return type

str

static vpp_node_interfaces_ready_wait(node, retries=15)

Wait until all interfaces with admin-up are in link-up state.

Parameters
  • node (dict) – Node to wait on.

  • retries (int) – Number of retries to check interface status (optional, default 15).

Returns

Nothing.

Raises

RuntimeError – If any interface is not in link-up state after defined number of retries.

static vpp_round_robin_rx_placement(node, prefix, workers=None)

Set Round Robin interface RX placement on all worker threads on node.

If specified, workers limits the number of physical cores used for data plane I/O work. Other cores are presumed to do something else, e.g. asynchronous crypto processing. None means all workers are used for data plane work.

Parameters
  • node (dict) – Topology nodes.

  • prefix (str) – Interface name prefix.

  • workers (str) – Comma separated worker index numbers intended for dataplane work.

static vpp_round_robin_rx_placement_on_all_duts(nodes, prefix, workers=None)

Set Round Robin interface RX placement on worker threads on all DUTs.

If specified, workers limits the number of physical cores used for data plane I/O work. Other cores are presumed to do something else, e.g. asynchronous crypto processing. None means all cores are used for data plane work.

Parameters
  • nodes (dict) – Topology nodes.

  • prefix (str) – Interface name prefix.

  • workers (str) – Comma separated worker index numbers intended for dataplane work.

static vpp_set_interface_mac(node, interface, mac)

Set MAC address for the given interface.

Parameters
  • node (dict) – VPP node to set interface MAC.

  • interface (int or str) – Numeric index or name string of a specific interface.

  • mac (str) – Required MAC address.

static vpp_set_interface_mtu(node, interface, mtu=9200)

Set Ethernet MTU on interface.

Parameters
  • node (dict) – VPP node.

  • interface (str or int) – Interface to setup MTU. Default: 9200.

  • mtu (int) – Ethernet MTU size in Bytes.

static vpp_show_bond_data_on_all_nodes(nodes, verbose=False)

Show (detailed) bond information on all VPP nodes in DICT__nodes.

Parameters
  • nodes (dict) – Nodes in the topology.

  • verbose (bool) – If detailed information is required or not.

static vpp_show_bond_data_on_node(node, verbose=False)

Show (detailed) bond information on VPP node.

Parameters
  • node (dict) – DUT node from topology.

  • verbose (bool) – If detailed information is required or not.

static vpp_sw_interface_rx_placement_dump(node)

Dump VPP interface RX placement on node.

Parameters

node (dict) – Node to run command on.

Returns

Thread mapping information as a list of dictionaries.

Return type

list

static vpp_sw_interface_rx_placement_dump_on_all_duts(nodes)

Dump VPP interface RX placement on all given nodes.

Parameters

nodes (dict) – Nodes to run command on.

Returns

Thread mapping information as a list of dictionaries.

Return type

list

static vpp_sw_interface_set_rx_placement(node, sw_if_index, queue_id, worker_id)

Set interface RX placement to worker on node.

Parameters
  • node (dict) – Node to run command on.

  • sw_if_index (int) – VPP SW interface index.

  • queue_id (int) – VPP interface queue ID.

  • worker_id (int) – VPP worker ID (indexing from 0).

Raises

RuntimeError – If failed to run command on host or if no API reply received.

static vxlan_dump(node, interface=None)

Get VxLAN data for the given interface.

Parameters
  • node (dict) – VPP node to get interface data from.

  • interface (int or str) – Numeric index or name string of a specific interface. If None, information about all VxLAN interfaces is returned.

Returns

Dictionary containing data for the given VxLAN interface or if interface=None, the list of dictionaries with all VxLAN interfaces.

Return type

dict or list

Raises

TypeError – if the data type of interface is neither basestring nor int.

static vxlan_gpe_dump(node, interface_name=None)

Get VxLAN GPE data for the given interface.

Parameters
  • node (dict) – VPP node to get interface data from.

  • interface_name (str) – Name of the specific interface. If None, information about all VxLAN GPE interfaces is returned.

Returns

Dictionary containing data for the given VxLAN GPE interface or if interface=None, the list of dictionaries with all VxLAN GPE interfaces.

Return type

dict or list

class resources.libraries.python.InterfaceUtil.LinkBondLoadBalanceAlgo(value)

Bases: enum.IntEnum

Link bonding load balance algorithm.

BOND_API_LB_ALGO_AB = 5
BOND_API_LB_ALGO_BC = 4
BOND_API_LB_ALGO_L2 = 0
BOND_API_LB_ALGO_L23 = 2
BOND_API_LB_ALGO_L34 = 1
BOND_API_LB_ALGO_RR = 3
class resources.libraries.python.InterfaceUtil.LinkBondMode(value)

Bases: enum.IntEnum

Link bonding mode.

BOND_API_MODE_ACTIVE_BACKUP = 2
BOND_API_MODE_BROADCAST = 4
BOND_API_MODE_LACP = 5
BOND_API_MODE_ROUND_ROBIN = 1
BOND_API_MODE_XOR = 3
class resources.libraries.python.InterfaceUtil.LinkDuplex(value)

Bases: enum.IntEnum

Link duplex

class resources.libraries.python.InterfaceUtil.MtuProto(value)

Bases: enum.IntEnum

MTU protocol.

MTU_PROTO_API_IP4 = 1
MTU_PROTO_API_IP6 = 2
MTU_PROTO_API_L3 = 0
MTU_PROTO_API_MPLS = 3
MTU_PROTO_API_N = 4
class resources.libraries.python.InterfaceUtil.RdmaMode(value)

Bases: enum.IntEnum

RDMA interface mode.

RDMA_API_MODE_AUTO = 0
RDMA_API_MODE_DV = 2
RDMA_API_MODE_IBV = 1
class resources.libraries.python.InterfaceUtil.RxMode(value)

Bases: enum.IntEnum

RX mode

RX_MODE_API_ADAPTIVE = 3
RX_MODE_API_DEFAULT = 4
RX_MODE_API_INTERRUPT = 2
RX_MODE_API_POLLING = 1
RX_MODE_API_UNKNOWN = 0
class resources.libraries.python.InterfaceUtil.SubInterfaceFlags(value)

Bases: enum.IntEnum

Sub-interface flags.

SUB_IF_API_FLAG_DEFAULT = 32
SUB_IF_API_FLAG_DOT1AD = 8
SUB_IF_API_FLAG_DOT1AH = 256
SUB_IF_API_FLAG_EXACT_MATCH = 16
SUB_IF_API_FLAG_INNER_VLAN_ID_ANY = 128
SUB_IF_API_FLAG_NO_TAGS = 1
SUB_IF_API_FLAG_ONE_TAG = 2
SUB_IF_API_FLAG_OUTER_VLAN_ID_ANY = 64
SUB_IF_API_FLAG_TWO_TAGS = 4

2.29. Iperf3 suite

iPerf3 utilities library.

class resources.libraries.python.Iperf3.IPerf3Client

Bases: object

iPerf3 client utilities.

static iperf3_cmdline(**kwargs)

Get iperf_client driver command line.

Parameters

kwargs (dict) – List of iperf_client driver parameters.

Returns

iperf_client driver command line.

Return type

OptionString

class resources.libraries.python.Iperf3.IPerf3Server

Bases: object

iPerf3 server utilities.

static iperf3_cmdline(**kwargs)

Get iPerf3 server command line.

Parameters

kwargs (dict) – List of iPerf3 server parameters.

Returns

iPerf3 server command line.

Return type

OptionString

class resources.libraries.python.Iperf3.Iperf3

Bases: object

iPerf3 traffic generator utilities.

static get_iperf_type(node)

Log and return the installed traffic generator type.

Parameters

node (dict) – Node from topology file.

Returns

Traffic generator type string.

Return type

str

static get_iperf_version(node)

Log and return the installed traffic generator version.

Parameters

node (dict) – Node from topology file.

Returns

Traffic generator version string.

Return type

str

initialize_iperf_server(node, pf_key, interface, bind, bind_gw, bind_mask, namespace=None, cpu_skip_cnt=0, cpu_cnt=1, instances=1)

iPerf3 initialization.

Parameters
  • node (dict) – Topology node running iPerf3 server.

  • pf_key (str) – First TG’s interface (To compute numa location).

  • interface (str) – Name of TG bind interface.

  • bind (str) – Bind to host, one of node’s addresses.

  • bind_gw (str) – Bind gateway (required for default route).

  • bind_mask (str) – Bind address mask.

  • namespace (str) – Name of TG namespace to execute.

  • cpu_skip_cnt (int) – Amount of CPU cores to skip.

  • cpu_cnt (int) – iPerf3 main thread count.

  • instances (int) – Number of simultaneous iPerf3 instances.

iperf_client_start_remote_exec(node, duration, rate, frame_size, async_call=False, warmup_time=0, traffic_directions=1, namespace=None, udp=False, host=None, bind=None, affinity=None)

Execute iPerf3 client script on remote node over ssh to start running traffic.

Parameters
  • node (dict) – Topology node running iPerf3.

  • duration (float) – Time expressed in seconds for how long to send traffic.

  • rate (str) – Traffic rate.

  • frame_size (str) – L2 frame size to send (without padding and IPG).

  • async_call (bool) – If enabled then don’t wait for all incoming traffic.

  • warmup_time (float) – Warmup time period.

  • traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 1

  • namespace (str) – Namespace to execute iPerf3 client on.

  • udp (bool) – UDP traffic.

  • host (str) – Client connecting to an iPerf server running on host.

  • bind (str) – Client bind IP address.

  • affinity (str) – iPerf3 client affinity.

Returns

List of iPerf3 PIDs.

Return type

list

static iperf_client_stop_remote_exec(node, pids)

Stop iPerf3 client execution.

Parameters

pids (str or list) – PID or List of PIDs of iPerf3 client.

static is_iperf_running(node)

Check if iPerf3 is running using pgrep.

Parameters

node (dict) – Topology node running iPerf3.

Returns

True if iPerf3 is running otherwise False.

Return type

bool

static start_iperf_server(node, namespace=None, port=5201, affinity=None)

Start iPerf3 server instance as a deamon.

Parameters
  • node (dict) – Topology node running iPerf3 server.

  • namespace (str) – Name of TG namespace to execute.

  • port (int) – The server port for the server to listen on.

  • affinity (str) – iPerf3 server affinity.

static teardown_iperf(node)

iPerf3 teardown.

Parameters

node (dict) – Topology node running iPerf3.

2.30. IrqUtil suite

IRQ handling library.

class resources.libraries.python.IrqUtil.IrqUtil

Bases: object

Contains methods for managing IRQs.

static get_interface_irqs(node, interface)

Get IRQs for interface in linux.

Parameters
  • node (dict) – Topology node.

  • interface (str) – Linux interface name.

Returns

List of IRQs attached to specified interface.

Return type

list

static get_pci_interface_irqs(node, pci_addr)

Get IRQs for interface in linux specified by PCI address.

Parameters
  • node (dict) – Topology node.

  • pci_addr (str) – Linux interface PCI address.

Returns

List of IRQs attached to specified interface.

Return type

list

static set_interface_irqs_affinity(node, interface, cpu_skip_cnt=0, cpu_cnt=1)

Set IRQs affinity for interface in linux.

Parameters
  • node (dict) – Topology node.

  • interface (str) – Topology interface.

  • cpu_skip_cnt (int) – Amount of CPU cores to skip.

  • cpu_cnt (int) – CPU threads count. (Optional, Default: 0)

  • cpu_list – List of CPUs. (Optional, Default: 1)

2.31. KubernetesUtils suite

Library to control Kubernetes kubectl.

class resources.libraries.python.KubernetesUtils.KubernetesUtils

Bases: object

Kubernetes utilities class.

static apply_kubernetes_resource_on_all_duts(nodes, yaml_file, **kwargs)

Apply Kubernetes resource on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • yaml_file (str) – YAML configuration file.

  • kwargs (dict) – Key-value pairs to replace in YAML template.

static apply_kubernetes_resource_on_node(node, yaml_file, **kwargs)

Apply Kubernetes resource on node.

Parameters
  • node (dict) – DUT node.

  • yaml_file (str) – YAML configuration file.

  • kwargs (dict) – Key-value pairs to replace in YAML template.

Raises

RuntimeError – If applying Kubernetes template failed.

static create_kubernetes_cm_from_file_on_all_duts(nodes, nspace, name, **kwargs)

Create Kubernetes ConfigMap from file on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • nspace (str) – Kubernetes namespace.

  • name (str) – ConfigMap name.

  • kwargs – Named parameters.

  • kwargs – dict

static create_kubernetes_cm_from_file_on_node(node, nspace, name, **kwargs)

Create Kubernetes ConfigMap from file on node.

Parameters
  • node (dict) – DUT node.

  • nspace (str) – Kubernetes namespace.

  • name (str) – ConfigMap name.

  • kwargs – Named parameters.

  • kwargs – dict

Raises

RuntimeError – If creating Kubernetes ConfigMap failed.

static create_kubernetes_vnf_startup_config(**kwargs)

Create Kubernetes VNF startup configuration.

Parameters
  • kwargs – Key-value pairs used to create configuration.

  • kwargs – dict

static create_kubernetes_vswitch_startup_config(**kwargs)

Create Kubernetes VSWITCH startup configuration.

Parameters
  • kwargs – Key-value pairs used to create configuration.

  • kwargs – dict

static delete_kubernetes_resource_on_all_duts(nodes, nspace, name=None, rtype='po,cm,deploy,rs,rc,svc')

Delete all Kubernetes resource on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • nspace (str) – Kubernetes namespace.

  • rtype (str) – Kubernetes resource type.

  • name (str) – Name of resource.

static delete_kubernetes_resource_on_node(node, nspace, name=None, rtype='po,cm,deploy,rs,rc,svc')

Delete Kubernetes resource on node.

Parameters
  • node (dict) – DUT node.

  • nspace (str) – Kubernetes namespace.

  • rtype (str) – Kubernetes resource type.

  • name (str) – Name of resource (Default: all).

Raises

RuntimeError – If retrieving or deleting Kubernetes resource failed.

static describe_kubernetes_resource_on_all_duts(nodes, nspace)

Describe all Kubernetes PODs in namespace on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • nspace (str) – Kubernetes namespace.

static describe_kubernetes_resource_on_node(node, nspace)

Describe all Kubernetes PODs in namespace on node.

Parameters
  • node (dict) – DUT node.

  • nspace (str) – Kubernetes namespace.

static destroy_kubernetes_on_all_duts(nodes)

Destroy Kubernetes on all DUTs.

Parameters

nodes (dict) – Topology nodes.

static destroy_kubernetes_on_node(node)

Destroy Kubernetes on node.

Parameters

node (dict) – DUT node.

Raises

RuntimeError – If destroying Kubernetes failed.

static get_kubernetes_logs_on_all_duts(nodes, nspace)

Get Kubernetes logs from all PODs in namespace on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • nspace (str) – Kubernetes namespace.

static get_kubernetes_logs_on_node(node, nspace)

Get Kubernetes logs from all PODs in namespace on node.

Parameters
  • node (dict) – DUT node.

  • nspace (str) – Kubernetes namespace.

static load_docker_image_on_all_duts(nodes, image_path)

Load Docker container image from file on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • image_path (str) – Container image path.

static load_docker_image_on_node(node, image_path)

Load Docker container image from file on node.

Parameters
  • node (dict) – DUT node.

  • image_path (str) – Container image path.

Raises

RuntimeError – If loading image failed on node.

static set_kubernetes_pods_affinity_on_all_duts(nodes)

Set affinity for all Kubernetes PODs except VPP on all DUTs.

Parameters

nodes (dict) – Topology nodes.

static set_kubernetes_pods_affinity_on_node(node)

Set affinity for all Kubernetes PODs except VPP on node.

Parameters

node (dict) – DUT node.

static setup_kubernetes_on_all_duts(nodes)

Set up Kubernetes on all DUTs.

Parameters

nodes (dict) – Topology nodes.

static setup_kubernetes_on_node(node)

Set up Kubernetes on node.

Parameters

node (dict) – DUT node.

Raises

RuntimeError – If Kubernetes setup failed on node.

static wait_for_kubernetes_pods_on_all_duts(nodes, nspace)

Wait for Kubernetes to become ready on all DUTs.

Parameters
  • nodes (dict) – Topology nodes.

  • nspace (str) – Kubernetes namespace.

static wait_for_kubernetes_pods_on_node(node, nspace)

Wait for Kubernetes PODs to become ready on node.

Parameters
  • node (dict) – DUT node.

  • nspace (str) – Kubernetes namespace.

Raises

RuntimeError – If Kubernetes PODs are not in Running state.

2.32. L2Util suite

L2 Utilities Library.

class resources.libraries.python.L2Util.L2Util

Bases: object

Utilities for l2 configuration.

static add_interface_to_l2_bd(node, interface, bd_id, shg=0, port_type=0)

Add an interface to the L2 bridge domain.

Get SW IF ID and add it to the bridge domain.

Parameters
  • node (dict) – Node where we want to execute the command that does this.

  • interface (str) – Interface name.

  • bd_id (int or str) – Bridge domain index.

  • shg (int or str) – Split-horizon group index. (Default value = 0)

  • port_type (int or str) – Port mode: 0 - normal, 1 - BVI, 2 - UU_FWD. (Default value = 0)

static bin_to_mac(mac_bin)

Convert MAC address from binary representation () to string format (e.g. 01:02:03:04:05:06).

Parameters

mac_bin (bytes) – MAC address in binary representation.

Returns

String representation of MAC address.

Return type

str

static create_l2_bd(node, bd_id, flood=True, uu_flood=True, forward=True, learn=True, arp_term=False)

Create an L2 bridge domain on a VPP node.

Parameters
  • node (dict) – Node where we wish to crate the L2 bridge domain.

  • bd_id (int or str) – Bridge domain index.

  • flood (bool) – Enable/disable bcast/mcast flooding in the BD. (Default value = 1)

  • uu_flood (bool) – Enable/disable unknown unicast flood in the BD. (Default value = 1)

  • forward (bool) – Enable/disable forwarding on all interfaces in the BD. (Default value = 1)

  • learn (bool) – Enable/disable MAC learning on all interfaces in the BD. (Default value = 1)

  • arp_term (bool) – Enable/disable arp termination in the BD. (Default value = 1)

static get_l2_fib_entry_by_mac(node, bd_index, mac)

Retrieves the L2 FIB entry specified by MAC address using PAPI.

Parameters
  • node (dict) – VPP node.

  • bd_index (int) – Index of the bridge domain.

  • mac (str) – MAC address used as the key in L2 FIB data structure.

Returns

L2 FIB entry

Return type

dict

static get_l2_fib_table(node, bd_id)

Retrieves the L2 FIB table.

Parameters
  • node (dict) – VPP node.

  • bd_id (int) – Index of the bridge domain.

Returns

L2 FIB table.

Return type

list

static int_to_mac(mac_int)

Convert MAC address from integer representation (e.g. 1108152157446) to string format (01:02:03:04:05:06).

Parameters

mac_int (int) – MAC address in integer representation.

Returns

String representation of MAC address.

Return type

str

static l2_vlan_tag_rewrite(node, interface, tag_rewrite_method, push_dot1q=True, tag1_id=None, tag2_id=None)

Rewrite tags in ethernet frame.

Parameters
  • node (dict) – Node to rewrite tags.

  • interface (str or int) – Interface on which rewrite tags.

  • tag_rewrite_method (str) – Method of tag rewrite.

  • push_dot1q (bool) – Optional parameter to disable to push dot1q tag instead of dot1ad.

  • tag1_id (int) – Optional tag1 ID for VLAN.

  • tag2_id (int) – Optional tag2 ID for VLAN.

static linux_add_bridge(node, br_name, if_1, if_2, set_up=True)

Bridge two interfaces on linux node.

Parameters
  • node (dict) – Node to add bridge on.

  • br_name (str) – Bridge name.

  • if_1 (str) – First interface to be added to the bridge.

  • if_2 (str) – Second interface to be added to the bridge.

  • set_up (bool) – Change bridge interface state to up after create bridge. Optional. Default: True.

static linux_del_bridge(node, br_name, set_down=True)

Delete bridge from linux node.

..note:: The network interface corresponding to the bridge must be

down before it can be deleted!

Parameters
  • node (dict) – Node to delete bridge from.

  • br_name (str) – Bridge name.

  • set_down (bool) – Change bridge interface state to down before delbr command. Optional. Default: True.

static mac_to_bin(mac_str)

Convert MAC address from string format (e.g. 01:02:03:04:05:06) to binary representation ().

Parameters

mac_str (str) – MAC address in string representation.

Returns

Binary representation of MAC address.

Return type

bytes

static mac_to_int(mac_str)

Convert MAC address from string format (e.g. 01:02:03:04:05:06) to integer representation (1108152157446).

Parameters

mac_str (str) – MAC address in string representation.

Returns

Integer representation of MAC address.

Return type

int

static vpp_add_l2_bridge_domain(node, bd_id, port_1, port_2, learn=True)

Add L2 bridge domain with 2 interfaces to the VPP node.

Parameters
  • node (dict) – Node to add L2BD on.

  • bd_id (int) – Bridge domain ID.

  • port_1 (str) – First interface name added to L2BD.

  • port_2 (str) – Second interface name added to L2BD.

  • learn (bool) – Enable/disable MAC learn.

static vpp_add_l2fib_entry(node, mac, interface, bd_id, static_mac=1, filter_mac=0, bvi_mac=0)

Create a static L2FIB entry on a VPP node.

Parameters
  • node (dict) – Node to add L2FIB entry on.

  • mac (str) – Destination mac address in string format 01:02:03:04:05:06.

  • interface (str or int) – Interface name or sw_if_index.

  • bd_id (int or str) – Bridge domain index.

  • static_mac (int or str) – Set to 1 to create static MAC entry. (Default value = 1)

  • filter_mac (int or str) – Set to 1 to drop packet that’s source or destination MAC address contains defined MAC address. (Default value = 0)

  • bvi_mac (int or str) – Set to 1 to create entry that points to BVI interface. (Default value = 0)

static vpp_get_bridge_domain_data(node, bd_id=4294967295)

Get all bridge domain data from a VPP node. If a domain ID number is provided, return only data for the matching bridge domain.

Parameters
  • node (dict) – VPP node to get bridge domain data from.

  • bd_id (int) – Numeric ID of a specific bridge domain.

Returns

List of dictionaries containing data for each bridge domain, or a single dictionary for the specified bridge domain.

Return type

list or dict

static vpp_setup_bidirectional_cross_connect(node, interface1, interface2)

Create bidirectional cross-connect between 2 interfaces on vpp node.

Parameters
  • node (dict) – Node to add bidirectional cross-connect.

  • interface1 (str or int) – First interface name or sw_if_index.

  • interface2 (str or int) – Second interface name or sw_if_index.

static vpp_setup_bidirectional_l2_patch(node, interface1, interface2)

Create bidirectional l2 patch between 2 interfaces on vpp node.

Parameters
  • node (dict) – Node to add bidirectional l2 patch.

  • interface1 (str or int) – First interface name or sw_if_index.

  • interface2 (str or int) – Second interface name or sw_if_index.

class resources.libraries.python.L2Util.L2VtrOp(value)

Bases: enum.IntEnum

VLAN tag rewrite operation.

L2_VTR_DISABLED = 0
L2_VTR_POP_1 = 3
L2_VTR_POP_2 = 4
L2_VTR_PUSH_1 = 1
L2_VTR_PUSH_2 = 2
L2_VTR_TRANSLATE_1_1 = 5
L2_VTR_TRANSLATE_1_2 = 6
L2_VTR_TRANSLATE_2_1 = 7
L2_VTR_TRANSLATE_2_2 = 8

2.33. LimitUtil suite

Linux limit library.

class resources.libraries.python.LimitUtil.LimitUtil

Bases: object

Class contains methods for getting or setting process resource limits.

static get_pid_limit(node, pid)

Get process resource limits.

Parameters
  • node (dict) – Node in the topology.

  • pid (int) – Process ID.

static set_pid_limit(node, pid, resource, limit)

Set process resource limits.

Parameters
  • node (dict) – Node in the topology.

  • pid (int) – Process ID.

  • resource (str) – Resource to set limits.

  • limit (str) – Limit value.

2.34. LispSetup suite

Library to set up Lisp in topology.

class resources.libraries.python.LispSetup.EidType(value)

Bases: enum.IntEnum

EID types.

MAC = 1
NSH = 2
PREFIX = 0
class resources.libraries.python.LispSetup.LispAdjacency

Bases: object

Class for lisp adjacency API.

static vpp_add_lisp_adjacency(node, vni, deid, deid_prefix, seid, seid_prefix, is_mac=False)

Add lisp adjacency on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • vni (int) – Vni.

  • deid (str) – Destination eid address.

  • deid_prefix (int) – Destination eid address prefix_len.

  • seid (str) – Source eid address.

  • seid_prefix (int) – Source eid address prefix_len.

  • is_mac (bool) – Set to True if the deid/seid is MAC address.

static vpp_del_lisp_adjacency(node, vni, deid, deid_prefix, seid, seid_prefix)

Delete lisp adjacency on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • vni (int) – Vni.

  • deid (str) – Destination eid address.

  • deid_prefix (int) – Destination eid address prefix_len.

  • seid (str) – Source eid address.

  • seid_prefix (int) – Source eid address prefix_len.

class resources.libraries.python.LispSetup.LispEid

Bases: object

Class for lisp eid.

static create_eid(eid, prefix_len)

Create lisp eid object.

Parameters
  • eid (str) – Eid value.

  • prefix_len (int) – Prefix len if the eid is IP address.

class resources.libraries.python.LispSetup.LispEidTableMap

Bases: object

Class for EID table map.

static vpp_lisp_eid_table_mapping(node, vni, bd_id=None, vrf=None)

Map LISP VNI to either bridge domain ID, or VRF ID.

Parameters
  • node (dict) – VPP node.

  • vni (int) – Lisp VNI.

  • bd_id (int) – Bridge domain ID.

  • vrf (int) – VRF id.

class resources.libraries.python.LispSetup.LispGpeStatus

Bases: object

Class for LISP GPE status manipulation.

static vpp_lisp_gpe_enable_disable(node, state)

Change the state of LISP GPE - enable or disable.

Parameters
  • node (dict) – VPP node.

  • state (str) – Requested state - enable or disable.

class resources.libraries.python.LispSetup.LispLocalEid

Bases: object

Class for Lisp local eid API.

static vpp_add_lisp_local_eid(node, locator_set_name, vni, eid, prefix_len=None)

Set lisp eid address on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • locator_set_name (str) – Name of the locator_set.

  • vni (int) – Vni value.

  • eid (str) – Eid value.

  • prefix_len (int) – Prefix len if the eid is IP address.

static vpp_del_lisp_local_eid(node, locator_set_name, vni, eid, prefix_len=None)

Set lisp eid address on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • locator_set_name (str) – Name of the locator_set.

  • vni (int) – Vni value.

  • eid (str) – Eid value.

  • prefix_len (int) – Prefix len if the eid is IP address.

class resources.libraries.python.LispSetup.LispLocator

Bases: object

Class for the Lisp Locator API.

static vpp_add_lisp_locator(node, locator_name, sw_if_index, priority, weight)

Set lisp locator on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • locator_name (str) – Name of the locator_set.

  • sw_if_index (int) – Sw_if_index if the interface.

  • priority (int) – Priority of the locator.

  • weight (int) – Weight of the locator.

static vpp_del_lisp_locator(node, locator_name, sw_if_index, priority, weight)

Unset lisp locator on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • locator_name (str) – Name of the locator_set.

  • sw_if_index (int) – Sw_if_index if the interface.

  • priority (int) – Priority of the locator.

  • weight (int) – Weight of the locator.

class resources.libraries.python.LispSetup.LispLocatorSet

Bases: object

Class for Lisp Locator Set API.

static vpp_add_lisp_locator_set(node, name)

Add lisp locator_set on VPP.

Parameters
  • node (dict) – VPP node.

  • name (str) – VPP locator name.

static vpp_del_lisp_locator_set(node, name)

Del lisp locator_set on VPP.

Parameters
  • node (dict) – VPP node.

  • name (str) – VPP locator name.

class resources.libraries.python.LispSetup.LispRemoteLocator

Bases: object

Class for lisp remote locator.

static create_rloc(ip_addr, priority=0, weight=0)

Create lisp remote locator object.

Parameters
  • ip_addr (str) – IP/IPv6 address.

  • priority (int) – Priority of the remote locator.

  • weight (int) – Weight of the remote locator.

class resources.libraries.python.LispSetup.LispRemoteMapping

Bases: object

Class for lisp remote mapping API.

static vpp_add_lisp_remote_mapping(node, vni, deid, deid_prefix, seid, seid_prefix, rloc, is_mac=False)

Add lisp remote mapping on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • vni (int) – Vni.

  • deid (str) – Destination eid address.

  • deid_prefix (int) – Destination eid address prefix_len.

  • seid (str) – Source eid address.

  • seid_prefix (int) – Source eid address prefix_len.

  • rloc (str) – Receiver locator.

  • is_mac (bool) – Set to True if the deid/seid is MAC address.

static vpp_del_lisp_remote_mapping(node, vni, deid, deid_prefix, seid, seid_prefix, rloc)

Delete lisp remote mapping on the VPP node in topology.

Parameters
  • node (dict) – VPP node.

  • vni (int) – Vni.

  • deid (str) – Destination eid address.

  • deid_prefix (int) – Destination eid address prefix_len.

  • seid (str) – Source eid address.

  • seid_prefix (int) – Source eid address prefix_len.

  • rloc (str) – Receiver locator.

class resources.libraries.python.LispSetup.LispStatus

Bases: object

Class for lisp API.

static vpp_lisp_enable_disable(node, state)

Enable/Disable lisp in the VPP node in topology.

Parameters
  • node (dict) – Node of the test topology.

  • state (str) – State of the lisp, enable or disable.

2.35. LoadBalancerUtil suite

Loadbalancer util library.

class resources.libraries.python.LoadBalancerUtil.LoadBalancerUtil

Bases: object

Basic Loadbalancer parameter configuration.

static vpp_lb_add_del_as(node, **kwargs)

Config AS for Loadbalancer.

Parameters
  • node (dict) – Node where the interface is.

  • kwargs (dict) –

    Optional key-value arguments:

    vip_addr: IPv4 address to be used as source for IPv4 traffic. (str) protocol: tcp or udp. (int) port: destination port. (int) as_addr: The application server address. (str) is_del: 1 if the VIP should be removed otherwise 0. (int) is_flush: 1 if the sessions related to this AS should be flushed otherwise 0. (int)

Returns

Nothing.

Raises

ValueError – If the node has an unknown node type.

static vpp_lb_add_del_intf_nat4(node, **kwargs)

Enable/disable NAT4 feature on the interface.

Parameters
  • node (dict) – Node where the interface is.

  • kwargs (dict) –

    Optional key-value arguments:

    is_add: true if add, false if delete. (bool) interface: software index of the interface. (int)

Returns

Nothing.

Raises

ValueError – If the node has an unknown node type.

static vpp_lb_add_del_vip(node, **kwargs)

Config vip for loadbalancer.

Parameters
  • node (dict) – Node where the interface is.

  • kwargs (dict) –

    Optional key-value arguments:

    vip_addr: IPv4 address to be used as source for IPv4 traffic. (str) protocol: tcp or udp. (int) port: destination port. (int) encap: encap is ip4 GRE(0) or ip6 (1GRE) or L3DSR(2) or NAT4(3) or NAT6(4). (int) dscp: dscp bit corresponding to VIP type: service type target_port: Pod’s port corresponding to specific service node_port: Node’s port new_len: Size of the new connections flow table used for this VIP is_del: 1 if the VIP should be removed otherwise 0.

Returns

Nothing.

Raises

ValueError – If the node has an unknown node type.

static vpp_lb_conf(node, **kwargs)

Config global parameters for loadbalancer.

Parameters
  • node (dict) – Node where the interface is.

  • kwargs (dict) –

    Optional key-value arguments:

    ip4_src_addr: IPv4 address to be used as source for IPv4 traffic.

    (str)

    ip6_src_addr: IPv6 address to be used as source for IPv6 traffic.

    (str)

    flow_timeout: Time in seconds after which, if no packet is received

    for a given flow, the flow is removed from the established flow table. (int)

    buckets_per_core: Number of buckets per worker thread in the

    established flow table (int)

Returns

Nothing.

Raises

ValueError – If the node has an unknown node type.

2.36. LocalExecution suite

Python library from executing command on local hosts.

Subprocess offers various functions, but there are differences between Python 2 and 3.

Overall, it is more convenient to introduce this internal API so call sites are shorter and unified.

This library should support commands given as Iterable, OptionString.

Commands given as a string are explicitly not supported, call sites should call .split(” “) on their own risk. Similarly, parts within OptionString should not be aggregates. Alternatively, long string can be wrapped as ‘bash -c “{str}”’. Both approaches can be hacked by malicious values.

resources.libraries.python.LocalExecution.run(command, msg='', check=True, log=False, console=False)

Wrapper around subprocess.check_output that can tolerates nonzero RCs.

Stderr is redirected to stdout, so it is part of output (but can be mingled as the two streams are buffered independently). If check and rc is nonzero, RuntimeError is raised. If log (and not checked failure), both rc and output are logged. Logging is performed on robot logger. By default .debug(), optionally .console() instead. The default log message is optionally prepended by user-given string, separated by “: “.

Commands given as single string are not supported, for safety reasons. Invoke bash explicitly if you need its glob support for arguments.

Parameters
  • command (Iterable or OptionString) – List of commands and arguments. Split your long string.

  • msg (str) – Message prefix. Argument name is short just to save space.

  • check (bool) – Whether to raise if return code is nonzero.

  • log (bool) – Whether to log results.

  • console (bool) – Whether use .console() instead of .debug(). Mainly useful when running from non-main thread.

Returns

rc and output

Return type

2-tuple of int and str

Raises
  • RuntimeError – If check is true and return code non-zero.

  • TypeError – If command is not an iterable.

2.37. Memif suite

Memif interface library.

class resources.libraries.python.Memif.Memif

Bases: object

Memif interface class

static create_memif_interface(node, filename, mid, sid, rxq=1, txq=1, role='SLAVE')

Create Memif interface on the given node.

Parameters
  • node (dict) – Given node to create Memif interface on.

  • filename (str) – Memif interface socket filename.

  • mid (str) – Memif interface ID.

  • sid (str) – Socket ID.

  • rxq (int) – Number of RX queues; 0 means do not set.

  • txq (int) – Number of TX queues; 0 means do not set.

  • role (str) – Memif interface role [master=0|slave=1]. Default is master.

Returns

SW interface index.

Return type

int

Raises

ValueError – If command ‘create memif’ fails.

static show_memif(node)

Show Memif data for the given node.

Parameters

node (dict) – Given node to show Memif data on.

static show_memif_on_all_duts(nodes)

Show Memif data on all DUTs.

Parameters

nodes (dict) – Topology nodes.

static vpp_get_memif_interface_mac(node, sw_if_index)

Get Memif interface MAC address from Memif interfaces dump.

Parameters
  • node (dict) – DUT node.

  • sw_if_index (int) – DUT node.

Returns

Memif interface MAC address, or None if not found.

Return type

str

static vpp_get_memif_interface_name(node, sw_if_index)

Get Memif interface name from Memif interfaces dump.

Parameters
  • node (dict) – DUT node.

  • sw_if_index (int) – DUT node.

Returns

Memif interface name, or None if not found.

Return type

str

class resources.libraries.python.Memif.MemifRole(value)

Bases: enum.IntEnum

Memif interface roles

MASTER = 0
SLAVE = 1

2.38. NATUtil suite

NAT utilities library.

class resources.libraries.python.NATUtil.NATUtil

Bases: object

This class defines the methods to set NAT.

static compute_max_translations_per_thread(sessions, threads)

Compute value of max_translations_per_thread NAT44 parameter based on total number of worker threads.

Parameters
  • sessions (int) – Required number of NAT44 sessions.

  • threads (int) – Number of worker threads.

Returns

Value of max_translations_per_thread NAT44 parameter.

Return type

int

static enable_det44_plugin(node, inside_vrf=0, outside_vrf=0)

Enable DET44 plugin.

Parameters
  • node (dict) – DUT node.

  • inside_vrf (str or int) – Inside VRF ID.

  • outside_vrf (str or int) – Outside VRF ID.

static enable_nat44_ed_plugin(node, inside_vrf=0, outside_vrf=0, sessions=0, session_memory=0, mode='')

Enable NAT44 plugin.

Parameters
  • node (dict) – DUT node.

  • inside_vrf (str or int) – Inside VRF ID.

  • outside_vrf (str or int) – Outside VRF ID.

  • sessions (str or int) – Maximum number of sessions.

  • session_memory (str or int) – Session memory size - overwrite auto calculated hash allocation parameter if non-zero.

  • mode (str) – NAT44 mode. Valid values: - endpoint-independent - endpoint-dependent - static-mapping-only - connection-tracking - out2in-dpo

static get_det44_mapping(node)

Get DET44 mapping data.

Parameters

node (dict) – DUT node.

Returns

Dictionary of DET44 mapping data.

Return type

dict

static get_det44_sessions_number(node)

Get number of established DET44 sessions from actual DET44 mapping data. :param node: DUT node. :type node: dict :returns: Number of established DET44 sessions. :rtype: int

static get_nat44_sessions_number(node, proto)

Get number of expected NAT44 sessions from NAT44 mapping data.

This keyword uses output from a CLI command, so it can start failing when VPP changes the output format. TODO: Switch to API (or stat segment) when available.

The current implementation supports both 2202 and post-2202 format. (The Gerrit number changing the output format is 34877.)

For TCP proto, the expected state after rampup is some number of sessions in transitory state (VPP has seen the FINs), and some number of sessions in established state (meaning some FINs were lost in the last trial). While the two states may need slightly different number of cycles to process next packet, the current implementation considers both of them the “fast path”, so they are both counted as expected.

As the tests should fail if a session is timed-out, the logic substracts timed out sessions for the returned value (only available for post-2202 format).

TODO: Investigate if it is worth to insert additional rampup trials in TPUT tests to ensure all sessions are transitory before next measurement.

Parameters
  • node (dict) – DUT node.

  • proto (str) – Required protocol - TCP/UDP/ICMP.

Returns

Number of active established NAT44 sessions.

Return type

int

Raises
  • ValueError – If not supported protocol.

  • RuntimeError – If output is not formatted as expected.

static set_det44_interface(node, if_key, is_inside)

Enable DET44 feature on the interface.

Parameters
  • node (dict) – DUT node.

  • if_key (str) – Interface key from topology file of interface to enable DET44 feature on.

  • is_inside (bool) – True if interface is inside, False if outside.

static set_det44_mapping(node, ip_in, subnet_in, ip_out, subnet_out)

Set DET44 mapping.

The return value is a callable (zero argument Python function) which can be used to reset NAT state, so repeated trial measurements hit the same slow path.

Parameters
  • node (dict) – DUT node.

  • ip_in (str) – Inside IP.

  • subnet_in (str or int) – Inside IP subnet.

  • ip_out (str) – Outside IP.

  • subnet_out (str or int) – Outside IP subnet.

static set_nat44_address_range(node, start_ip, end_ip, vrf_id=4294967295, flag='NAT_IS_NONE')

Set NAT44 address range.

The return value is a callable (zero argument Python function) which can be used to reset NAT state, so repeated trial measurements hit the same slow path.

Parameters
  • node (dict) – DUT node.

  • start_ip (str) – IP range start.

  • end_ip (str) – IP range end.

  • vrf_id (int) – VRF index (Optional).

  • flag (str) – NAT flag name.

Returns

Resetter of the NAT state.

Return type

Callable[[], None]

static set_nat44_interface(node, interface, flag)

Set inside and outside interfaces for NAT44.

Parameters
  • node (dict) – DUT node.

  • interface (str) – NAT44 interface.

  • flag (str) – Interface NAT configuration flag name.

static set_nat44_interfaces(node, int_in, int_out)

Set inside and outside interfaces for NAT44.

Parameters
  • node (dict) – DUT node.

  • int_in (str) – Inside interface.

  • int_out (str) – Outside interface.

static show_det44(node)

Show DET44 data.

Used data sources:

det44_interface_dump det44_map_dump det44_session_dump

Parameters

node (dict) – DUT node.

static show_nat44_config(node)

Show the NAT44 plugin running configuration.

Parameters

node (dict) – DUT node.

static show_nat44_summary(node)

Show NAT44 summary on the specified topology node.

Parameters

node (dict) – Topology node.

Returns

NAT44 summary data.

Return type

str

static show_nat_base_data(node)

Show the NAT base data.

Used data sources:

nat_worker_dump nat44_interface_addr_dump nat44_address_dump nat44_static_mapping_dump nat44_interface_dump

Parameters

node (dict) – DUT node.

static show_nat_user_data(node)

Show the NAT user data.

Used data sources:

nat44_user_dump nat44_user_session_dump

Parameters

node (dict) – DUT node.

class resources.libraries.python.NATUtil.Nat44ConfigFlags(value)

Bases: enum.IntEnum

NAT44 configuration flags

NAT44_IS_CONNECTION_TRACKING = 4
NAT44_IS_ENDPOINT_DEPENDENT = 1
NAT44_IS_ENDPOINT_INDEPENDENT = 0
NAT44_IS_OUT2IN_DPO = 8
NAT44_IS_STATIC_MAPPING_ONLY = 2
class resources.libraries.python.NATUtil.NatAddrPortAllocAlg(value)

Bases: enum.IntEnum

NAT Address and port assignment algorithms.

NAT_ALLOC_ALG_DEFAULT = 0
NAT_ALLOC_ALG_MAP_E = 1
NAT_ALLOC_ALG_PORT_RANGE = 2
class resources.libraries.python.NATUtil.NatConfigFlags(value)

Bases: enum.IntEnum

NAT plugin configuration flags

NAT_IS_ADDR_ONLY = 8
NAT_IS_EXT_HOST_VALID = 128
NAT_IS_INSIDE = 32
NAT_IS_NONE = 0
NAT_IS_OUT2IN_ONLY = 4
NAT_IS_OUTSIDE = 16
NAT_IS_SELF_TWICE_NAT = 2
NAT_IS_STATIC = 64
NAT_IS_TWICE_NAT = 1

2.39. Namespaces suite

Linux namespace utilities library.

class resources.libraries.python.Namespaces.Namespaces

Bases: object

Linux namespace utilities.

static add_default_route_to_namespace(node, namespace, default_route)

Add IPv4 default route to interface in namespace.

Parameters
  • node (dict) – Node where to execute command.

  • namespace (str) – Namespace to execute command on.

  • default_route (str) – Default route address.

static attach_interface_to_namespace(node, namespace, interface)

Attach specific interface to namespace.

Parameters
  • node (dict) – Node where to execute command.

  • namespace (str) – Namespace to execute command on.

  • interface (str) – Interface in namespace.

Raises

RuntimeError – Interface could not be attached.

static clean_up_namespaces(node, namespace=None)

Delete all old namespaces.

Parameters
  • node (dict) – Node where to execute command.

  • namespace (str) – Namespace to delete, if None delete all namespaces

Raises

RuntimeError – Namespaces could not be cleaned properly.

static create_bridge_for_int_in_namespace(node, namespace, bridge_name, *interfaces)

Setup bridge domain and add interfaces to it.

Parameters
  • node (dict) – Node where to execute command.

  • namespace (str) – Namespace to execute command on.

  • bridge_name (str) – Name of the bridge to be created.

  • interfaces (list) – List of interfaces to add to the namespace.

static create_namespace(node, namespace, delete_before_create=True)

Create namespace and add the name to the list for later clean-up.

Parameters
  • node (dict) – Where to create namespace.

  • namespace (str) – Name for namespace.

  • delete_before_create (bool) – Delete namespace prior to create

static delete_namespace(node, namespace)

Delete namespace from the node and list.

Parameters
  • node (dict) – Where to delete namespace.

  • namespace (str) – Name for namespace.

  • delete_before_create (bool) – Delete namespace prior to create

2.40. NginxConfigGenerator suite

Nginx Configuration File Generator library.

class resources.libraries.python.NginxConfigGenerator.NginxConfigGenerator

Bases: object

NGINX Configuration File Generator.

add_config_item(config, value, path)

Add NGINX configuration item.

Parameters
  • config (dict) – Startup configuration of node.

  • value (str) – Value to insert.

  • path (list) – Path where to insert item.

add_daemon(value='off')

Add daemon configuration.

add_events_accept_mutex(value='off')

Add Events accept mutex configuration.

add_events_multi_accept(value='off')

Add Events multi accept configuration.

add_events_use(value='epoll')

Add Events use configuration.

add_events_worker_connections(value=10240)

Add Events worker connections configuration.

add_http_access_log(value='off')

Add Http access_log configuration.

add_http_default_type(value='application/octet-stream')

Add Http default_type configuration.

add_http_include(value='mime.types')

Add Http include configuration.

add_http_keepalive_requests(value)

Add Http keepalive alive requests configuration.

add_http_keepalive_timeout(value)

Add Http keepalive alive timeout configuration.

add_http_sendfile(value='on')

Add Http sendfile configuration.

add_http_server_index(value='index.html index.htm')

Add Http Server index configuration.

add_http_server_listen(value)

Add Http Server listen port configuration.

add_http_server_location(size)

Add Http Server location configuration.

Parameters

size (int) – File size.

add_http_server_root(value='html')

Add Http Server root configuration.

add_master_process(value='on')

Add master process configuration.

add_worker_processes(value, smt_used)

Add worker processes configuration.

add_worker_rlimit_nofile(value=10240)

Add Events worker rlimit nofile configuration.

apply_config(filename=None, verify_nginx=True)

Generate and write NGINX configuration to file and verify configuration.

Parameters
  • filename (str) – NGINX configuration file name.

  • verify_nginx (bool) – Verify NGINX configuration.

dump_config(obj, level=- 1)

Dump the startup configuration in NGINX config format.

Parameters
  • obj (Obj) – Python Object to print.

  • level (int) – Nested level for indentation.

Returns

nothing

set_nginx_path(packages_dir, nginx_version)

Set NGINX Conf Name.

Parameters
  • packages_dir (str) – NGINX install path.

  • nginx_version (str) – Test NGINX version.

Raises

RuntimeError – If Node type is not DUT.

set_node(node)

Set DUT node.

Parameters

node (dict) – Node to store configuration on.

Raises

RuntimeError – If Node type is not DUT.

write_config(filename=None)

Generate and write NGINX startup configuration to file.

Parameters

filename (str) – NGINX configuration file name.

2.41. NginxUtil suite

NGINX Utilities Library.

class resources.libraries.python.NginxUtil.NginxUtil

Bases: object

Utilities for NGINX.

static get_cmd_options(**kwargs)

Create parameters options.

Parameters

kwargs (dict) – Dict of cmd parameters.

Returns

cmd parameters.

Return type

OptionString

static nginx_cmd_start(node, path, filename)

Start NGINX cmd app on node. :param node: Topology node. :param path: Nginx install path. :param filename: Nginx conf name. :type node: dict :type path: str :type filename: str

Returns

nothing

static nginx_cmd_stop(node, path)

Stop NGINX cmd app on node. :param node: Topology node. :param path: Nginx install path. :type node: dict :type path: str :returns: nothing

static nginx_config_verify(node, path)

Start NGINX cmd app on node. :param node: Topology node. :param path: Nginx install path. :type node: dict :type path: str :returns: nothing

static taskset_nginx_pid_to_idle_cores(node, cpu_idle_list)

Set idle cpus to NGINX pid on node.

Parameters
  • node (dict) – Topology node.

  • cpu_idle_list (list) – Idle Cpus.

Returns

nothing

2.42. NodePath suite

Path utilities library for nodes in the topology.

class resources.libraries.python.NodePath.NodePath

Bases: object

Path utilities for nodes in the topology.

Example

node1–link1–>node2–link2–>node3–link3–>node2–link4–>node1 RobotFramework: | Library | resources/libraries/python/NodePath.py

Path test
| [Arguments] | ${node1} | ${node2} | ${node3}
| Append Node | ${nodes1}
| Append Node | ${nodes2}
| Append Nodes | ${nodes3} | ${nodes2}
| Append Node | ${nodes1}
| Compute Path | ${FALSE}
| ${first_int} | ${node}= | First Interface
| ${last_int} | ${node}= | Last Interface
| ${first_ingress} | ${node}= | First Ingress Interface
| ${last_egress} | ${node}= | Last Egress Interface
| ${next} | ${node}= | Next Interface

Python: >>> from NodePath import NodePath >>> path = NodePath() >>> path.append_node(node1) >>> path.append_node(node2) >>> path.append_nodes(node3, node2) >>> path.append_node(node1) >>> path.compute_path() >>> (interface, node) = path.first_interface() >>> (interface, node) = path.last_interface() >>> (interface, node) = path.first_ingress_interface() >>> (interface, node) = path.last_egress_interface() >>> (interface, node) = path.next_interface()

append_node(node, filter_list=None)

Append node to the path.

Parameters
  • node (dict) – Node to append to the path.

  • filter_list (list of strings) – Filter criteria list.

append_nodes(*nodes, filter_list=None)

Append nodes to the path.

Parameters
  • nodes (dict) – Nodes to append to the path.

  • filter_list (list of strings) – Filter criteria list.

Note

Node order does matter.

clear_path()

Clear path.

compute_circular_topology(nodes, filter_list=None, nic_pfs=1, always_same_link=False, topo_has_tg=True, topo_has_dut=True)

Return computed circular path.

Parameters
  • nodes (dict) – Nodes to append to the path.

  • filter_list (list of strings) – Filter criteria list.

  • nic_pfs (int) – Number of PF of NIC.

  • always_same_link (bool) – If True use always same link between two nodes in path. If False use different link (if available) between two nodes if one link was used before.

  • topo_has_tg (bool) – If True, the topology has a TG node. If False, the topology consists entirely of DUT nodes.

  • topo_has_dut (bool) – If True, the topology has a DUT node(s). If False, the topology consists entirely of TG nodes.

Returns

Topology information dictionary.

Return type

dict

Raises

RuntimeError – If unsupported combination of parameters.

compute_path(always_same_link=True, topo_has_dut=True)

Compute path for added nodes.

Note

First add at least two nodes to the topology.

Parameters
  • always_same_link (bool) – If True use always same link between two nodes in path. If False use different link (if available) between two nodes if one link was used before.

  • topo_has_dut (bool) – If False we want to test back to back test on TG.

Raises

RuntimeError – If not enough nodes for path.

first_ingress_interface()

Return first ingress interface on the path.

Returns

Interface and node.

Return type

tuple (str, dict)

Note

Call compute_path before.

first_interface()

Return first interface on the path.

Returns

Interface and node.

Return type

tuple (str, dict)

Note

Call compute_path before.

last_egress_interface()

Return last egress interface on the path.

Returns

Interface and node.

Return type

tuple (str, dict)

Note

Call compute_path before.

last_interface()

Return last interface on the path.

Returns

Interface and node.

Return type

tuple (str, dict)

Note

Call compute_path before.

next_interface()

Path interface iterator.

Returns

Interface and node or None if not next interface.

Return type

tuple (str, dict)

Note

Call compute_path before.

2.43. NsimUtil suite

VPP Network Simulator Plugin util library.

class resources.libraries.python.NsimUtil.NsimUtil

Bases: object

VPP NSIM Plugin Keywords.

static configure_vpp_nsim(node, vpp_nsim_attr, interface0, interface1=None)

Configure nsim on the specified VPP node.

Parameters
  • node (dict) – Topology node.

  • vpp_nsim_attr (dict) – VPP NSIM configuration attributes

  • interface0 (str or int) – Interface name.

  • interface1 (str or int) – 2nd Interface name for cross-connect feature

Raises

RuntimeError – if no NSIM features are enabled or vpp papi command fails.

2.44. OptionString suite

Utility function for handling options without doubled or trailing spaces.

class resources.libraries.python.OptionString.OptionString(parts=(), prefix='')

Bases: object

Class serving as a builder for option strings.

Motivation: Both manual concatenation and .join() methods are prone to leaving superfluous spaces if some parts of options are optional (missing, empty).

The scope of this class is more general than just command line options, it can concatenate any string consisting of words that may be missing. But options were the first usage, so method arguments are frequently named “parameter” and “value”. To keep this generality, automated adding of dashes is optional, and disabled by default.

Parts of the whole option string are kept as list items (string, stipped), with prefix already added. Empty strings are never added to the list (except by constructor).

The class offers many methods for adding, so that callers can pick the best fitting one, without much logic near the call site.

add(parameter)

Add parameter if nonempty to the list of parts.

Parameter object is converted to string and stripped. If parameter converts to empty string, nothing is added. Parameter is prefixed before adding.

Parameters

parameter (object) – Parameter object, usually a word starting with dash.

Returns

Self, to enable method chaining.

Return type

OptionString

add_equals(parameter, value)

Add parameter=value to the list of parts.

Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – Parameter object, usually a word starting with dash.

  • value (object) – Value object. Prefix is never added.

Returns

Self, to enable method chaining.

Return type

OptionString

add_equals_from_dict(parameter, key, mapping, default='')

Add parameter=value to options where value is from dict.

If key is missing, default is used as value. Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – The parameter part to add with prefix.

  • key (str) – The key to look the value for.

  • mapping (dict) – Mapping with keys and values to use.

  • default (object) – The value to use if key is missing.

Returns

Self, to enable method chaining.

Return type

OptionString

add_equals_if(parameter, value, condition)

Add parameter=value to the list of parts if condition is true.

If condition truth value is false, nothing is added. Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – Parameter object, usually a word starting with dash.

  • value (object) – Value object. Prefix is never added.

  • condition (object) – Do not add if truth value of this is false.

Returns

Self, to enable method chaining.

Return type

OptionString

add_equals_if_from_dict(parameter, value, key, mapping, default='False')

Add parameter=value based on condition in dict.

If key is missing, default is used as condition. If condition truth value is false, nothing is added. Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – The parameter part to add with prefix.

  • value (object) – Value object. Prefix is never added.

  • key (str) – The key to look the value for.

  • mapping (dict) – Mapping with keys and values to use.

  • default (object) – The value to use if key is missing.

Returns

Self, to enable method chaining.

Return type

OptionString

add_if(parameter, condition)

Add parameter if nonempty and condition is true to the list of parts.

If condition truth value is false, nothing is added. Parameter object is converted to string and stripped. If parameter converts to empty string, nothing is added. Parameter is prefixed before adding.

Parameters
  • parameter (object) – Parameter object, usually a word starting with dash.

  • condition (object) – Do not add if truth value of this is false.

Returns

Self, to enable method chaining.

Return type

OptionString

add_if_from_dict(parameter, key, mapping, default='False')

Add parameter based on if the condition in dict is true.

If key is missing, default is used as condition. If condition truth value is false, nothing is added. Parameter is converted to string and stripped. If parameter converts to empty string, nothing is added. Parameter is prefixed before adding.

Parameters
  • parameter (object) – The parameter part to add with prefix.

  • key (str) – The key to look the value for.

  • mapping (dict) – Mapping with keys and values to use.

  • default (object) – The value to use if key is missing.

Returns

Self, to enable method chaining.

Return type

OptionString

add_with_value(parameter, value)

Add parameter, if followed by a value to the list of parts.

Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – Parameter object, usually a word starting with dash.

  • value (object) – Value object. Prefix is never added.

Returns

Self, to enable method chaining.

Return type

OptionString

add_with_value_from_dict(parameter, key, mapping, default='')

Add parameter with value from dict under key, or default.

If key is missing, default is used as value. Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – The parameter part to add with prefix.

  • key (str) – The key to look the value for.

  • mapping (dict) – Mapping with keys and values to use.

  • default (object) – The value to use if key is missing.

Returns

Self, to enable method chaining.

Return type

OptionString

add_with_value_if(parameter, value, condition)

Add parameter and value if condition is true and nothing is empty.

If condition truth value is false, nothing is added. Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – Parameter object, usually a word starting with dash.

  • value (object) – Value object. Prefix is never added.

  • condition (object) – Do not add if truth value of this is false.

Returns

Self, to enable method chaining.

Return type

OptionString

add_with_value_if_from_dict(parameter, value, key, mapping, default='False')

Add parameter and value based on condition in dict.

If key is missing, default is used as condition. If condition truth value is false, nothing is added. Parameter and value are converted to string and stripped. If parameter or value converts to empty string, nothing is added. If added, parameter (but not value) is prefixed.

Parameters
  • parameter (object) – The parameter part to add with prefix.

  • value (object) – Value object. Prefix is never added.

  • key (str) – The key to look the value for.

  • mapping (dict) – Mapping with keys and values to use.

  • default (object) – The value to use if key is missing.

Returns

Self, to enable method chaining.

Return type

OptionString

change_prefix(prefix)

Change the prefix field from the initialized value.

Sometimes it is more convenient to change the prefix in the middle of string construction. Typical use is for constructing a command, where the first part (executeble filename) does not have a dash, but the other parameters do. You could put the first part into constructor argument, but using .add and only then enabling prefix is horizontally shorter.

Parameters

prefix (object) – New prefix value, to be converted and tripped.

Returns

Self, to enable method chaining.

Return type

OptionString

check_and_add(part, prefixed)

Convert to string, strip, conditionally add prefixed if non-empty.

Value of None is converted to empty string. Emptiness is tested before adding prefix.

This could be a protected method (name starting with underscore), but then pylint does not understand add_equals and add_with_value are allowed to call this on the temp instance. TODO: Is there a way to make pylint understand?

Parameters
  • part (object) – Unchecked part to add to list of parts.

  • prefixed (object) – Whether to add prefix when adding.

Returns

The converted part without prefix, empty means not added.

Return type

str

extend(other)

Extend self by contents of other option string.

Parameters

other (OptionString) – Another instance to add to the end of self.

Returns

Self, to enable method chaining.

Return type

OptionString

2.45. PapiExecutor suite

Python API executor library.

class resources.libraries.python.PapiExecutor.Disconnector

Bases: object

Class for holding a single keyword.

static disconnect_all_papi_connections()

Disconnect all connected client instances, tear down the SSH tunnels.

Also remove the local sockets by deleting the temporary directory. Put disconnected client instances to the reuse list. The added attributes are not cleaned up, as their values will get overwritten on next connect.

Call this method just before killing/restarting all VPP instances.

This could be a class method of PapiSocketExecutor. But Robot calls methods on instances, and it would be weird to give node argument for constructor in import. Also, as we have a class of the same name as the module, the keywords defined on module level are not accessible.

class resources.libraries.python.PapiExecutor.PapiExecutor(node)

Bases: object

Contains methods for executing VPP Python API commands on DUTs.

TODO: Remove .add step, make get_stats accept paths directly.

This class processes only one type of VPP PAPI methods: vpp-stats.

The recommended ways of use are (examples):

path = [‘^/if’, ‘/err/ip4-input’, ‘/sys/node/ip4-input’] with PapiExecutor(node) as papi_exec:

stats = papi_exec.add(api_name=’vpp-stats’, path=path).get_stats()

print(‘RX interface core 0, sw_if_index 0:

{0}’. format(stats[0][‘/if/rx’][0][0]))

or

path_1 = [‘^/if’, ] path_2 = [‘^/if’, ‘/err/ip4-input’, ‘/sys/node/ip4-input’] with PapiExecutor(node) as papi_exec:

stats = papi_exec.add(‘vpp-stats’, path=path_1). add(‘vpp-stats’, path=path_2).get_stats()

print(‘RX interface core 0, sw_if_index 0:

{0}’. format(stats[1][‘/if/rx’][0][0]))

Note: In this case, when PapiExecutor method ‘add’ is used: - its parameter ‘csit_papi_command’ is used only to keep information

that vpp-stats are requested. It is not further processed but it is included in the PAPI history this way: vpp-stats(path=[‘^/if’, ‘/err/ip4-input’, ‘/sys/node/ip4-input’]) Always use csit_papi_command=”vpp-stats” if the VPP PAPI method is “stats”.

  • the second parameter must be ‘path’ as it is used by PapiExecutor method ‘add’.

  • even if the parameter contains multiple paths, there is only one reply item (for each .add).

add(csit_papi_command='vpp-stats', history=True, **kwargs)

Add next command to internal command list; return self.

The argument name ‘csit_papi_command’ must be unique enough as it cannot be repeated in kwargs. The kwargs dict is deep-copied, so it is safe to use the original with partial modifications for subsequent commands.

Parameters
  • csit_papi_command (str) – VPP API command.

  • history (bool) – Enable/disable adding command to PAPI command history.

  • kwargs (dict) – Optional key-value arguments.

Returns

self, so that method chaining is possible.

Return type

PapiExecutor

get_stats(err_msg='Failed to get statistics.', timeout=120, socket='/run/vpp/stats.sock')

Get VPP Stats from VPP Python API.

Parameters
  • err_msg (str) – The message used if the PAPI command(s) execution fails.

  • timeout (int) – Timeout in seconds.

  • socket (str) – Path to Stats socket to tunnel to.

Returns

Requested VPP statistics.

Return type

list of dict

class resources.libraries.python.PapiExecutor.PapiSocketExecutor(node, remote_vpp_socket='/run/vpp/api.sock')

Bases: object

Methods for executing VPP Python API commands on forwarded socket.

Previously, we used an implementation with single client instance and connection being handled by a resource manager. On “with” statement, the instance connected, and disconnected on exit from the “with” block. This was limiting (no nested with blocks) and mainly it was slow: 0.7 seconds per disconnect cycle on Skylake, more than 3 second on Taishan.

The currently used implementation caches the connected client instances, providing speedup and making “with” blocks unnecessary. But with many call sites, “with” blocks are still the main usage pattern. Documentation still lists that as the intended pattern.

As a downside, clients need to be explicitly told to disconnect before VPP restart. There is some amount of retries and disconnects on disconnect (so unresponsive VPPs do not breach test much more than needed), but it is hard to verify all that works correctly. Especially, if Robot crashes, files and ssh processes may leak.

Delay for accepting socket connection is 10s. TODO: Decrease 10s to value that is long enough for creating connection and short enough to not affect performance.

The current implementation downloads and parses .api.json files only once and caches client instances for reuse. Cleanup metadata is added as additional attributes directly to client instances.

The current implementation seems to run into read error occasionally. Not sure if the error is in Python code on Robot side, ssh forwarding, or socket handling at VPP side. Anyway, reconnect after some sleep seems to help, hoping repeated command execution does not lead to surprises. The reconnection is logged at WARN level, so it is prominently shown in log.html, so we can see how frequently it happens.

TODO: Support handling of retval!=0 without try/except in caller.

Note: Use only with “with” statement, e.g.:

cmd = ‘show_version’ with PapiSocketExecutor(node) as papi_exec:

reply = papi_exec.add(cmd).get_reply(err_msg)

This class processes two classes of VPP PAPI methods: 1. Simple request / reply: method=’request’. 2. Dump functions: method=’dump’.

Note that access to VPP stats over socket is not supported yet.

The recommended ways of use are (examples):

  1. Simple request / reply

  1. One request with no arguments:

    cmd = ‘show_version’ with PapiSocketExecutor(node) as papi_exec:

    reply = papi_exec.add(cmd).get_reply(err_msg)

  2. Three requests with arguments, the second and the third ones are the same but with different arguments.

    with PapiSocketExecutor(node) as papi_exec:

    replies = papi_exec.add(cmd1, **args1).add(cmd2, **args2). add(cmd2, **args3).get_replies(err_msg)

  1. Dump functions

    cmd = ‘sw_interface_rx_placement_dump’ with PapiSocketExecutor(node) as papi_exec:

    details = papi_exec.add(cmd, sw_if_index=ifc[‘vpp_sw_index’]). get_details(err_msg)

add(csit_papi_command, history=True, **kwargs)

Add next command to internal command list; return self.

Unless disabled, new entry to papi history is also added at this point. The argument name ‘csit_papi_command’ must be unique enough as it cannot be repeated in kwargs. The kwargs dict is deep-copied, so it is safe to use the original with partial modifications for subsequent commands.

Any pending conflicts from .api.json processing are raised. Then the command name is checked for known CRCs. Unsupported commands raise an exception, as CSIT change should not start using messages without making sure which CRCs are supported. Each CRC issue is raised only once, so subsequent tests can raise other issues.

Parameters
  • csit_papi_command (str) – VPP API command.

  • history (bool) – Enable/disable adding command to PAPI command history.

  • kwargs (dict) – Optional key-value arguments.

Returns

self, so that method chaining is possible.

Return type

PapiSocketExecutor

Raises

RuntimeError – If unverified or conflicting CRC is encountered.

api_json_path = None

String path to .api.json files, a directory somewhere in api_root_dir.

api_package_path = None

String path to PAPI code, a different directory under api_root_dir.

api_root_dir = None

We copy .api json files and PAPI code from DUT to robot machine. This class variable holds temporary directory once created. When python exits, the directory is deleted, so no downloaded file leaks. The value will be set to TemporaryDirectory class instance (not string path) to ensure deletion at exit.

conn_cache = {}

Mapping from node key to connected client instance.

crc_checker = None

Accesses .api.json files at creation, caching speeds up accessing it.

static disconnect_all_papi_connections()

Disconnect all connected client instances, tear down the SSH tunnels.

Also remove the local sockets by deleting the temporary directory. Put disconnected client instances to the reuse list. The added attributes are not cleaned up, as their values will get overwritten on next connect.

This should be a class method, but we prefer to call static methods from Robot.

Call this method just before killing/restarting all VPP instances.

classmethod disconnect_all_sockets_by_node(node)

Disconnect all socket connected client instance.

Noop if not connected.

Also remove the local sockets by deleting the temporary directory. Put disconnected client instances to the reuse list. The added attributes are not cleaned up, as their values will get overwritten on next connect.

Call this method just before killing/restarting remote VPP instance.

classmethod disconnect_by_key(key)

Disconnect a connected client instance, noop it not connected.

Also remove the local sockets by deleting the temporary directory. Put disconnected client instances to the reuse list. The added attributes are not cleaned up, as their values will get overwritten on next connect.

This method is useful for disconnect_all type of work.

Parameters

key (tuple of str) – Tuple identifying the node (and socket).

classmethod disconnect_by_node_and_socket(node, remote_socket='/run/vpp/api.sock')

Disconnect a connected client instance, noop it not connected.

Also remove the local sockets by deleting the temporary directory. Put disconnected client instances to the reuse list. The added attributes are not cleaned up, as their values will get overwritten on next connect.

Call this method just before killing/restarting remote VPP instance.

static dump_and_log(node, cmds)

Dump and log requested information, return None.

Parameters
  • node (dict) – DUT node.

  • cmds (list of str) – Dump commands to be executed.

ensure_api_dirs()

Copy files from DUT to local temporary directory.

If the directory is still there, do not copy again. If copying, also initialize CRC checker (this also performs static checks), and remember PAPI package path. Do not add that to PATH yet.

ensure_vpp_instance()

Create or reuse a closed client instance, return it.

The instance is initialized for unix domain socket access, it has initialized all the bindings, it is removed from the internal list of disconnected instances, but it is not connected (to a local socket) yet.

Returns

VPP client instance ready for connect.

Return type

vpp_papi.VPPApiClient

get_connected_client(check_connected=True)

Return None or cached connected client.

If check_connected, RuntimeError is raised when the client is not in cache. None is returned if client is not in cache (and the check is disabled).

This hides details of what the node key is.

Parameters

check_connected (bool) – Whether cache miss raises.

Returns

Connected client instance, or None if uncached and no check.

Return type

Optional[vpp_papi.VPPApiClient]

Raises

RuntimeError – If cache miss and check enabled.

get_details(err_msg='Failed to get dump details.')

Get dump details from VPP Python API.

The details are parsed into dict-like objects. The number of details per single dump command can vary, and all association between details and dumps is lost, so if you care about the association (as opposed to logging everything at once for debugging purposes), it is recommended to call get_details for each dump (type) separately.

Parameters

err_msg (str) – The message used if the PAPI command(s) execution fails.

Returns

Details, dict objects with fields due to API without “retval”.

Return type

list of dict

get_replies(err_msg='Failed to get replies.')

Get replies from VPP Python API.

The replies are parsed into dict-like objects, “retval” field is guaranteed to be zero on success.

Parameters

err_msg (str) – The message used if the PAPI command(s) execution fails.

Returns

Responses, dict objects with fields due to API and “retval”.

Return type

list of dict

Raises

RuntimeError – If retval is nonzero, parsing or ssh error.

get_reply(err_msg='Failed to get reply.')

Get reply from VPP Python API.

The reply is parsed into dict-like object, “retval” field is guaranteed to be zero on success.

TODO: Discuss exception types to raise, unify with inner methods.

Parameters

err_msg (str) – The message used if the PAPI command(s) execution fails.

Returns

Response, dict object with fields due to API and “retval”.

Return type

dict

Raises

AssertionError – If retval is nonzero, parsing or ssh error.

get_sw_if_index(err_msg='Failed to get reply.')

Get sw_if_index from reply from VPP Python API.

Frequently, the caller is only interested in sw_if_index field of the reply, this wrapper makes such call sites shorter.

TODO: Discuss exception types to raise, unify with inner methods.

Parameters

err_msg (str) – The message used if the PAPI command(s) execution fails.

Returns

Response, sw_if_index value of the reply.

Return type

int

Raises

AssertionError – If retval is nonzero, parsing or ssh error.

classmethod key_for_node_and_socket(node, remote_socket)

Return a hashable object to distinguish nodes.

The usual node object (of “dict” type) is not hashable, and can contain mutable information (mostly virtual interfaces). Use this method to get an object suitable for being a key in dict.

The fields to include are chosen by what ssh needs.

This class method is needed, for disconnect.

Parameters
  • node (dict) – The node object to distinguish.

  • remote_socket (str) – Path to remote socket.

Returns

Tuple of values distinguishing this node from similar ones.

Return type

tuple of str

key_for_self()

Return a hashable object to distinguish nodes.

Just a wrapper around key_for_node_and_socket which sets up proper arguments.

Returns

Tuple of values distinguishing this node from similar ones.

Return type

tuple of str

reusable_vpp_client_list = []

Each connection needs a separate client instance, and each client instance creation needs to parse all .api files, which takes time. If a client instance disconnects, it is put here, so on next connect we can reuse intead of creating new.

static run_cli_cmd(node, cli_cmd, log=True, remote_vpp_socket='/run/vpp/api.sock')

Run a CLI command as cli_inband, return the “reply” field of reply.

Optionally, log the field value.

Parameters
  • node (dict) – Node to run command on.

  • cli_cmd (str) – The CLI command to be run on the node.

  • remote_vpp_socket (str) – Path to remote socket to tunnel to.

  • log (bool) – If True, the response is logged.

Returns

CLI output.

Return type

str

static run_cli_cmd_on_all_sockets(node, cli_cmd, log=True)

Run a CLI command as cli_inband, on all sockets in topology file.

Parameters
  • node (dict) – Node to run command on.

  • cli_cmd (str) – The CLI command to be run on the node.

  • log (bool) – If True, the response is logged.

set_connected_client(client)

Add a connected client instance into cache.

This hides details of what the node key is.

If there already is a client for the computed key, fail, as it is a sign of resource leakage.

Parameters

client (vpp_papi.VPPApiClient) – VPP client instance in connected state.

Raises

RuntimeError – If related key already has a cached client.

2.46. PapiHistory suite

DUT PAPI command history setup library.

class resources.libraries.python.PapiHistory.PapiHistory

Bases: object

Contains methods to set up DUT PAPI command history.

static add_to_papi_history(node, csit_papi_command, papi=True, **kwargs)

Add command to PAPI command history on DUT node.

Repr strings are used for argument values.

The argument name ‘csit_papi_command’ must be unique enough as it cannot be repeated in kwargs.

Examples of PAPI history items:

Request without parameters:

show_threads()

Request with parameters:

ipsec_select_backend(index=1,protocol=1)

Dump:

sw_interface_rx_placement_dump(sw_if_index=4)

VPP Stats:

vpp-stats(path=[‘^/if’, ‘/err/ip4-input’, ‘/sys/node/ip4-input’])

VAT:

sw_interface_set_flags sw_if_index 3 admin-up link-up

Parameters
  • node (dict) – DUT node to add command to PAPI command history for.

  • csit_papi_command (str) – Command to be added to PAPI command history.

  • papi (bool) – Says if the command to store is PAPi or VAT. Remove when VAT executor is completely removed.

  • kwargs (dict) – Optional key-value arguments.

static reset_papi_history(node)

Reset PAPI command history for DUT node.

Parameters

node (dict) – DUT node to reset PAPI command history for.

static reset_papi_history_on_all_duts(nodes)

Reset PAPI command history for all DUT nodes.

Parameters

nodes (dict) – Nodes to reset PAPI command history for.

static show_papi_history(node)

Show PAPI command history for DUT node.

Parameters

node (dict) – DUT node to show PAPI command history for.

static show_papi_history_on_all_duts(nodes)

Show PAPI command history for all DUT nodes.

Parameters

nodes (dict) – Nodes to show PAPI command history for.

2.47. Policer suite

Policer utilities library.

class resources.libraries.python.Policer.Policer

Bases: object

Policer utilities.

static get_dscp_num_value(dscp)

Return DSCP numeric value.

Parameters

dscp (str) – DSCP name.

Returns

DSCP numeric value.

Return type

int

static policer_classify_get_precolor(precolor)

Return policer pre-color numeric value.

Parameters

precolor (str) – Policer pre-color name.

Returns

Policer pre-color numeric value.

Return type

int

static policer_classify_set_interface(node, interface, ip4_table_index=4294967295, ip6_table_index=4294967295, l2_table_index=4294967295, is_add=True)

Set/unset policer classify interface.

Parameters
  • node (dict) – VPP node.

  • interface (str or int) – Interface name or sw_if_index to set/unset policer classify.

  • ip4_table_index (int) – IP4 classify table index (~0 to skip). (Default value = ~0)

  • ip6_table_index (int) – IP6 classify table index (~0 to skip). (Default value = ~0)

  • l2_table_index (int) – L2 classify table index (~0 to skip). (Default value = ~0)

  • is_add (bool) – Set if True, else unset.

static policer_set_configuration(node, policer_name, cir, eir, cbs, ebs, rate_type, round_type, policer_type, conform_action_type, exceed_action_type, violate_action_type, color_aware, is_add=True, conform_dscp=None, exceed_dscp=None, violate_dscp=None)

Configure policer on VPP node.

Parameters
  • node (dict) – VPP node.

  • policer_name (str) – Name of the policer.

  • cir (int) – Committed information rate.

  • eir (int) – Excess (or Peak) information rate.

  • cbs (int) – Committed burst size.

  • ebs (int) – Excess (or Peak) burst size.

  • rate_type (str) – Rate type.

  • round_type (str) – Round type.

  • policer_type (str) – Policer algorithm.

  • conform_action_type (str) – Conform action type.

  • exceed_action_type (str) – Exceed action type.

  • violate_action_type (str) – Violate action type.

  • color_aware (str) – Color-blind (cb) or color-aware (ca).

  • is_add (bool) – Add policer if True, else delete.

  • conform_dscp (str) – DSCP for conform mark_and_transmit action.

  • exceed_dscp (str) – DSCP for exceed mark_and_transmit action.

  • violate_dscp (str) – DSCP for vilate mark_and_transmit action.

class resources.libraries.python.Policer.PolicerAction(value)

Bases: enum.IntEnum

Policer action.

DROP = 0
MARK_AND_TRANSMIT = 2
TRANSMIT = 1
class resources.libraries.python.Policer.PolicerPreColor(value)

Bases: enum.IntEnum

Policer Pre-color.

CONFORM_COLOR = 0
EXCEED_COLOR = 1
VIOLATE_COLOR = 2
class resources.libraries.python.Policer.PolicerRateType(value)

Bases: enum.IntEnum

Policer rate types.

INVALID = 2
KBPS = 0
PPS = 1
class resources.libraries.python.Policer.PolicerRoundType(value)

Bases: enum.IntEnum

Policer round types.

ROUND_INVALID = 3
ROUND_TO_CLOSEST = 0
ROUND_TO_DOWN = 2
ROUND_TO_UP = 1
class resources.libraries.python.Policer.PolicerType(value)

Bases: enum.IntEnum

Policer type.

TYPE_1R2C = 0
TYPE_1R3C_RFC_2697 = 1
TYPE_2R3C_RFC_2698 = 2
TYPE_2R3C_RFC_4115 = 3
TYPE_2R3C_RFC_MEF5CF1 = 4
TYPE_MAX = 5

2.48. QemuManager suite

QEMU Manager library.

class resources.libraries.python.QemuManager.QemuManager(nodes)

Bases: object

QEMU lifecycle management class

ROBOT_LIBRARY_SCOPE = 'TEST CASE'
construct_vms_on_all_nodes(**kwargs)

Construct 1..Mx1..N VMs(s) with specified name on all nodes.

Parameters

kwargs (dict) – Named parameters.

construct_vms_on_node(**kwargs)

Construct 1..Mx1..N VMs(s) on node with specified name.

Parameters

kwargs (dict) – Named parameters.

initialize()

Initialize QemuManager object.

kill_all_vms(force=False)

Kill all added VMs in manager.

Parameters

force (bool) – Force kill all Qemu instances by pkill qemu if True.

start_all_vms(pinning=False)

Start all added VMs in manager.

Parameters

pinning (bool) – If True, then do also QEMU process pinning.

2.49. QemuUtils suite

QEMU utilities library.

class resources.libraries.python.QemuUtils.QemuUtils(node, qemu_id=1, smp=1, mem=512, vnf=None, img='/var/lib/vm/image.iso', page_size='')

Bases: object

QEMU utilities.

ROBOT_LIBRARY_SCOPE = 'TEST CASE'
add_default_params()

Set default QEMU command line parameters.

add_drive(drive_file, drive_format)

Set drive with custom format.

Parameters
  • drive_file (str) – Path to drive image.

  • drive_format (str) – Drive image format.

add_drive_cdrom(drive_file, index=None)

Set CD-ROM drive.

Parameters
  • drive_file (str) – Path to drive image.

  • index (int) – Drive index.

add_kernelvm_params()

Set KernelVM QEMU parameters.

add_net_user(net='10.0.2.0/24')

Set managment port forwarding.

add_qmp_qga()

Set QMP, QGA management.

add_serial()

Set serial to file redirect.

add_vfio_pci_if(pci)

Add VFIO PCI interface.

Parameters

pci (str) – PCI address of interface.

add_vhost_user_if(socket, server=True, jumbo_frames=False, queue_size=None, queues=1, virtio_feature_mask=None)

Add Vhost-user interface.

Parameters
  • socket (str) – Path of the unix socket.

  • server (bool) – If True the socket shall be a listening socket.

  • jumbo_frames (bool) – Set True if jumbo frames are used in the test.

  • queue_size (int) – Vring queue size.

  • queues (int) – Number of queues.

  • virtio_feature_mask (int) – Mask of virtio features to be enabled.

configure_kernelvm_vnf(**kwargs)

Create KernelVM VNF configurations.

Parameters

kwargs (dict) – Key-value pairs for templating configs.

create_kernelvm_config_iperf3()

Create QEMU iperf3 command line.

create_kernelvm_config_testpmd_io(**kwargs)

Create QEMU testpmd-io command line.

Parameters

kwargs (dict) – Key-value pairs to construct command line parameters.

create_kernelvm_config_testpmd_mac(**kwargs)

Create QEMU testpmd-mac command line.

Parameters

kwargs (dict) – Key-value pairs to construct command line parameters.

create_kernelvm_config_vpp(**kwargs)

Create QEMU VPP config files.

Parameters

kwargs (dict) – Key-value pairs to replace content of VPP configuration file.

create_kernelvm_init(**kwargs)

Create QEMU init script.

Parameters

kwargs (dict) – Key-value pairs to replace content of init startup file.

get_qemu_pids()

Get QEMU CPU pids.

Returns

List of QEMU CPU pids.

Return type

list of str

qemu_kill()

Kill qemu process.

qemu_kill_all()

Kill all qemu processes on DUT node if specified.

qemu_set_affinity(*host_cpus)

Set qemu affinity by getting thread PIDs via QMP and taskset to list of CPU cores. Function tries to execute 3 times to avoid race condition in getting thread PIDs.

Parameters

host_cpus (list) – List of CPU cores.

qemu_set_scheduler_policy()

Set scheduler policy to SCHED_RR with priority 1 for all Qemu CPU processes.

Raises

RuntimeError – Set scheduler policy failed.

qemu_start()

Start QEMU and wait until VM boot.

Returns

VM node info.

Return type

dict

qemu_version()

Return Qemu version.

Returns

Qemu version.

Return type

str

2.50. SRv6 suite

Segment Routing over IPv6 data plane utilities library.

class resources.libraries.python.SRv6.SRv6

Bases: object

SRv6 class.

static configure_sr_localsid(node, local_sid, behavior, interface=None, next_hop=None, fib_table=None, out_if=None, in_if=None, src_addr=None, sid_list=None)

Create SRv6 LocalSID and binds it to a particular behaviour on the given node.

Parameters
  • node (dict) – Given node to create localSID on.

  • local_sid (str) – LocalSID IPv6 address.

  • behavior (str) – SRv6 LocalSID function.

  • interface (str) – Interface name (Optional, required for L2/L3 xconnects).

  • next_hop (str) – Next hop IPv4/IPv6 address (Optional, required for L3 xconnects).

  • fib_table (str) – FIB table for IPv4/IPv6 lookup (Optional, required for L3 routing).

  • out_if (str) – Interface name of local interface for sending traffic towards the Service Function (Optional, required for SRv6 endpoint to SR-unaware appliance).

  • in_if (str) – Interface name of local interface receiving the traffic coming back from the Service Function (Optional, required for SRv6 endpoint to SR-unaware appliance).

  • src_addr (str) – Source address on the packets coming back on in_if interface (Optional, required for SRv6 endpoint to SR-unaware appliance via static proxy).

  • sid_list (list) – SID list (Optional, required for SRv6 endpoint to SR-unaware appliance via static proxy).

Raises

ValueError – If required parameter is missing.

static configure_sr_policy(node, bsid, sid_list, mode='encap')

Create SRv6 policy on the given node.

Parameters
  • node (dict) – Given node to create SRv6 policy on.

  • bsid (str) – BindingSID - local SID IPv6 address.

  • sid_list (list) – SID list.

  • mode (str) – Encapsulation / insertion mode.

static configure_sr_steer(node, mode, bsid, interface=None, ip_addr=None, prefix=None)

Create SRv6 steering policy on the given node.

Parameters
  • node (dict) – Given node to create steering policy on.

  • mode (str) – Mode of operation - L2 or L3.

  • bsid (str) – BindingSID - local SID IPv6 address.

  • interface (str) – Interface name (Optional, required in case of L2 mode).

  • ip_addr (str) – IPv4/IPv6 address (Optional, required in case of L3 mode).

  • prefix (int) – IP address prefix (Optional, required in case of L3 mode).

Raises

ValueError – If unsupported mode used or required parameter is missing.

static create_srv6_sid_list(sids)

Create SRv6 SID list object.

Parameters

sids (list) – SID IPv6 addresses.

Returns

SRv6 SID list object.

Return type

dict

static set_sr_encaps_source_address(node, ip6_addr)

Set SRv6 encapsulation source address on the given node.

Parameters
  • node (dict) – Given node to set SRv6 encapsulation source address on.

  • ip6_addr (str) – Local SID IPv6 address.

static show_sr_localsids(node)

Show SRv6 LocalSIDs on the given node.

Parameters

node (dict) – Given node to show localSIDs on.

static show_sr_policies(node)

Show SRv6 policies on the given node.

Parameters

node (dict) – Given node to show SRv6 policies on.

static show_sr_steering_policies(node)

Show SRv6 steering policies on the given node.

Parameters

node (dict) – Given node to show SRv6 steering policies on.

class resources.libraries.python.SRv6.SRv6Behavior(value)

Bases: enum.IntEnum

SRv6 LocalSID supported functions.

END = 1
END_AD = 21
END_AM = 22
END_AS = 20
END_DT4 = 9
END_DT6 = 8
END_DX2 = 5
END_DX4 = 7
END_DX6 = 6
END_X = 2
class resources.libraries.python.SRv6.SRv6PolicySteeringTypes(value)

Bases: enum.IntEnum

SRv6 steering types.

SR_STEER_IPV4 = 4
SR_STEER_IPV6 = 6
SR_STEER_L2 = 2

2.51. SchedUtils suite

Linux scheduler util library

class resources.libraries.python.SchedUtils.SchedUtils

Bases: object

General class for any linux scheduler related methods/functions.

static set_proc_scheduling_other(node, pid)

Set normal scheduling of a process to SCHED_OTHER for specified PID.

Parameters
  • node (dict) – Node where to apply scheduling changes.

  • pid (int) – Process ID.

Raises
  • ValueError – Parameters out of allowed ranges.

  • RuntimeError – Failed to set policy for PID.

static set_proc_scheduling_rr(node, pid, priority=1)

Set real-time scheduling of a process to SCHED_RR with priority for specified PID.

Parameters
  • node (dict) – Node where to apply scheduling changes.

  • pid (int) – Process ID.

  • priority (int) – Realtime priority in range 1-99. Default is 1.

Raises
  • ValueError – Parameters out of allowed ranges.

  • RuntimeError – Failed to set policy for PID.

static set_vpp_scheduling_rr(node)

Set real-time scheduling attributes of VPP worker threads to SCHED_RR with priority 1.

Parameters

node (dict) – DUT node with running VPP.

Raises

RuntimeError – Failed to retrieve PID for VPP worker threads.

2.52. SetupFramework suite

This module exists to provide setup utilities for the framework on topology nodes. All tasks required to be run before the actual tests are started is supposed to end up here.

TODO: Figure out how to export JSON from SSH outside main Robot thread.

class resources.libraries.python.SetupFramework.SetupFramework

Bases: object

Setup suite run on topology nodes.

Many VAT/CLI based tests need the scripts at remote hosts before executing them. This class packs the whole testing directory and copies it over to all nodes in topology under /tmp/

static setup_framework(nodes)

Pack the whole directory and extract in temp on each node.

Parameters

nodes (dict) – Topology nodes.

Raises

RuntimeError – If setup framework failed.

2.53. SysctlUtil suite

Linux sysctl library.

class resources.libraries.python.SysctlUtil.SysctlUtil

Bases: object

Class contains methods for getting or setting sysctl settings.

static get_sysctl_value(node, key)

Get sysctl key.

Parameters
  • node (dict) – Node in the topology.

  • key (str) – Key that will be set.

static set_sysctl_value(node, key, value)

Set sysctl key to specific value.

Parameters
  • node (dict) – Node in the topology.

  • key (str) – Key that will be set.

  • value (str) – Value to set.

2.54. TGSetup suite

TG Setup library.

class resources.libraries.python.TGSetup.TGSetup

Bases: object

TG setup before test.

static all_tgs_set_interface_default_driver(nodes)

Setup interfaces default driver for all TGs in given topology.

Parameters

nodes (dict) – Nodes in topology.

2.55. Tap suite

Tap utilities library.

class resources.libraries.python.Tap.Tap

Bases: object

Tap utilities.

static add_tap_interface(node, tap_name, mac=None, host_namespace=None, num_rx_queues=1, rxq_size=0, txq_size=0, tap_feature_mask=0)

Add tap interface with name and optionally with MAC.

Parameters
  • node (dict) – Node to add tap on.

  • tap_name (str) – Tap interface name for linux tap.

  • mac (str) – Optional MAC address for VPP tap.

  • host_namespace (str) – Namespace.

  • num_rx_queues (int) – Number of RX queues.

  • rxq_size (int) – Size of RXQ (0 = Default API; 256 = Default VPP).

  • txq_size (int) – Size of TXQ (0 = Default API; 256 = Default VPP).

  • tap_feature_mask (int) – Mask of tap features to be enabled.

Returns

Returns a interface index.

Return type

int

static tap_dump(node, name=None)

Get all TAP interface data from the given node, or data about a specific TAP interface.

Parameters
  • node (dict) – VPP node to get data from.

  • name (str) – Optional name of a specific TAP interface.

Returns

Dictionary of information about a specific TAP interface, or a List of dictionaries containing all TAP data for the given node.

Return type

dict or list

static vpp_get_tap_dev_name(node, host_if_name)

Get VPP tap interface name from hardware interfaces dump.

Parameters
  • node (dict) – DUT node.

  • host_if_name (str) – Tap host interface name.

Returns

VPP tap interface dev_name.

Return type

str

static vpp_get_tap_interface_mac(node, interface_name)

Get tap interface MAC address from interfaces dump.

Parameters
  • node (dict) – DUT node.

  • interface_name (str) – Tap interface name.

Returns

Tap interface MAC address.

Return type

str

class resources.libraries.python.Tap.TapFeatureMask

Bases: object

Tap features utilities

static create_tap_feature_mask(**kwargs)

Create tap feature mask with feature bits set according to kwargs. :param kwargs: Key-value pairs of feature names and it’s state :type kwargs: dict

static is_feature_enabled(tap_feature_mask, tap_feature_flag)

Checks if concrete tap feature is enabled within tap_feature_mask :param tap_feature_mask: Mask of enabled tap features :param tap_feature_flag: Checked tap feature :type tap_feature_mask: int :type tap_feature_flag: TapFeaturesFlags

class resources.libraries.python.Tap.TapFeaturesFlags(value)

Bases: enum.IntEnum

TAP Features Flags.

TAP_API_FLAG_ATTACH = 8
TAP_API_FLAG_CSUM_OFFLOAD = 2
TAP_API_FLAG_GRO_COALESCE = 32
TAP_API_FLAG_GSO = 1
TAP_API_FLAG_IN_ORDER = 128
TAP_API_FLAG_PACKED = 64
TAP_API_FLAG_PERSIST = 4
TAP_API_FLAG_TUN = 16

2.56. TelemetryUtil suite

Telemetry utility.

class resources.libraries.python.TelemetryUtil.TelemetryUtil

Bases: object

Class contains methods for telemetry utility.

static perf_stat(node, cpu_list=None, duration=1)

Get perf stat read for duration.

Parameters
  • node (dict) – Node in the topology.

  • cpu_list (str) – CPU List as a string separated by comma.

  • duration (int) – Measure time in seconds.

static perf_stat_on_all_duts(nodes, cpu_list=None, duration=1)

Get perf stat read for duration on all DUTs.

Parameters
  • nodes (dict) – Nodes in the topology.

  • cpu_list (str) – CPU List.

  • duration (int) – Measure time in seconds.

static run_telemetry(node, profile, hook=None)

Get telemetry stat read for duration.

Parameters
  • node (dict) – Node in the topology.

  • profile (str) – Telemetry configuration profile.

  • hook (str) – Process ID or socket path (optional).

static run_telemetry_on_all_duts(nodes, profile)

Get telemetry stat read on all DUTs.

Parameters
  • nodes (dict) – Nodes in the topology.

  • profile (str) – Telemetry configuration profile.

  • hooks (dict) – Dict of Process IDs or socket paths (optional).

2.57. TestConfig suite

Special test configurations library.

class resources.libraries.python.TestConfig.TestConfig

Bases: object

Contains special test configurations implemented in python for faster execution.

static vpp_create_multiple_vxlan_ipv4_tunnels(node, node_vxlan_if, node_vlan_if, op_node, op_node_if, n_tunnels, vni_start, src_ip_start, dst_ip_start, ip_step, bd_id_start)

Create multiple VXLAN tunnel interfaces and VLAN sub-interfaces on VPP node.

Put each pair of VXLAN tunnel interface and VLAN sub-interface to separate bridge-domain.

Parameters
  • node (dict) – VPP node to create VXLAN tunnel interfaces.

  • node_vxlan_if (str) – VPP node interface key to create VXLAN tunnel interfaces.

  • node_vlan_if (str) – VPP node interface key to create VLAN sub-interface.

  • op_node (dict) – Opposite VPP node for VXLAN tunnel interfaces.

  • op_node_if (str) – Opposite VPP node interface key for VXLAN tunnel interfaces.

  • n_tunnels (int) – Number of tunnel interfaces to create.

  • vni_start (int) – VNI start ID.

  • src_ip_start (str) – VXLAN tunnel source IP address start.

  • dst_ip_start (str) – VXLAN tunnel destination IP address start.

  • ip_step (int) – IP address incremental step.

  • bd_id_start (int) – Bridge-domain ID start.

static vpp_create_vxlan_and_vlan_interfaces(node, node_vxlan_if, node_vlan_if, vxlan_count, vni_start, src_ip_start, dst_ip_start, ip_step)

Configure IPs, create VXLAN interfaces and VLAN sub-interfaces on VPP node.

Parameters
  • node (dict) – VPP node.

  • node_vxlan_if (str) – VPP node interface key to create VXLAN tunnel interfaces.

  • node_vlan_if (str) – VPP node interface key to create VLAN sub-interface.

  • vxlan_count (int) – Number of tunnel interfaces to create.

  • vni_start (int) – VNI start ID.

  • src_ip_start (str) – VXLAN tunnel source IP address start.

  • dst_ip_start (str) – VXLAN tunnel destination IP address start.

  • ip_step (int) – IP address incremental step.

Returns

Number of created VXLAN interfaces.

Return type

int

static vpp_put_vxlan_and_vlan_interfaces_to_bridge_domain(node, node_vxlan_if, vxlan_count, op_node, op_node_if, dst_ip_start, ip_step, bd_id_start)

Configure ARPs and routes for VXLAN interfaces and put each pair of VXLAN tunnel interface and VLAN sub-interface to separate bridge-domain.

Parameters
  • node (dict) – VPP node.

  • node_vxlan_if (str) – VPP node interface key where VXLAN tunnel interfaces have been created.

  • vxlan_count (int) – Number of tunnel interfaces.

  • op_node (dict) – Opposite VPP node for VXLAN tunnel interfaces.

  • op_node_if – Opposite VPP node interface key for VXLAN tunnel interfaces.

  • dst_ip_start (str) – VXLAN tunnel destination IP address start.

  • ip_step (int) – IP address incremental step.

  • bd_id_start (int) – Bridge-domain ID start.

static vpp_put_vxlan_and_vlan_interfaces_up(node, vxlan_count, node_vlan_if)

Update topology with VXLAN interfaces and VLAN sub-interfaces data and put interfaces up.

Parameters
  • node (dict) – VPP node.

  • vxlan_count (int) – Number of tunnel interfaces.

  • node_vlan_if (str) – VPP node interface key where VLAN sub-interfaces have been created.

2.58. Trace suite

Packet trace library.

class resources.libraries.python.Trace.Trace

Bases: object

This class provides methods to manipulate the VPP packet trace.

static clear_packet_trace_on_all_duts(nodes)

Clear VPP packet trace on all duts.

Parameters

nodes (dict) – Nodes where the packet trace will be cleared.

static clear_packet_trace_on_dut(node)

Clear VPP packet trace on dut.

Parameters

node (dict) – Node where the packet trace will be cleared.

static show_packet_trace_on_all_duts(nodes, maximum=None)

Show VPP packet trace.

Parameters
  • nodes (dict) – Nodes from which the packet trace will be displayed.

  • maximum (int) – Maximum number of packet traces to be displayed.

2.59. TrafficGenerator suite

Performance testing traffic generator library.

class resources.libraries.python.TrafficGenerator.OptimizedSearch

Bases: object

Class to be imported as Robot Library, containing search keywords.

Aside of setting up measurer and forwarding arguments, the main business is to translate min/max rate from unidir to aggregated.

Setup initialized TG, perform optimized search, return intervals.

If transaction_scale is nonzero, all init and non-init trial durations are set to 1.0 (as they do not affect the real trial duration) and zero intermediate phases are used. This way no re-measurement happens. Warmup has to be handled via resetter or ramp-up mechanisms.

Parameters
  • frame_size (str or int) – Frame size identifier or value [B].

  • traffic_profile (str) – Module name as a traffic profile identifier. See GPL/traffic_profiles/trex for implemented modules.

  • minimum_transmit_rate (float) – Minimal load in transactions per second.

  • maximum_transmit_rate (float) – Maximal load in transactions per second.

  • packet_loss_ratio (float) – Ratio of packets lost, for PDR [1].

  • final_relative_width (float) – Final lower bound transmit rate cannot be more distant that this multiple of upper bound [1].

  • final_trial_duration (float) – Trial duration for the final phase [s].

  • initial_trial_duration (float) – Trial duration for the initial phase and also for the first intermediate phase [s].

  • number_of_intermediate_phases (int) – Number of intermediate phases to perform before the final phase [1].

  • timeout (float) – The search will fail itself when not finished before this overall time [s].

  • ppta (int) – Packets per transaction, aggregated over directions. Needed for udp_pps which does not have a good transaction counter, so we need to compute expected number of packets. Default: 1.

  • resetter (Optional[Callable[[], None]]) – Callable to reset DUT state for repeated trials.

  • traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2

  • transaction_duration (float) – Total expected time to close transaction.

  • transaction_scale (int) – Number of transactions to perform. 0 (default) means unlimited.

  • transaction_type (str) – An identifier specifying which counters and formulas to use when computing attempted and failed transactions. Default: “packet”.

  • use_latency (bool) – Whether to measure latency during the trial. Default: False.

  • ramp_up_rate (float) – Rate to use in ramp-up trials [pps].

  • ramp_up_duration (float) – Duration of ramp-up trials [s].

  • state_timeout (float) – Time of life of DUT state [s].

  • expansion_coefficient (float) – In external search multiply width by this.

Returns

Structure containing narrowed down NDR and PDR intervals and their measurements.

Return type

List[Receiverateinterval]

Raises

RuntimeError – If total duration is larger than timeout.

Setup initialized TG, perform soak search, return avg and stdev.

Parameters
  • frame_size (str or int) – Frame size identifier or value [B].

  • traffic_profile (str) – Module name as a traffic profile identifier. See GPL/traffic_profiles/trex for implemented modules.

  • minimum_transmit_rate (float) – Minimal load in transactions per second.

  • maximum_transmit_rate (float) – Maximal load in transactions per second.

  • plr_target (float) – Ratio of packets lost to achieve [1].

  • tdpt – Trial duration per trial. The algorithm linearly increases trial duration with trial number, this is the increment between succesive trials, in seconds.

  • initial_count (int) – Offset to apply before the first trial. For example initial_count=50 makes first trial to be 51*tdpt long. This is needed because initial “search” phase of integrator takes significant time even without any trial results.

  • timeout (float) – The search will stop after this overall time [s].

  • ppta (int) – Packets per transaction, aggregated over directions. Needed for udp_pps which does not have a good transaction counter, so we need to compute expected number of packets. Default: 1.

  • resetter (Optional[Callable[[], None]]) – Callable to reset DUT state for repeated trials.

  • trace_enabled (bool) – True if trace enabled else False. This is very verbose tracing on numeric computations, do not use in production. Default: False

  • traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2

  • transaction_duration (float) – Total expected time to close transaction.

  • transaction_scale (int) – Number of transactions to perform. 0 (default) means unlimited.

  • transaction_type (str) – An identifier specifying which counters and formulas to use when computing attempted and failed transactions. Default: “packet”.

  • use_latency (bool) – Whether to measure latency during the trial. Default: False.

  • ramp_up_rate (float) – Rate to use in ramp-up trials [pps].

  • ramp_up_duration (float) – Duration of ramp-up trials [s].

  • state_timeout (float) – Time of life of DUT state [s].

Returns

Average and stdev of estimated aggregated rate giving PLR.

Return type

2-tuple of float

class resources.libraries.python.TrafficGenerator.TGDropRateSearchImpl

Bases: resources.libraries.python.DropRateSearch.DropRateSearch

Drop Rate Search implementation.

get_latency()

Returns min/avg/max latency.

Returns

Latency stats.

Return type

list

measure_loss(rate, frame_size, loss_acceptance, loss_acceptance_type, traffic_profile)

Runs the traffic and evaluate the measured results.

Parameters
  • rate (float) – Offered traffic load.

  • frame_size (str) – Size of frame.

  • loss_acceptance (float) – Permitted drop ratio or frames count.

  • loss_acceptance_type (LossAcceptanceType) – Type of permitted loss.

  • traffic_profile (str) – Module name as a traffic profile identifier. See GPL/traffic_profiles/trex for implemented modules.

Returns

Drop threshold exceeded? (True/False)

Return type

bool

Raises
  • NotImplementedError – If TG is not supported.

  • RuntimeError – If TG is not specified.

class resources.libraries.python.TrafficGenerator.TrafficGenerator

Bases: resources.libraries.python.MLRsearch.AbstractMeasurer.AbstractMeasurer

Traffic Generator.

ROBOT_LIBRARY_SCOPE = 'TEST SUITE'
check_mode(expected_mode)

Check TG mode.

Parameters

expected_mode (object) – Expected traffic generator mode.

Raises

RuntimeError – In case of unexpected TG mode.

fail_if_no_traffic_forwarded()

Fail if no traffic forwarded.

TODO: Check number of passed transactions instead.

Returns

nothing

Raises

Exception – If no traffic forwarded.

get_approximated_rate()

Return approximated rate computed as ratio of transmitted packets over duration of trial.

Returns

Approximated rate.

Return type

str

get_l7_data()

Return L7 data.

Returns

Number of received packets.

Return type

dict

get_latency_int()

Return rounded min/avg/max latency.

Returns

Latency stats.

Return type

list

get_loss()

Return number of lost packets.

Returns

Number of lost packets.

Return type

str

get_received()

Return number of received packets.

Returns

Number of received packets.

Return type

str

get_sent()

Return number of sent packets.

Returns

Number of sent packets.

Return type

str

static get_tg_type(tg_node)

Log and return the installed traffic generator type.

Parameters

tg_node (dict) – Node from topology file.

Returns

Traffic generator type string.

Return type

str

Raises

RuntimeError – If command returns nonzero return code.

static get_tg_version(tg_node)

Log and return the installed traffic generator version.

Parameters

tg_node (dict) – Node from topology file.

Returns

Traffic generator version string.

Return type

str

Raises

RuntimeError – If command returns nonzero return code.

initialize_traffic_generator(tg_node, tg_if1, tg_if2, tg_if1_adj_node, tg_if1_adj_if, tg_if2_adj_node, tg_if2_adj_if, osi_layer, tg_if1_dst_mac=None, tg_if2_dst_mac=None)

TG initialization.

TODO: Document why do we need (and how do we use) _ifaces_reordered.

Parameters
  • tg_node (dict) – Traffic generator node.

  • tg_if1 (str) – TG - name of first interface.

  • tg_if2 (str) – TG - name of second interface.

  • tg_if1_adj_node (dict) – TG if1 adjecent node.

  • tg_if1_adj_if (str) – TG if1 adjecent interface.

  • tg_if2_adj_node (dict) – TG if2 adjecent node.

  • tg_if2_adj_if (str) – TG if2 adjecent interface.

  • osi_layer (str) – ‘L2’, ‘L3’ or ‘L7’ - OSI Layer testing type.

  • tg_if1_dst_mac (str) – Interface 1 destination MAC address.

  • tg_if2_dst_mac (str) – Interface 2 destination MAC address.

Returns

nothing

Raises

RuntimeError – In case of issue during initialization.

static is_trex_running(node)

Check if T-Rex is running using pidof.

Parameters

node (dict) – Traffic generator node.

Returns

True if T-Rex is running otherwise False.

Return type

bool

measure(duration, transmit_rate)

Run trial measurement, parse and return results.

The input rate is for transactions. Stateles bidirectional traffic is understood as sequence of (asynchronous) transactions, two packets each.

The result units depend on test type, generally the count either transactions or packets (aggregated over directions).

Optionally, this method sleeps if measurement finished before the time specified as duration.

Parameters
  • duration (float) – Trial duration [s].

  • transmit_rate (float) – Target rate in transactions per second.

Returns

Structure containing the result of the measurement.

Return type

ReceiveRateMeasurement

Raises
  • RuntimeError – If TG is not set or if node is not TG or if subtype is not specified.

  • NotImplementedError – If TG is not supported.

no_traffic_loss_occurred()

Fail if loss occurred in traffic run.

Returns

nothing

Raises

Exception – If loss occured.

property node

Getter.

Returns

Traffic generator node.

Return type

dict

partial_traffic_loss_accepted(loss_acceptance, loss_acceptance_type)

Fail if loss is higher then accepted in traffic run.

Parameters
  • loss_acceptance (float) – Permitted drop ratio or frames count.

  • loss_acceptance_type (LossAcceptanceType) – Type of permitted loss.

Returns

nothing

Raises

Exception – If loss is above acceptance criteria.

send_traffic_on_tg(duration, rate, frame_size, traffic_profile, async_call=False, ppta=1, traffic_directions=2, transaction_duration=0.0, transaction_scale=0, transaction_type='packet', duration_limit=0.0, use_latency=False, ramp_up_rate=None, ramp_up_duration=None, state_timeout=240.0, ramp_up_only=False)

Send traffic from all configured interfaces on TG.

In async mode, xstats is stored internally, to enable getting correct result when stopping the traffic. In both modes, stdout is returned, but _parse_traffic_results only works in sync output.

Note that traffic generator uses DPDK driver which might reorder port numbers based on wiring and PCI numbering. This method handles that, so argument values are invariant, but you can see swapped valued in debug logs.

When transaction_scale is specified, the duration value is ignored and the needed time is computed. For cases where this results in to too long measurement (e.g. teardown trial with small rate), duration_limit is applied (of non-zero), so the trial is stopped sooner.

Bidirectional STL profiles are treated as transactions with two packets.

The return value is None for async.

Parameters
  • duration (float) – Duration of test traffic generation in seconds.

  • rate (float) – Traffic rate in transactions per second.

  • frame_size (str) – Frame size (L2) in Bytes.

  • traffic_profile (str) – Module name as a traffic profile identifier. See GPL/traffic_profiles/trex for implemented modules.

  • async_call (bool) – Async mode.

  • ppta (int) – Packets per transaction, aggregated over directions. Needed for udp_pps which does not have a good transaction counter, so we need to compute expected number of packets. Default: 1.

  • traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2

  • transaction_duration (float) – Total expected time to close transaction.

  • transaction_scale (int) – Number of transactions to perform. 0 (default) means unlimited.

  • transaction_type (str) – An identifier specifying which counters and formulas to use when computing attempted and failed transactions. Default: “packet”.

  • duration_limit (float) – Zero or maximum limit for computed (or given) duration.

  • use_latency (bool) – Whether to measure latency during the trial. Default: False.

  • ramp_up_rate (float) – Rate to use in ramp-up trials [pps].

  • ramp_up_duration (float) – Duration of ramp-up trials [s].

  • state_timeout (float) – Time of life of DUT state [s].

  • ramp_up_only (bool) – If true, do not perform main trial measurement.

Returns

TG results.

Return type

ReceiveRateMeasurement or None

Raises

ValueError – If TG traffic profile is not supported.

set_rate_provider_defaults(frame_size, traffic_profile, ppta=1, resetter=None, traffic_directions=2, transaction_duration=0.0, transaction_scale=0, transaction_type='packet', duration_limit=0.0, negative_loss=True, sleep_till_duration=False, use_latency=False, ramp_up_rate=None, ramp_up_duration=None, state_timeout=240.0)

Store values accessed by measure().

Parameters
  • frame_size (str or int) – Frame size identifier or value [B].

  • traffic_profile (str) – Module name as a traffic profile identifier. See GPL/traffic_profiles/trex for implemented modules.

  • ppta (int) – Packets per transaction, aggregated over directions. Needed for udp_pps which does not have a good transaction counter, so we need to compute expected number of packets.