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'¶

SOCKCLI_PATH = '/run/vpp/cli.sock'¶

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(b_min, b_max, traffic_profile, skip_max_rate=False, skip_warmup=False)¶

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(start_rate, traffic_profile)¶

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(start_rate, traffic_profile)¶

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¶

IF_STATUS_API_FLAG_LINK_UP = 2¶

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

LINK_DUPLEX_API_FULL = 2¶

LINK_DUPLEX_API_HALF = 1¶

LINK_DUPLEX_API_UNKNOWN = 0¶

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):

Simple request / reply

One request with no arguments:

cmd = ‘show_version’ with PapiSocketExecutor(node) as papi_exec:

reply = papi_exec.add(cmd).get_reply(err_msg)
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)

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.

static perform_optimized_ndrpdr_search(frame_size, traffic_profile, minimum_transmit_rate, maximum_transmit_rate, packet_loss_ratio=0.005, final_relative_width=0.005, final_trial_duration=30.0, initial_trial_duration=1.0, number_of_intermediate_phases=2, timeout=1200.0, ppta=1, resetter=None, traffic_directions=2, transaction_duration=0.0, transaction_scale=0, transaction_type='packet', use_latency=False, ramp_up_rate=None, ramp_up_duration=None, state_timeout=240.0, expansion_coefficient=4.0)¶

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.

static perform_soak_search(frame_size, traffic_profile, minimum_transmit_rate, maximum_transmit_rate, plr_target=1e-07, tdpt=0.1, initial_count=50, timeout=7200.0, ppta=1, resetter=None, trace_enabled=False, traffic_directions=2, transaction_duration=0.0, transaction_scale=0, transaction_type='packet', use_latency=False, ramp_up_rate=None, ramp_up_duration=None, state_timeout=240.0)¶

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. Default: 1.
resetter (Optional[Callable[[], None]]) – Callable to reset DUT state for repeated trials.
traffic_directions (int) – Traffic from packet counting point of view 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”. TODO: Does this also specify parsing for the measured duration?
duration_limit (float) – Zero or maximum limit for computed (or given) duration.
negative_loss (bool) – If false, negative loss is reported as zero loss.
sleep_till_duration (bool) – If true and measurement returned faster, sleep until it matches duration. Needed for PLRsearch.
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].

static startup_trex(tg_node, osi_layer, subtype=None)¶

Startup sequence for the TRex traffic generator.

Parameters

tg_node (dict) – Traffic generator node.
osi_layer (str) – ‘L2’, ‘L3’ or ‘L7’ - OSI Layer testing type.
subtype (NodeSubTypeTG) – Traffic generator sub-type.

Raises

RuntimeError – If T-Rex startup failed.
ValueError – If OSI layer is not supported.

stop_traffic_on_tg()¶

Stop all traffic on TG.

Returns: Structure containing the result of the measurement.
Return type: ReceiveRateMeasurement
Raises: ValueError – If TG traffic profile is not supported.

static teardown_traffic_generator(node)¶

TG teardown.

Parameters: node (dict) – Traffic generator node.
Returns: nothing
Raises: RuntimeError – If node type is not a TG, or if T-Rex teardown fails.

trex_astf_start_remote_exec(duration, multiplier, async_call=False)¶

Execute T-Rex ASTF script on remote node over ssh to start running traffic.

In sync mode, measurement results are stored internally. In async mode, initial data including xstats are stored internally.

This method contains the logic to compute duration as maximum time if transaction_scale is nonzero. The transaction_scale argument defines (limits) how many transactions will be started in total. As that amount of transaction can take considerable time (sometimes due to explicit delays in the profile), the real time a trial needs to finish is computed here. For now, in that case the duration argument is ignored, assuming it comes from ASTF-unaware search algorithm. The overall time a single transaction needs is given in parameter transaction_duration, it includes both explicit delays and implicit time it takes to transfer data (or whatever the transaction does).

Currently it is observed TRex does not start the ASTF traffic immediately, an ad-hoc constant is added to the computed duration to compensate for that.

If transaction_scale is zero, duration is not recomputed. It is assumed the subsequent result parsing gets the real duration if the traffic stops sooner for any reason.

Currently, it is assumed traffic profile defines a single transaction. To avoid heavy logic here, the input rate is expected to be in transactions per second, as that directly translates to TRex multiplier, (assuming the profile does not override the default cps value of one).

Parameters

duration (float) – Time expressed in seconds for how long to send traffic.
multiplier (int) – Traffic rate in transactions per second.
async_call (bool) – If enabled then don’t wait for all incoming traffic.

Raises

RuntimeError – In case of T-Rex driver issue.

trex_astf_stop_remote_exec(node)¶

Execute T-Rex ASTF script on remote node over ssh to stop running traffic.

Internal state is updated with measurement results.

Parameters: node (dict) – T-Rex generator node.
Raises: RuntimeError – If stop traffic script fails.

trex_stl_start_remote_exec(duration, rate, async_call=False)¶

Execute T-Rex STL script on remote node over ssh to start running traffic.

In sync mode, measurement results are stored internally. In async mode, initial data including xstats are stored internally.

Mode-unaware code (e.g. in search algorithms) works with transactions. To keep the logic simple, multiplier is set to that value. As bidirectional traffic profiles send packets in both directions, they are treated as transactions with two packets (one per direction).

Parameters

duration (float) – Time expressed in seconds for how long to send traffic.
rate (str) – Traffic rate in transactions per second.
async_call (bool) – If enabled then don’t wait for all incoming traffic.

Raises

RuntimeError – In case of T-Rex driver issue.

trex_stl_stop_remote_exec(node)¶

Execute T-Rex STL script on remote node over ssh to stop running traffic.

Internal state is updated with measurement results.

Parameters: node (dict) – T-Rex generator node.
Raises: RuntimeError – If stop traffic script fails.

2.60. TrafficScriptExecutor suite¶

Traffic script executor library.

class resources.libraries.python.TrafficScriptExecutor.TrafficScriptExecutor¶

Bases: object

Traffic script executor utilities.

static run_traffic_script_on_node(script_file_name, node, script_args, timeout=60)¶

Run traffic script on the TG node.

Parameters

script_file_name (str) – Traffic script name.
node (dict) – Node to run traffic script on.
script_args (str) – Traffic scripts arguments.
timeout (int) – Timeout (optional).

Raises

RuntimeError – ICMP echo Rx timeout.
RuntimeError – DHCP REQUEST Rx timeout.
RuntimeError – DHCP DISCOVER Rx timeout.
RuntimeError – TCP/UDP Rx timeout.
RuntimeError – ARP reply timeout.
RuntimeError – Traffic script execution failed.

static traffic_script_gen_arg(rx_if, tx_if, src_mac, dst_mac, src_ip, dst_ip)¶

Generate traffic script basic arguments string.

Parameters

rx_if (str) – Interface that receives traffic.
tx_if (str) – Interface that sends traffic.
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

Traffic script arguments string.

Return type

str

2.61. VPPUtil suite¶

VPP util library.

class resources.libraries.python.VPPUtil.VPPUtil¶

Bases: object

General class for any VPP related methods/functions.

static adjust_privileges(node)¶

Adjust privileges to control VPP without sudo.

Parameters: node (dict) – Topology node.

static restart_vpp_service(node, node_key=None)¶

Restart VPP service on the specified topology node.

Disconnect possibly connected PAPI executor.

Parameters

node (dict) – Topology node.
node_key (str) – Topology node key.

static restart_vpp_service_on_all_duts(nodes)¶

Restart VPP service on all DUT nodes.

Parameters: nodes (dict) – Topology nodes.

static show_event_logger(node)¶

Show event logger on the specified topology node.

Parameters: node (dict) – Topology node.

static show_event_logger_on_all_duts(nodes)¶

Show event logger on all DUTs in the given topology.

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

static show_log(node)¶

Show logging on the specified topology node.

Parameters: node (dict) – Topology node.

static show_log_on_all_duts(nodes)¶

Show logging on all DUTs in the given topology.

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

static show_vpp_settings(node, *additional_cmds)¶

Print default VPP settings. In case others are needed, can be accepted as next parameters (each setting one parameter), preferably in form of a string.

Parameters

node (dict) – VPP node.
additional_cmds (tuple) – Additional commands that the vpp should print settings for.

static show_vpp_version_on_all_duts(nodes)¶

Show VPP version verbose on all DUTs.

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

static stop_vpp_service(node, node_key=None)¶

Stop VPP service on the specified topology node.

Disconnect possibly connected PAPI executor.

Parameters

node (dict) – Topology node.
node_key (str) – Topology node key.

static stop_vpp_service_on_all_duts(nodes)¶

Stop VPP service on all DUT nodes.

Parameters: nodes (dict) – Topology nodes.

static verify_vpp(node)¶

Verify that VPP is installed and started on the specified topology node. Adjust privileges so user can connect without sudo.

Parameters: node (dict) – Topology node.
Raises: RuntimeError – If VPP service fails to start.

static verify_vpp_installed(node)¶

Verify that VPP is installed on the specified topology node.

Parameters: node (dict) – Topology node.

static verify_vpp_on_all_duts(nodes)¶

Verify that VPP is installed and started on all DUT nodes.

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

static verify_vpp_started(node)¶

Verify that VPP is started on the specified topology node.

Parameters: node (dict) – Topology node.

static vpp_add_graph_node_next(node, graph_node_name, graph_next_name)¶

Set the next node for a given node.

Parameters

node (dict) – Node to run command on.
graph_node_name (str) – Graph node to add the next node on.
graph_next_name (str) – Graph node to add as the next node.

Returns

The index of the next graph node.

Return type

int

static vpp_enable_elog_traces(node)¶

Enable API/CLI/Barrier traces on the specified topology node.

Parameters: node (dict) – Topology node.

static vpp_enable_elog_traces_on_all_duts(nodes)¶

Enable API/CLI/Barrier traces on all DUTs in the given topology.

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

static vpp_enable_traces_on_all_duts(nodes, fail_on_error=False)¶

Enable vpp packet traces on all DUTs in the given topology.

Parameters

nodes (dict) – Nodes in the topology.
fail_on_error (bool) – If True, keyword fails if an error occurs, otherwise passes.

static vpp_enable_traces_on_dut(node, fail_on_error=False)¶

Enable vpp packet traces on the DUT node.

Parameters

node (dict) – DUT node to set up.
fail_on_error (bool) – If True, keyword fails if an error occurs, otherwise passes.

static vpp_show_interfaces(node)¶

Run “show interface” CLI command.

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

static vpp_show_threads(node)¶

Show VPP threads on node.

Parameters: node (dict) – Node to run command on.
Returns: VPP thread data.
Return type: list

static vpp_show_version(node, remote_vpp_socket='/run/vpp/api.sock', log=True)¶

Run “show_version” PAPI command.

Socket is configurable, so VPP inside container can be accessed. The result is exported to JSON UTI output as “dut-version”.

Parameters

node (dict) – Node to run command on.
remote_vpp_socket (str) – Path to remote socket to target VPP.
log (bool) – If true, show the result in Robot log.

Returns

VPP version.

Return type

str

Raises

RuntimeError – If PAPI connection fails.
AssertionError – If PAPI retcode is nonzero.

2.62. VatExecutor suite¶

VAT executor library.

class resources.libraries.python.VatExecutor.VatExecutor¶

Bases: object

Contains methods for executing VAT commands on DUTs.

static cmd_from_template(node, vat_template_file, json_param=True, **vat_args)¶

Execute VAT script on specified node. This method supports script templates with parameters.

Parameters

node – Node in topology on witch the script is executed.
vat_template_file – Template file of VAT script.
json_param – Require JSON mode.
vat_args – Arguments to the template file.

Returns

List of JSON objects returned by VAT.

execute_script(vat_name, node, timeout=120, json_out=True, copy_on_execute=False, history=True)¶

Execute VAT script on remote node, and store the result. There is an option to copy script from local host to remote host before execution. Path is defined automatically.

Parameters

vat_name (str) – Name of the vat script file. Only the file name of the script is required, the resources path is prepended automatically.
node (dict) – Node to execute the VAT script on.
timeout (int) – Seconds to allow the script to run.
json_out (bool) – Require JSON output.
copy_on_execute (bool) – If true, copy the file from local host to remote before executing.
history (bool) – If true, add command to history.

Raises

SSHException – If cannot open connection for VAT.
SSHTimeout – If VAT execution is timed out.
RuntimeError – If VAT script execution fails.

execute_script_json_out(vat_name, node, timeout=120)¶

Pass all arguments to ‘execute_script’ method, then cleanup returned json output.

Parameters

vat_name (str) – Name of the vat script file. Only the file name of the script is required, the resources path is prepended automatically.
node (dict) – Node to execute the VAT script on.
timeout (int) – Seconds to allow the script to run.

get_script_stderr()¶: Returns value of stderr from last executed script.

get_script_stdout()¶: Returns value of stdout from last executed script.

script_should_have_failed()¶: Read return code from last executed script and raise exception if the script didn’t fail.

script_should_have_passed()¶: Read return code from last executed script and raise exception if the script failed.

write_and_execute_script(node, tmp_fn, commands, timeout=300, json_out=False)¶

Write VAT commands to the script, copy it to node and execute it.

Parameters

node (dict) – VPP node.
tmp_fn (str) – Path to temporary file script.
commands (list) – VAT command list.
timeout (int) – Seconds to allow the script to run.
json_out (bool) – Require JSON output.

2.63. VatJsonUtil suite¶

Utilities to work with JSON data format from VAT.

class resources.libraries.python.VatJsonUtil.VatJsonUtil¶

Bases: object

Utilities to work with JSON data format from VAT.

static get_interface_mac_from_json(interface_dump_json, sw_if_index)¶

Get interface MAC address from given JSON output by sw_if_index.

Parameters

interface_dump_json (str) – JSON output from dump_interface_list VAT command.
sw_if_index (int) – SW interface index.

Returns

Interface MAC address.

Return type

str

Raises

ValueError – If interface not found in interface_dump_json.

static get_interface_name_from_json(interface_dump_json, sw_if_index)¶

Get interface name from given JSON output by sw_if_index.

Parameters

interface_dump_json (str) – JSON output from dump_interface_list VAT command.
sw_if_index (int) – SW interface index.

Returns

Interface name.

Return type

str

Raises

ValueError – If interface not found in interface_dump_json.

static get_interface_sw_index_from_json(interface_dump_json, interface_name)¶

Get sw_if_index from given JSON output by interface name.

Parameters

interface_dump_json (str) – JSON output from dump_interface_list VAT command.
interface_name (str) – Interface name.

Returns

SW interface index.

Return type

int

Raises

ValueError – If interface not found in interface_dump_json.

static get_vpp_interface_by_mac(interfaces_list, mac_address)¶

Return interface dictionary from interface_list by MAC address.

Extracts interface dictionary from all of the interfaces in interfaces list parsed from JSON according to mac_address of the interface.

Parameters

interfaces_list (dict) – Interfaces parsed from JSON.
mac_address (str) – MAC address of interface we are looking for.

Returns

Interface from JSON.

Return type

dict

static update_vpp_interface_data_from_json(node, interface_dump_json)¶

Update vpp node data in node__DICT from JSON interface dump.

This method updates vpp interface names and sw if indexes according to interface MAC addresses found in interface_dump_json.

Parameters

node (dict) – Node dictionary.
interface_dump_json (str) – JSON output from dump_interface_list VAT command.

static verify_vat_retval(vat_out, exp_retval=0, err_msg='VAT cmd failed')¶

Verify return value of VAT command.

VAT command JSON output should be object (dict in python) or array. We are looking for something like this: { “retval”: 0 }. Verification is skipped if VAT output does not contain return value element or root elemet is array.

Parameters

vat_out (dict or list) – VAT command output in python representation of JSON.
exp_retval (int) – Expected return value (default 0).

Err_msg

Message to be displayed in case of error (optional).

Raises

RuntimeError – If VAT command return value is incorrect.

2.64. VhostUser suite¶

Vhost-user interfaces library.

class resources.libraries.python.VhostUser.VhostUser¶

Bases: object

Vhost-user interfaces L1 library.

static get_vhost_user_if_name_by_sock(node, socket)¶

Get Vhost-user interface name by socket.

Parameters

node (dict) – Node to get Vhost-user interface name on.
socket (str) – Vhost-user interface socket path.

Returns

Interface name or None if not found.

Return type

str

static get_vhost_user_mac_by_sw_index(node, sw_if_index)¶

Get Vhost-user l2_address for the given interface from actual interface dump.

Parameters

node (dict) – VPP node to get interface data from.
sw_if_index (str) – SW index of the specific interface.

Returns

l2_address of the given interface.

Return type

str

static show_vpp_vhost_on_all_duts(nodes)¶

Show Vhost-user on all DUTs.

Parameters: nodes (dict) – VPP nodes.

static vhost_user_affinity(node, pf_key, skip_cnt=0)¶

Set vhost-user affinity for the given node.

Parameters

node (dict) – Topology node.
pf_key (str) – Interface key to compute numa location.
skip_cnt (int) – Skip first “skip_cnt” CPUs.

static vhost_user_dump(node)¶

Get vhost-user data for the given node.

Parameters: node (dict) – VPP node to get interface data from.
Returns: List of dictionaries with all vhost-user interfaces.
Return type: list

static vpp_create_vhost_user_interface(node, socket, is_server=False, virtio_feature_mask=None)¶

Create Vhost-user interface on VPP node.

Parameters

node (dict) – Node to create Vhost-user interface on.
socket (str) – Vhost-user interface socket path.
is_server (bool) – Server side of connection. Default: False
virtio_feature_mask (int) – Mask of virtio features to be enabled.

Returns

SW interface index.

Return type

int

class resources.libraries.python.VhostUser.VirtioFeatureMask¶

Bases: object

Virtio features utilities

static create_virtio_feature_mask(**kwargs)¶: Create virtio 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(virtio_feature_mask, virtio_feature_flag)¶: Checks if concrete virtio feature is enabled within virtio_feature_mask :param virtio_feature_mask: Mask of enabled virtio features :param virtio_feature_flag: Checked virtio feature :type virtio_feature_mask: int :type virtio_feature_flag: VirtioFeaturesFlags

class resources.libraries.python.VhostUser.VirtioFeaturesFlags(value)¶

Bases: enum.IntEnum

Virtio Features Flags.

VIRTIO_F_API_ANY_LAYOUT = 27¶

VIRTIO_F_API_INDIRECT_DESC = 28¶

VIRTIO_NET_F_API_CSUM = 0¶

VIRTIO_NET_F_API_CTRL_VQ = 17¶

VIRTIO_NET_F_API_GSO = 6¶

VIRTIO_NET_F_API_GUEST_ANNOUNCE = 21¶

VIRTIO_NET_F_API_GUEST_CSUM = 1¶

VIRTIO_NET_F_API_GUEST_TSO4 = 7¶

VIRTIO_NET_F_API_GUEST_TSO6 = 8¶

VIRTIO_NET_F_API_GUEST_UFO = 10¶

VIRTIO_NET_F_API_HOST_TSO4 = 11¶

VIRTIO_NET_F_API_HOST_TSO6 = 12¶

VIRTIO_NET_F_API_HOST_UFO = 14¶

VIRTIO_NET_F_API_MQ = 22¶

VIRTIO_NET_F_API_MRG_RXBUF = 15¶

2.65. VppApiCrc suite¶

Module for keeping track of VPP API CRCs relied on by CSIT.

class resources.libraries.python.VppApiCrc.VppApiCrcChecker(directory, fail_on_mismatch=False)¶

Bases: object

Holder of data related to tracking VPP API CRCs.

Both message names and crc hexa strings are tracked as ordinary Python3 (unicode) string, so _str() is used when input is possibly bytes or otherwise not safe.

Each instance of this class starts with same default state, so make sure the calling libraries have appropriate robot library scope. For usual testing, it means “GLOBAL” scope.

check_api_name(api_name)¶

Fail if the api_name has no, or different from known CRC associated.

Print warning if options contain anything more than vat_help.

Do not fail if this particular failure has been already reported.

Intended use: Call during test (not in initialization), every time an API call is queued or response received.

Parameters: api_name (str or unicode) – VPP API message name to check.
Raises: RuntimeError – If no verified CRC for the api_name is found.

fail_on_mismatch¶: If True, mismatch leads to test failure, by raising exception. If False, the mismatch is logged, but the test is allowed to continue.

log_and_raise(exc_msg)¶

Log to console, on fail_on_mismatch also raise runtime exception.

Parameters: exc_msg (str) – The message to include in log or exception.
Raises: RuntimeError – With the message, if fail_on_mismatch.

report_initial_conflicts(report_missing=False)¶

Report issues discovered by _check_dir, if not done that already.

Intended use: Call once after init, at a time when throwing exception is convenient.

Optionally, report also missing messages. Missing reporting is disabled by default, because some messages come from plugins that might not be enabled at runtime.

After the report, clear _reported, so that test cases report them again, thus tracking which message is actually used (by which test).

Parameters: report_missing (bool) – Whether to raise on missing messages.
Raises: RuntimeError – If CRC mismatch or missing messages are detected, and fail_on_mismatch is True.

2.66. VppConfigGenerator suite¶

VPP Configuration File Generator library.

class resources.libraries.python.VppConfigGenerator.VppConfigGenerator¶

Bases: object

VPP Configuration File Generator.

add_api_segment_api_size(value)¶

Add API-SEGMENT api-size configuration.

Parameters: value (str) – API size.

add_api_segment_gid(value='vpp')¶

Add API-SEGMENT gid configuration.

Parameters: value (str) – Gid.

add_api_segment_global_size(value)¶

Add API-SEGMENT global-size configuration.

Parameters: value (str) – Global size.

add_api_trace()¶: Add API trace configuration.

add_buffers_default_data_size(value)¶

Increase buffers data-size allocated.

Parameters: value (int) – Buffers data-size allocated.

add_buffers_per_numa(value)¶

Increase number of buffers allocated.

Parameters: value (int) – Number of buffers allocated.

add_config_item(config, value, path)¶

Add startup configuration item.

Parameters

config (dict) – Startup configuration of node.
value (str) – Value to insert.
path (list) – Path where to insert item.

add_cpu_corelist_workers(value)¶

Add CPU corelist-workers configuration.

Parameters: value (str) – Corelist-workers option.

add_cpu_main_core(value)¶

Add CPU main core configuration.

Parameters: value (str) – Main core option.

add_default_hugepage_size(value='2M')¶

Add Default Hugepage Size configuration.

Parameters: value (str) – Hugepage size.

add_dpdk_cryptodev(count)¶

Add DPDK Crypto PCI device configuration.

Parameters: count (int) – Number of HW crypto devices to add.

add_dpdk_dev(*devices)¶

Add DPDK PCI device configuration.

Parameters: devices (tuple) – PCI device(s) (format xxxx:xx:xx.x)

add_dpdk_dev_default_rxd(value)¶

Add DPDK dev default rxd configuration.

Parameters: value (str) – Default number of rxds.

add_dpdk_dev_default_rxq(value)¶

Add DPDK dev default rxq configuration.

Parameters: value (str) – Default number of rxqs.

add_dpdk_dev_default_txd(value)¶

Add DPDK dev default txd configuration.

Parameters: value (str) – Default number of txds.

add_dpdk_dev_default_txq(value)¶

Add DPDK dev default txq configuration.

Parameters: value (str) – Default number of txqs.

add_dpdk_log_level(value)¶

Add DPDK log-level configuration.

Parameters: value (str) – Log level.

add_dpdk_max_simd_bitwidth(variant='')¶

Add DPDK max-simd-bitwidth configuration.

Parameters: value (str) – Graph node variant default value.

add_dpdk_no_multi_seg()¶: Add DPDK no-multi-seg configuration.

add_dpdk_no_pci()¶: Add DPDK no-pci.

add_dpdk_no_tx_checksum_offload()¶: Add DPDK no-tx-checksum-offload configuration.

add_dpdk_sw_cryptodev(sw_pmd_type, socket_id, count)¶

Add DPDK SW Crypto device configuration.

Parameters

sw_pmd_type (str) – Type of SW crypto device PMD to add.
socket_id (int) – Socket ID.
count (int) – Number of SW crypto devices to add.

add_dpdk_uio_driver(value=None)¶

Add DPDK uio-driver configuration.

Parameters: value (str) – DPDK uio-driver configuration. By default, driver will be loaded automatically from Topology file, still leaving option to manually override by parameter.

add_graph_node_variant(variant='')¶

Add default graph node variant.

Parameters: value (str) – Graph node variant default value.

add_ip6_hash_buckets(value)¶

Add IP6 hash buckets configuration.

Parameters: value (str) – Number of IP6 hash buckets.

add_ip6_heap_size(value)¶

Add IP6 heap-size configuration.

Parameters: value (str) – IP6 Heapsize amount.

add_main_heap_page_size(value)¶

Add Main Heap Page Size configuration.

Parameters: value (str) – Heap page size.

add_main_heap_size(value)¶

Add Main Heap Size configuration.

Parameters: value (str) – Amount of heap.

add_nat(value='deterministic')¶

Add NAT mode configuration.

Parameters: value (str) – NAT mode.

add_nat_max_translations_per_thread(value)¶

Add NAT max. translations per thread number configuration.

Parameters: value (str) – NAT mode.

add_nsim_poll_main_thread()¶: Add NSIM poll-main-thread configuration.

add_plugin(state, *plugins)¶

Add plugin section for specific plugin(s).

Parameters

state (str) – State of plugin [enable|disable].
plugins (list) – Plugin(s) to disable.

add_session_enable()¶: Add session enable.

add_session_event_queue_length(value)¶

Add session event queue length.

Parameters: value (int) – Session event queue length.

add_session_event_queues_memfd_segment()¶: Add session event queue memfd segment.

add_session_event_queues_segment_size(value)¶

Add session event queue length.

Parameters: value (str) – Session event queue segment size.

add_session_local_endpoints_table_buckets(value)¶

Add the number of local endpoints table buckets.

Parameters: value (int) – Number of local endpoints table buckets.

add_session_local_endpoints_table_memory(value)¶

Add the size of local endpoints table memory.

Parameters: value (str) – Size of local endpoints table memory.

add_session_preallocated_sessions(value)¶

Add the number of pre-allocated sessions.

Parameters: value (int) – Number of pre-allocated sessions.

add_session_v4_halfopen_table_buckets(value)¶

Add the number of v4 halfopen table buckets.

Parameters: value (int) – Number of v4 halfopen table buckets.

add_session_v4_halfopen_table_memory(value)¶

Add the size of v4 halfopen table memory.

Parameters: value (str) – Size of v4 halfopen table memory.

add_session_v4_session_table_buckets(value)¶

Add number of v4 session table buckets to the config.

Parameters: value (int) – Number of v4 session table buckets.

add_session_v4_session_table_memory(value)¶

Add the size of v4 session table memory.

Parameters: value (str) – Size of v4 session table memory.

add_socksvr(socket='/run/vpp/api.sock')¶: Add socksvr configuration.

add_spd_flow_cache_ipv4_outbound()¶: Add SPD flow cache for IP4 outbound traffic

add_statseg_page_size(value)¶

Add Stats Heap Page Size configuration.

Parameters: value (str) – Stats heapsize amount.

add_statseg_per_node_counters(value)¶

Add stats per-node-counters configuration.

Parameters: value (str) – “on” to switch the counters on.

add_statseg_size(value)¶

Add Stats Heap Size configuration.

Parameters: value (str) – Stats heapsize amount.

add_tcp_congestion_control_algorithm(value='cubic')¶

Add TCP congestion control algorithm.

Parameters: value (str) – The congestion control algorithm to use. Example: cubic

add_tcp_preallocated_connections(value)¶

Add TCP pre-allocated connections.

Parameters: value (int) – The number of pre-allocated connections.

add_tcp_preallocated_half_open_connections(value)¶

Add TCP pre-allocated half open connections.

Parameters: value (int) – The number of pre-allocated half open connections.

add_unix_cli_listen(value='/run/vpp/cli.sock')¶

Add UNIX cli-listen configuration.

Parameters: value (str) – CLI listen address and port or path to CLI socket.

add_unix_cli_no_pager()¶: Add UNIX cli-no-pager configuration.

add_unix_coredump()¶: Add UNIX full-coredump configuration.

add_unix_exec(value)¶: Add UNIX exec configuration.

add_unix_gid(value='vpp')¶

Add UNIX gid configuration.

Parameters: value (str) – Gid.

add_unix_log(value=None)¶

Add UNIX log configuration.

Parameters: value (str) – Log file.

add_unix_nodaemon()¶: Add UNIX nodaemon configuration.

apply_config(filename=None, verify_vpp=True)¶

Generate and write VPP startup configuration to file and restart VPP.

Use data from calls to this class to form a startup.conf file and replace /etc/vpp/startup.conf with it on topology node.

Parameters

filename (str) – Startup configuration file name.
verify_vpp (bool) – Verify VPP is running after restart.

dump_config(obj, level=- 1)¶

Dump the startup configuration in VPP config format.

Parameters

obj (Obj) – Python Object to print.
level (int) – Nested level for indentation.

Returns

nothing

get_config_str()¶

Get dumped startup configuration in VPP config format.

Returns: Startup configuration in VPP config format.
Return type: str

set_node(node, node_key=None)¶

Set DUT node.

Parameters

node (dict) – Node to store configuration on.
node_key (str) – Topology node key.

Raises

RuntimeError – If Node type is not DUT.

write_config(filename=None)¶

Generate and write VPP startup configuration to file.

Use data from calls to this class to form a startup.conf file and replace /etc/vpp/startup.conf with it on topology node.

Parameters: filename (str) – Startup configuration file name.

2.67. VppCounters suite¶

VPP counters utilities library.

class resources.libraries.python.VppCounters.VppCounters¶

Bases: object

VPP counters utilities.

static clear_statistics_on_all_duts(nodes)¶

Clear statistics on all DUTs.

Parameters: nodes (dict) – DUT nodes.

static clear_vpp_statistics(node)¶

Clear [errors, hardware] stats.

Parameters: node (dict) – VPP node.

static show_statistics_on_all_duts(nodes)¶

Show statistics on all DUTs.

Parameters: nodes (dict) – DUT nodes.

static show_vpp_statistics(node)¶

Show [errors, hardware] stats.

Parameters: node (dict) – VPP node.

static vpp_clear_errors(node)¶

Run “clear errors” CLI command.

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

static vpp_clear_errors_on_all_duts(nodes)¶

Clear VPP errors counters on all DUTs.

Parameters: nodes (dict) – VPP nodes.

static vpp_clear_hardware(node)¶

Run “clear hardware” CLI command.

Parameters: node (dict) – Node to run command on.
Returns: Verified data from PAPI response.
Return type: dict

static vpp_clear_hardware_on_all_duts(nodes)¶

Clear hardware on all DUTs.

Parameters: nodes (dict) – VPP nodes.

static vpp_clear_runtime(node)¶

Run “clear runtime” CLI command.

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

static vpp_clear_runtime_on_all_duts(nodes)¶

Run “clear runtime” CLI command on all DUTs.

Parameters: nodes (dict) – VPP nodes.

static vpp_show_errors(node)¶

Run “show errors” debug CLI command.

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

static vpp_show_errors_on_all_duts(nodes)¶

Show errors on all DUTs.

Parameters: nodes (dict) – VPP nodes.

static vpp_show_hardware(node)¶

Run “show hardware” debug CLI command.

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

static vpp_show_memory(node)¶

Run “show memory” debug CLI command.

Currently, every flag is hardcoded, giving the longest output.

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

static vpp_show_memory_on_all_duts(nodes)¶

Run “show memory” on all DUTs.

Parameters: nodes (dict) – VPP nodes.

static vpp_show_runtime(node, log_zeros=False)¶

Run “show runtime” CLI command.

Parameters

node (dict) – Node to run command on.
log_zeros (bool) – Log also items with zero values.

static vpp_show_runtime_on_all_duts(nodes)¶

Clear VPP runtime counters on all DUTs.

Parameters: nodes (dict) – VPP nodes.

2.68. WireGuardUtil suite¶

WireGuard utilities library.

class resources.libraries.python.WireGuardUtil.WireGuardUtil¶

Bases: object

This class defines the methods to set WireGuard.

static generate_wireguard_privatekey_and_pubkey()¶

Generate a pair of WireGuard Private key and Public key.

Returns: A pair of privatekey and publickey
Return type: x25519._X25519PublicKey object

static private_key_bytes(k)¶

Return the private key as byte.

Parameters: k – Generated private key.
Type: x25519._X25519PrivateKey object
Returns: Private key.
Return type: bytes

static public_key_bytes(k)¶

Return the public key as byte.

Parameters: k – Generated public key.
Type: x25519._X25519PublicKey object
Returns: Public key.
Return type: bytes

static vpp_wireguard_add_peer(node, interface, peer_pubkey, endpoint_ip, allowed_ips, n_allowed_ips, dst_port, keepalive_time)¶

Add a peer for WireGuard interface.

Parameters

node (dict) – VPP node to add config on.
interface (int) – WireGuard interface sw_if_index.
peer_pubkey (bytes) – Public key of wireguard interface peer.
endpoint_ip (str) – Peer source IPv4.
allowed_ips (list) – WireGuard interface allowed ips list.
n_allowed_ips (int) – Number of allowed ips.
dst_port (int) – WireGuard destination port.
time (keepaliva) – WireGuard persistent keepalive time.

static vpp_wireguard_create_interface(node, listen_port, wg_src, private_key)¶

Create WireGuard interface.

Parameters

node (dict) – VPP node to add config on.
listen_port (int) – WireGuard interface listen port.
wg_src (str) – WireGuard srouce IPv4.
private_key (bytes) – WireGuard interface private key

Returns

Wireguard interface sw_if_index.

Return type

int

static vpp_wireguard_create_tunnel_interface_on_duts(nodes, if1_key, if2_key, if1_ip_addr, if2_ip_addr, if1_mac_addr, if2_mac_addr, wg_if1_ip_addr, wg_if2_ip_addr, n_allowed_ips, port, keepalive_time, raddr_ip1, raddr_ip2)¶

Create WireGuard tunnel interfaces between two VPP nodes.

Parameters

nodes (dict) – VPP nodes to create tunnel interfaces.
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)
if1_ip_addr (str) – VPP node 1 interface IPv4/IPv6 address.
if2_ip_addr (str) – VPP node 2 / TG node (in case of 2-node topology) interface IPv4/IPv6 address.
if1_mac_addr (str) – VPP node1 interface mac address.
if2_mac_addr (str) – VPP node2 interface mac address.
wg_if1_ip_addr (str) – VPP node 1 WireGuard interface IPv4 address.
wg_if2_ip_addr (str) – VPP node 2 WireGuard interface IPv4 address.
allowed_ips (str) – WireGuard interface allowed ip list.
n_allowed_ips (int) – Number of allowed ips.
port (int) – WireGuard interface listen port or Peer interface destination port.
keepalive_time (int) – WireGuard persistent keepalive time.
raddr_ip1 (str) – Policy selector remote IPv4/IPv6 start address for the first tunnel in direction node1->node2.
raddr_ip2 (str) – Policy selector remote IPv4/IPv6 start address for the first tunnel in direction node2->node1.

2.69. ssh suite¶

Library for SSH connection management.

class resources.libraries.python.ssh.SSH¶

Bases: object

Contains methods for managing and using SSH connections.

connect(node, attempts=5)¶

Connect to node prior to running exec_command or scp.

If there already is a connection to the node, this method reuses it.

Parameters

node (dict) – Node in topology.
attempts (int) – Number of reconnect attempts.

Raises

IOError – If cannot connect to host.

disconnect(node=None)¶

Close SSH connection to the node.

Parameters: node (dict or None) – The node to disconnect from. None means last connected.

exec_command(cmd, timeout=10, log_stdout_err=True, export=True)¶

Execute SSH command on a new channel on the connected Node.

Parameters

cmd (str or OptionString) – Command to run on the Node.
timeout (int) – Maximal time in seconds to wait until the command is done. If set to None then wait forever.
log_stdout_err (bool) – If True, stdout and stderr are logged. stdout and stderr are logged also if the return code is not zero independently of the value of log_stdout_err.
export (bool) – If false, do not attempt JSON export. Needed for calls outside Robot (e.g. from reservation script).

Returns

return_code, stdout, stderr

Return type

tuple(int, str, str)

Raises

SSHTimeout – If command is not finished in timeout time.

exec_command_lxc(lxc_cmd, lxc_name, lxc_params='', sudo=True, timeout=30)¶

Execute command in LXC on a new SSH channel on the connected Node.

Parameters

lxc_cmd (str) – Command to be executed.
lxc_name (str) – LXC name.
lxc_params (str) – Additional parameters for LXC attach.
sudo (bool) – Run in privileged LXC mode. Default: privileged
timeout (int) – Timeout.

Returns

return_code, stdout, stderr

exec_command_sudo(cmd, cmd_input=None, timeout=30, log_stdout_err=True, export=True)¶

Execute SSH command with sudo on a new channel on the connected Node.

Parameters

cmd (str) – Command to be executed.
cmd_input (str) – Input redirected to the command.
timeout (int) – Timeout.
log_stdout_err (bool) – If True, stdout and stderr are logged.
export (bool) – If false, do not attempt JSON export. Needed for calls outside Robot (e.g. from reservation script).

Returns

return_code, stdout, stderr

Return type

tuple(int, str, str)

Example

>>> from ssh import SSH
>>> ssh = SSH()
>>> ssh.connect(node)
>>> # Execute command without input (sudo -S cmd)
>>> ssh.exec_command_sudo(u"ifconfig eth0 down")
>>> # Execute command with input (sudo -S cmd <<< 'input')
>>> ssh.exec_command_sudo(u"vpp_api_test", u"dump_interface_table")

static interactive_terminal_close(chan)¶

Close interactive terminal SSH channel.

Parameters: chan – SSH channel to be closed.

interactive_terminal_exec_command(chan, cmd, prompt)¶

Execute command on interactive terminal.

interactive_terminal_open() method has to be called first!

Parameters

chan – SSH channel with opened terminal.
cmd – Command to be executed.
prompt – Command prompt, sequence of characters used to indicate readiness to accept commands.

Returns

Command output.

Warning

Interruptingcow is used here, and it uses signal(SIGALRM) to let the operating system interrupt program execution. This has the following limitations: Python signal handlers only apply to the main thread, so you cannot use this from other threads. You must not use this in a program that uses SIGALRM itself (this includes certain profilers)

interactive_terminal_open(time_out=45)¶

Open interactive terminal on a new channel on the connected Node.

Parameters: time_out – Timeout in seconds.
Returns: SSH channel with opened terminal.

Warning

Interruptingcow is used here, and it uses signal(SIGALRM) to let the operating system interrupt program execution. This has the following limitations: Python signal handlers only apply to the main thread, so you cannot use this from other threads. You must not use this in a program that uses SIGALRM itself (this includes certain profilers)

scp(local_path, remote_path, get=False, timeout=30, wildcard=False)¶

Copy files from local_path to remote_path or vice versa.

connect() method has to be called first!

Parameters

local_path (str) – Path to local file that should be uploaded; or path where to save remote file.
remote_path (str) – Remote path where to place uploaded file; or path to remote file which should be downloaded.
get (bool) – scp operation to perform. Default is put.
timeout (int) – Timeout value in seconds.
wildcard (bool) – If path has wildcard characters. Default is false.

exception resources.libraries.python.ssh.SSHTimeout¶

Bases: Exception

This exception is raised when a timeout occurs.

resources.libraries.python.ssh.exec_cmd(node, cmd, timeout=600, sudo=False, disconnect=False, log_stdout_err=True, export=True)¶

Convenience function to ssh/exec/return rc, out & err.

Returns (rc, stdout, stderr).

Parameters

node (dict) – The node to execute command on.
cmd (str or OptionString) – Command to execute.
timeout (int) – Timeout value in seconds. Default: 600.
sudo (bool) – Sudo privilege execution flag. Default: False.
disconnect (bool) – Close the opened SSH connection if True.
log_stdout_err (bool) – If True, stdout and stderr are logged. stdout and stderr are logged also if the return code is not zero independently of the value of log_stdout_err.
export (bool) – If false, do not attempt JSON export. Needed for calls outside Robot (e.g. from reservation script).

Returns

RC, Stdout, Stderr.

Return type

Tuple[int, str, str]

resources.libraries.python.ssh.exec_cmd_no_error(node, cmd, timeout=600, sudo=False, message=None, disconnect=False, retries=0, include_reason=False, log_stdout_err=True, export=True)¶

Convenience function to ssh/exec/return out & err.

Verifies that return code is zero. Supports retries, timeout is related to each try separately then. There is sleep(1) before each retry. Disconnect (if enabled) is applied after each try.

Parameters

node (dict) – DUT node.
cmd (str or OptionString) – Command to be executed.
timeout (int) – Timeout value in seconds. Default: 600.
sudo (bool) – Sudo privilege execution flag. Default: False.
message (str) – Error message in case of failure. Default: None.
disconnect (bool) – Close the opened SSH connection if True.
retries (int) – How many times to retry on failure.
include_reason (bool) – Whether default info should be appended to message.
log_stdout_err (bool) – If True, stdout and stderr are logged. stdout and stderr are logged also if the return code is not zero independently of the value of log_stdout_err.
export (bool) – If false, do not attempt JSON export. Needed for calls outside Robot thread (e.g. parallel framework setup).

Returns

Stdout, Stderr.

Return type

tuple(str, str)

Raises

RuntimeError – If bash return code is not 0.

resources.libraries.python.ssh.scp_node(node, local_path, remote_path, get=False, timeout=30, disconnect=False)¶

Copy files from local_path to remote_path or vice versa.

Parameters

node (dict) – SUT node.
local_path (str) – Path to local file that should be uploaded; or path where to save remote file.
remote_path (str) – Remote path where to place uploaded file; or path to remote file which should be downloaded.
get (bool) – scp operation to perform. Default is put.
timeout (int) – Timeout value in seconds.
disconnect (bool) – Close the opened SSH connection if True.

Raises

RuntimeError – If SSH connection failed or SCP transfer failed.

2.70. topology suite¶

Defines nodes and topology structure.

class resources.libraries.python.topology.NodeSubTypeTG¶

Bases: object

Defines node sub-type TG - traffic generator.

IXNET = 'IXNET'¶

MOONGEN = 'MOONGEN'¶

TREX = 'TREX'¶

class resources.libraries.python.topology.NodeType¶

Bases: object

Defines node types used in topology dictionaries.

DUT = 'DUT'¶

TG = 'TG'¶

VM = 'VM'¶

class resources.libraries.python.topology.SocketType¶

Bases: object

Defines socket types used in topology dictionaries.

CLI = 'CLI'¶

PAPI = 'PAPI'¶

STATS = 'STATS'¶

class resources.libraries.python.topology.Topology¶

Bases: object

Topology data manipulation and extraction methods.

Defines methods used for manipulation and extraction of data from the active topology.

“Active topology” contains initially data from the topology file and can be extended with additional data from the DUTs like internal interface indexes or names. Additional data which can be filled to the active topology are

additional internal representation (index, name, …)

operational data (dynamic ports)

To access the port data it is recommended to use a port key because the key does not rely on the data retrieved from nodes, this allows to call most of the methods without having filled active topology with internal nodes data.

static add_new_port(node, ptype)¶

Add new port to the node to active topology.

Parameters

node (dict) – Node to add new port on.
ptype (str) – Port type, used as key prefix.

Returns

Port key or None

Return type

string or None

static add_new_socket(node, socket_type, socket_id, socket_path)¶

Add socket file of specific SocketType and ID to node.

Parameters

node (dict) – Node to add socket on.
socket_type (SocketType) – Socket type.
socket_id (str) – Socket id, currently equals to unique node key.
socket_path (str) – Socket absolute path.

static add_node_item(node, value, path)¶

Add item to topology node.

Parameters

node (dict) – Topology node.
value (str) – Value to insert.
path (list) – Path where to insert item.

static clean_sockets_on_all_nodes(nodes)¶

Remove temporary socket files from topology file.

Parameters: nodes – SUT nodes.

static convert_interface_reference(node, interface, wanted_format)¶

Takes interface reference in any format (name, link name, topology key or sw_if_index) and returns its equivalent in the desired format.

Parameters

node (dict) – Node in topology.
interface (str or int) – Name, sw_if_index, link name or key of an interface on the node.
wanted_format (str) – Format of return value wanted. Valid options are: sw_if_index, key, name.

Returns

Interface name, interface key or sw_if_index.

Return type

str or int

Raises

TypeError, ValueError – If provided with invalid arguments.
RuntimeError – If the interface does not exist in topology.

static convert_interface_reference_to_key(node, interface)¶

Takes interface reference in any format (name, link name, interface key or sw_if_index) and converts to interface key using Topology methods.

Parameters

node (dict) – Node in topology.
interface (str or int) – Name, sw_if_index, link name or key of an interface on the node.

Returns

Interface key.

Return type

str

Raises

TypeError – If provided with invalid interface argument.
RuntimeError – If the interface does not exist in topology.

static del_node_socket_id(node, socket_type, socket_id)¶

Delete socket of specific SocketType and ID from node.

Parameters

node (dict) – Node to delete socket from.
socket_type (SocketType) – Socket type.
socket_id (str) – Socket id, currently equals to unique node key.

get_active_connecting_links(node1, node2, filter_list_node1=None, filter_list_node2=None)¶

Return list of link names that connect together node1 and node2.

Parameters

node1 (dict) – Node topology dictionary.
node2 (dict) – Node topology dictionary.
filter_list_node1 (list of strings) – Link filter criteria for node1.
filter_list_node2 (list of strings) – Link filter criteria for node2.

Returns

List of strings that represent connecting link names.

Return type

list

static get_adjacent_node_and_interface(nodes_info, node, iface_key)¶

Get node and interface adjacent to specified interface on local network.

Parameters

nodes_info (dict) – Dictionary containing information on all nodes in topology.
node (dict) – Node that contains specified interface.
iface_key (str) – Interface key from topology file.

Returns

Return (node, interface_key) tuple or None if not found.

Return type

(dict, str)

static get_cryptodev(node)¶

Return Crytodev configuration of the node.

Parameters: node (dict) – Node created from topology.
Returns: Cryptodev configuration string.
Return type: str

get_egress_interfaces_name_for_nodes(node1, node2)¶

Get egress interfaces on node1 for link with node2.

Parameters

node1 (dict) – First node, node to get egress interface on.
node2 (dict) – Second node.

Returns

Egress interfaces.

Return type

list

get_first_active_connecting_link(node1, node2)¶

Get first link connecting the two nodes together.

Parameters

node1 (dict) – Connected node.
node2 (dict) – Connected node.

Returns

Name of a link connecting the two nodes together.

Return type

str

Raises

RuntimeError – If no links are found.

get_first_egress_interface_for_nodes(node1, node2)¶

Get first egress interface on node1 for link with node2.

Parameters

node1 (dict) – First node, node to get egress interface name on.
node2 (dict) – Second node.

Returns

Egress interface name.

Return type

str

static get_interface_by_link_name(node, link_name, subsequent=False)¶

Return interface key of link on node.

This method returns the interface name associated with a given link for a given node.

Parameters

node (dict) – The node topology dictionary.
link_name (string) – Name of the link that a interface is connected to.
subsequent (bool) – Use second interface of the link. Useful for back-to-back links. Default: False

Returns

Interface key of the interface connected to the given link.

Return type

str

static get_interface_by_name(node, iface_name)¶

Return interface key based on name from DUT/TG.

This method returns interface key based on interface name retrieved from the DUT, or TG.

Parameters

node (dict) – The node topology dictionary.
iface_name (string) – Interface name (string form).

Returns

Interface key.

Return type

str

static get_interface_by_sw_index(node, sw_if_index)¶

Return interface name of link on node.

This method returns the interface name associated with a software interface index assigned to the interface by vpp for a given node.

Parameters

node (dict) – The node topology dictionary.
sw_if_index (int) – sw_if_index of the link that a interface is connected to.

Returns

Interface name of the interface connected to the given link.

Return type

str

static get_interface_driver(node, iface_key)¶

Get interface driver.

Parameters

node (dict) – Node to get interface driver on.
iface_key (str) – Interface key from topology file.

Returns

Return interface driver or None if not found.

static get_interface_ip4(node, iface_key)¶

Get IP4 address for the interface.

Parameters

node (dict) – Node to get interface mac on.
iface_key (str) – Interface key from topology file.

Returns

Return IP4 or None if not found.

static get_interface_ip4_prefix_length(node, iface_key)¶

Get IP4 address prefix length for the interface.

Parameters

node (dict) – Node to get prefix length on.
iface_key (str) – Interface key from topology file.

Returns

Prefix length from topology file or the default IP4 prefix length if not found.

Return type

int

Raises

KeyError if iface_key is not found.

static get_interface_mac(node, iface_key)¶

Get MAC address for the interface.

Parameters

node (dict) – Node to get interface mac on.
iface_key (str) – Interface key from topology file.

Returns

Return MAC or None if not found.

static get_interface_mtu(node, iface_key)¶

Get interface MTU.

Returns physical layer MTU (max. size of Ethernet frame). :param node: Node to get interface MTU on. :param iface_key: Interface key from topology file. :type node: dict :type iface_key: str :returns: MTU or None if not found. :rtype: int

static get_interface_name(node, iface_key)¶

Get interface name (retrieved from DUT/TG).

Returns name in string format, retrieved from the node. :param node: Node to get interface name on. :param iface_key: Interface key from topology file. :type node: dict :type iface_key: str :returns: Interface name or None if not found. :rtype: str

static get_interface_numa_node(node, iface_key)¶

Get interface numa node.

Returns physical relation to numa node, numa_id.

Parameters

node (dict) – Node to get numa id on.
iface_key (str) – Interface key from topology file.

Returns

numa node id, None if not available.

Return type

int

static get_interface_pci_addr(node, iface_key)¶

Get interface PCI address.

Parameters

node (dict) – Node to get interface PCI address on.
iface_key (str) – Interface key from topology file.

Returns

Return PCI address or None if not found.

static get_interface_sw_index(node, iface_key)¶

Get VPP sw_if_index for the interface using interface key.

Parameters

node (dict) – Node to get interface sw_if_index on.
iface_key (str/int) – Interface key from topology file, or sw_if_index.

Returns

Return sw_if_index or None if not found.

Return type

int or None

static get_interface_sw_index_by_name(node, iface_name)¶

Get VPP sw_if_index for the interface using interface name.

Parameters

node (dict) – Node to get interface sw_if_index on.
iface_name (str) – Interface name.

Returns

Return sw_if_index or None if not found.

Raises

TypeError – If provided interface name is not a string.

static get_interface_vlan(node, iface_key)¶

Get interface vlan.

Parameters

node (dict) – Node to get interface driver on.
iface_key (str) – Interface key from topology file.

Returns

Return interface vlan or None if not found.

get_interfaces_by_link_names(node, link_names)¶

Return dictionary of dictionaries {“interfaceN”, interface name}.

This method returns the interface names associated with given links for a given node.

Parameters

node (dict) – The node topology directory.
link_names (list) – List of names of the link that a interface is connected to.

Returns

Dictionary of interface names that are connected to the given links.

Return type

dict

static get_interfaces_numa_node(node, *iface_keys)¶

Get numa node on which are located most of the interfaces.

Return numa node with highest count of interfaces provided as arguments. Return 0 if the interface does not have numa_node information available. If all interfaces have unknown location (-1), then return 0. If most of interfaces have unknown location (-1), but there are some interfaces with known location, then return the second most location of the provided interfaces.

Parameters

node (dict) – Node from DICT__nodes.
iface_keys (strings) – Interface keys for lookup.

Returns

Numa node of most given interfaces or 0.

Return type

int

static get_links(nodes)¶

Get list of links(networks) in the topology.

Parameters: nodes (dict) – Nodes of the test topology.
Returns: Links in the topology.
Return type: list

get_links_dict_from_nodes(tgen, dut1, dut2)¶

Return link combinations used in tests in circular topology.

For the time being it returns links from the Node path: TG->DUT1->DUT2->TG The naming convention until changed to something more general is implemented is this: DUT1_DUT2_LINK: link name between DUT! and DUT2 DUT1_TG_LINK: link name between DUT1 and TG DUT2_TG_LINK: link name between DUT2 and TG TG_TRAFFIC_LINKS: list of link names that generated traffic is sent to and from DUT1_BD_LINKS: list of link names that will be connected by the bridge domain on DUT1 DUT2_BD_LINKS: list of link names that will be connected by the bridge domain on DUT2

Parameters

tgen (dict) – Traffic generator node data.
dut1 (dict) – DUT1 node data.
dut2 (dict) – DUT2 node data.

Returns

Dictionary of possible link combinations.

Return type

dict

static get_node_arch(node)¶

Return arch of the node.: Default to x86_64 if no arch present

Parameters: node (dict) – Node created from topology.
Returns: Node architecture
Return type: str

static get_node_by_hostname(nodes, hostname)¶

Get node from nodes of the topology by hostname.

Parameters

nodes (dict) – Nodes of the test topology.
hostname (str) – Host name.

Returns

Node dictionary or None if not found.

static get_node_hostname(node)¶

Return host (hostname/ip address) of the node.

Parameters: node (dict) – Node created from topology.
Returns: Hostname or IP address.
Return type: str

static get_node_interfaces(node)¶

Get all node interfaces.

Parameters: node (dict) – Node to get list of interfaces from.
Returns: Return list of keys of all interfaces.
Return type: list

static get_node_link_mac(node, link_name)¶

Return interface mac address by link name.

Parameters

node (dict) – Node to get interface sw_if_index on.
link_name (str) – Link name.

Returns

MAC address string.

Return type

str

static get_node_sockets(node, socket_type=None)¶

Get node socket files.

Parameters

node (dict) – Node to get sockets from.
socket_type (SocketType) – Socket type or None for all sockets.

Returns

Node sockets or None if not found.

Return type

dict

static get_uio_driver(node)¶

Return uio-driver configuration of the node.

Parameters: node (dict) – Node created from topology.
Returns: uio-driver configuration string.
Return type: str

static is_tg_node(node)¶

Find out whether the node is TG.

Parameters: node (dict) – Node to examine.
Returns: True if node is type of TG, otherwise False.
Return type: bool

static remove_all_added_ports_on_all_duts_from_topology(nodes)¶

Remove all added ports on all DUT nodes in the topology.

Parameters: nodes (dict) – Nodes in the topology.
Returns: Nothing

static remove_all_added_vif_ports_on_all_duts_from_topology(nodes)¶

Remove all added Virtual Interfaces on all DUT nodes in the topology.

Parameters: nodes (dict) – Nodes in the topology.
Returns: Nothing

static remove_all_ports(node, ptype)¶

Remove all ports with ptype as prefix.

Parameters: node (dict) – Node to remove ports on.
Param: ptype: Port type, used as key prefix.
Returns: Nothing

static remove_all_vif_ports(node)¶

Remove all Virtual Interfaces on DUT node.

Parameters: node (dict) – Node to remove VIF ports on.
Returns: Nothing

static remove_port(node, iface_key)¶

Remove required port from active topology.

Parameters: node (dict) – Node to remove port on.
Param: iface_key: Topology key of the interface.
Returns: Nothing

static set_interface_numa_node(node, iface_key, numa_node_id)¶

Set interface numa_node location.

Parameters

node (dict) – Node to set numa_node on.
iface_key (str) – Interface key from topology file.
numa_node_id (int) – Num_node ID.

Returns

Return iface_key or None if not found.

static update_interface_mac_address(node, iface_key, mac_address)¶

Update mac_address on the interface from the node.

Parameters

node (dict) – Node to update MAC on.
iface_key (str) – Topology key of the interface.
mac_address (str) – MAC address.

static update_interface_memif_id(node, iface_key, memif_id)¶

Update memif ID on the interface from the node.

Parameters

node (dict) – Node to update memif ID on.
iface_key (str) – Topology key of the interface.
memif_id (str) – Memif interface ID.

static update_interface_memif_role(node, iface_key, memif_role)¶

Update memif role on the interface from the node.

Parameters

node (dict) – Node to update memif role on.
iface_key (str) – Topology key of the interface.
memif_role (str) – Memif role.

static update_interface_memif_socket(node, iface_key, memif_socket)¶

Update memif socket name on the interface from the node.

Parameters

node (dict) – Node to update socket name on.
iface_key (str) – Topology key of the interface.
memif_socket (str) – Path to named socket on node.

static update_interface_name(node, iface_key, name)¶

Update name on the interface from the node.

Parameters

node (dict) – Node to update name on.
iface_key (str) – Topology key of the interface.
name (str) – Interface name to store.

static update_interface_pci_address(node, iface_key, pci_address)¶

Update pci_address on the interface from the node.

Parameters

node (dict) – Node to update PCI on.
iface_key (str) – Topology key of the interface.
pci_address (str) – PCI address.

static update_interface_sw_if_index(node, iface_key, sw_if_index)¶

Update sw_if_index on the interface from the node.

Parameters

node (dict) – Node to update sw_if_index on.
iface_key (str) – Topology key of the interface.
sw_if_index (int) – Internal index to store.

static update_interface_tap_dev_name(node, iface_key, dev_name)¶

Update device name on the tap interface from the node.

Parameters

node (dict) – Node to update tap device name on.
iface_key (str) – Topology key of the interface.
dev_name (str) – Device name of the tap interface.

Returns

Nothing

static update_interface_vhost_socket(node, iface_key, vhost_socket)¶

Update vhost socket name on the interface from the node.

Parameters

node (dict) – Node to update socket name on.
iface_key (str) – Topology key of the interface.
vhost_socket (str) – Path to named socket on node.

static update_interface_vlan(node, iface_key, vlan)¶

Update VLAN on the interface from the node.

Parameters

node (dict) – Node to update VLAN on.
iface_key (str) – Topology key of the interface.
vlan (str) – VLAN ID.