2. Python Library¶

2.7. Classify suite¶

2.8. 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.

TODO: Yaml files are easier for humans to edit. Figure out how to set the attributes by parsing a file that works regardless of current working directory.

BITWISE_NON_ZERO = 4294967295¶

CORE_DUMP_DIR = '/tmp'¶

CPU_CNT_MAIN = 1¶

CPU_CNT_SYSTEM = 1¶

DATAPATH_INTERFACES_MAX = 100¶

DEFAULT_IP4_PREFIX_LENGTH = '24'¶

DOCKER_SUT_IMAGE_UBUNTU = 'snergster/csit-sut:latest'¶

DOCKER_SUT_IMAGE_UBUNTU_ARM = 'snergster/csit-arm-sut:latest'¶

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'], 'Cisco-VIC-1227': ['vfio-pci'], 'Cisco-VIC-1385': ['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 = ''¶

FAIL_ON_CRC_MISMATCH = False¶

FORBIDDEN_SUITE_PREFIX_LIST = ['avf-', 'rdma-', 'mlx5-']¶

KERNEL_CORE_PATTERN = '/tmp/%p-%u-%g-%s-%t-%h-%e.core'¶

NIC_DRIVER_TO_PLUGINS = {'avf': 'avf_plugin.so', 'rdma-core': 'rdma_plugin.so', 'vfio-pci': 'dpdk_plugin.so'}¶

NIC_DRIVER_TO_SUITE_PREFIX = {'avf': 'avf-', 'rdma-core': 'rdma-', 'vfio-pci': ''}¶

NIC_DRIVER_TO_TAG = {'avf': 'DRV_AVF', 'rdma-core': 'DRV_RDMA_CORE', 'vfio-pci': 'DRV_VFIO_PCI'}¶

NIC_DRIVER_TO_VFS = {'avf': 'nic_vfs}= | 1', 'rdma-core': 'nic_vfs}= | 0', 'vfio-pci': 'nic_vfs}= | 0'}¶

NIC_NAME_TO_BPS_LIMIT = {'Amazon-Nitro-50G': 10000000000, 'Cisco-VIC-1227': 10000000000, 'Cisco-VIC-1385': 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', 'Cisco-VIC-1227': '10ge2p1vic1227', 'Cisco-VIC-1385': '40ge2p1vic1385', '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'], 'Cisco-VIC-1227': ['vfio-pci'], 'Cisco-VIC-1385': ['vfio-pci'], 'Intel-X520-DA2': ['vfio-pci'], 'Intel-X553': ['vfio-pci'], 'Intel-X710': ['vfio-pci', 'avf'], 'Intel-XL710': ['vfio-pci', 'avf'], 'Intel-XXV710': ['vfio-pci', 'avf'], 'Mellanox-CX556A': ['rdma-core']}¶

NIC_NAME_TO_PPS_LIMIT = {'Amazon-Nitro-50G': 1500000, 'Cisco-VIC-1227': 14880952, 'Cisco-VIC-1385': 18750000, 'Intel-X520-DA2': 14880952, 'Intel-X553': 14880952, 'Intel-X710': 14880952, 'Intel-XL710': 18750000, 'Intel-XXV710': 18750000, 'Mellanox-CX556A': 47000000, 'virtual': 14880952}¶

PERF_TRIAL_DURATION = 1.0¶

PERF_TRIAL_LATENCY_DURATION = 5.0¶

PERF_TRIAL_MULTIPLICITY = 10¶

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\\\n| ... | at line rate and reports total received packets over trial period.\\', 'ndrpdr': 'ication:* TG finds and reports throughput NDR (Non Drop\\\n| ... | Rate) with zero packet loss tolerance and throughput PDR (Partial Drop\\\n| ... | Rate) with non-zero packet loss tolerance (LT) expressed in percentage\\\n| ... | of packets transmitted. NDR and PDR are discovered for different\\\n| ... | Ethernet L2 frame sizes using MLRsearch library.\\', 'soak': 'fication:* 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.\\'}¶

QEMU_BIN_PATH = '/usr/bin'¶

QEMU_VM_DPDK = '/opt/dpdk-20.02'¶

QEMU_VM_IMAGE = '/var/lib/vm/vhost-nested.img'¶

QEMU_VM_KERNEL = '/opt/boot/vmlinuz'¶

QEMU_VM_KERNEL_INITRD = '/opt/boot/initrd.img'¶

REMOTE_FW_DIR = '/tmp/openvpp-testing'¶

RESOURCES_LIB_SH = 'resources/libraries/bash'¶

RESOURCES_PAPI_PROVIDER = 'resources/tools/papi/vpp_papi_provider.py'¶

RESOURCES_TPL_CONTAINER = 'resources/templates/container'¶

RESOURCES_TPL_K8S = 'resources/templates/kubernetes'¶

RESOURCES_TPL_VAT = 'resources/templates/vat'¶

RESOURCES_TPL_VCL = 'resources/templates/vcl'¶

RESOURCES_TPL_VM = 'resources/templates/vm'¶

RESOURCES_TP_WRK_WWW = 'resources/traffic_profiles/wrk/www'¶

SOCKSTAT_PATH = '/run/vpp/stats.sock'¶

SOCKSVR_PATH = '/run/vpp/api.sock'¶

TREX_CORE_COUNT = 15¶

TREX_EXTRA_CMDLINE = '--mbuf-factor 32'¶

TREX_INSTALL_DIR = '/opt/trex-core-2.73'¶

TREX_LIMIT_MEMORY = 8192¶

TREX_SEND_FORCE = False¶

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.9. ContainerUtils suite¶

2.10. Cop suite¶

2.11. 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.12. 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_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_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.13. 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.

Note

# lspci -vmmks 0000:00:05.0 Slot: 00:05.0 Class: Ethernet controller Vendor: Red Hat, Inc Device: Virtio network device SVendor: Red Hat, Inc SDevice: Device 0001 PhySlot: 5 Driver: virtio-pci

Parameters

node (dict) – DUT node.
pci_addr (str) – PCI device address.

Returns

Driver or None

Raises

RuntimeError – If PCI rescan or lspci command execution failed.
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 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.14. Dhcp suite¶

2.15. 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.16. 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¶

Bases: enum.Enum

Type of the loss acceptance criteria.

FRAMES = 1¶

PERCENTAGE = 2¶

class resources.libraries.python.DropRateSearch.RateType¶

Bases: enum.Enum

Type of rate units.

BITS_PER_SECOND = 3¶

PACKETS_PER_SECOND = 2¶

PERCENTAGE = 1¶

class resources.libraries.python.DropRateSearch.SearchDirection¶

Bases: enum.Enum

Direction of linear search.

BOTTOM_UP = 2¶

TOP_DOWN = 1¶

class resources.libraries.python.DropRateSearch.SearchResultType¶

Bases: enum.Enum

Type of search result evaluation.

BEST_OF_N = 1¶

WORST_OF_N = 2¶

class resources.libraries.python.DropRateSearch.SearchResults¶

Bases: enum.Enum

Result of the drop rate search.

FAILURE = 2¶

SUCCESS = 1¶

SUSPICIOUS = 3¶

2.17. 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.18. GBP suite¶

2.19. HoststackUtil suite¶

2.20. IPAddress suite¶

Common IP utilities library.

class resources.libraries.python.IPAddress.AddressFamily¶

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.21. IPUtil suite¶

2.22. IPsecUtil suite¶

2.23. IPv6Util suite¶

2.24. InterfaceUtil suite¶

2.25. KubernetesUtils suite¶

2.26. L2Util suite¶

2.27. 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.28. LispSetup suite¶

2.29. LoadBalancerUtil suite¶

2.30. 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.31. Memif suite¶

2.32. NATUtil suite¶

2.33. 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.34. 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)¶

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.

Returns

Topology information dictionary.

Return type

dict

Raises

RuntimeError – If unsupported combination of parameters.

compute_path(always_same_link=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.
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.35. NsimUtil suite¶

2.36. 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.37. PapiExecutor suite¶

2.38. PapiHistory suite¶

2.39. Policer suite¶

2.40. QemuManager suite¶

2.41. QemuUtils suite¶

2.42. SRv6 suite¶

2.43. 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.44. 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.

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.45. 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.46. TGSetup suite¶

2.47. Tap suite¶

2.48. TestConfig suite¶

2.49. Trace suite¶

2.50. TrafficGenerator suite¶

Performance testing traffic generator library.

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, skip_warmup=False)¶

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.
skip_warmup (bool) – Start TRex without warmup traffic if true.

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.

FIXME: Describe API.

ROBOT_LIBRARY_SCOPE = 'TEST SUITE'¶

fail_if_no_traffic_forwarded()¶

Fail if no traffic forwarded.

Returns: nothing
Raises: Exception – If no traffic forwarded.

get_approximated_rate()¶

Return approximated rate computed as ratio of transmited packets over duration of trial.

Returns: Approximated rate.
Return type: str

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_measurement_result(duration=None, transmit_rate=None)¶

Return the result of last measurement as ReceiveRateMeasurement.

Separate function, as measurements can end either by time or by explicit call, this is the common block at the end.

TODO: Fail on running or already reported measurement.

Parameters

duration (float or NoneType) – Measurement duration [s] if known beforehand. For explicitly stopped measurement it is estimated.
transmit_rate (float or NoneType) – Target aggregate transmit rate [pps]. If not given, computed assuming it was bidirectional.

Returns

Structure containing the result of the measurement.

Return type

ReceiveRateMeasurement

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

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 TRex is running using pidof.

Parameters: node (dict) – Traffic generator node.
Returns: True if TRex is running otherwise False.
Return type: bool
Raises: RuntimeError – If node type is not a TG.

measure(duration, transmit_rate)¶

Run trial measurement, parse and return aggregate results.

Aggregate means sum over traffic directions.

Parameters

duration (float) – Trial duration [s].
transmit_rate (float) – Target aggregate transmit rate [pps].

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, warmup_time=5, async_call=False, latency=True, traffic_directions=2, tx_port=0, rx_port=1)¶

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 bidirectional traffic also contains flows transmitted from rx_port and received in tx_port. But some tests use asymmetric traffic, so those arguments are relevant.

Also 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.

TODO: Is it better to have less descriptive argument names just to make them less probable to be viewed as misleading or confusing? See https://gerrit.fd.io/r/#/c/17625/11/resources/libraries/python /TrafficGenerator.py@406

Parameters

duration (str) – Duration of test traffic generation in seconds.
rate (str) – Offered load per interface (e.g. 1%, 3gbps, 4mpps, …).
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.
warmup_time (float) – Warmup phase in seconds.
async_call (bool) – Async mode.
latency (bool) – With latency measurement.
traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2
tx_port (int) – Traffic generator transmit port for first flow. Default: 0
rx_port (int) – Traffic generator receive port for first flow. Default: 1

Returns

TG output.

Return type

str

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.

set_rate_provider_defaults(frame_size, traffic_profile, warmup_time=0.0, traffic_directions=2)¶

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.
warmup_time (float) – Traffic duration before measurement starts [s].
traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2

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 node subtype is not a TREX or startup failed.

stop_traffic_on_tg()¶

Stop all traffic on TG.

Returns: Structure containing the result of the measurement.
Return type: ReceiveRateMeasurement
Raises: RuntimeError – If TG is not set.

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 TRex teardown fails.

trex_stl_start_remote_exec(duration, rate, frame_size, traffic_profile, async_call=False, latency=True, warmup_time=5.0, traffic_directions=2, tx_port=0, rx_port=1)¶

Execute script on remote node over ssh to start traffic.

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

Parameters

duration (float) – Time expresed in seconds for how long to send traffic.
rate (str) – Traffic rate expressed with units (pps, %)
frame_size (str) – L2 frame size to send (without padding and IPG).
traffic_profile (str) – Module name as a traffic profile identifier. See GPL/traffic_profiles/trex for implemented modules.
async_call (bool) – If enabled then don’t wait for all incomming trafic.
latency (bool) – With latency measurement.
warmup_time (float) – Warmup time period.
traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2
tx_port (int) – Traffic generator transmit port for first flow. Default: 0
rx_port (int) – Traffic generator receive port for first flow. Default: 1

Raises

RuntimeError – In case of TG driver issue.

trex_stl_stop_remote_exec(node)¶

Execute script on remote node over ssh to stop running traffic.

Internal state is updated with measurement results.

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

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 aggregate.

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=720.0, doublings=1, traffic_directions=2)¶

Setup initialized TG, perform optimized search, return intervals.

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 uni-directional target transmit rate [pps].
maximum_transmit_rate (float) – Maximal uni-directional target transmit rate [pps].
packet_loss_ratio (float) – Fraction 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].
doublings (int) – How many doublings to do in external search step. Default 1 is suitable for fairly stable tests, less stable tests might get better overal duration with 2 or more.
traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2

Returns

Structure containing narrowed down NDR and PDR intervals and their measurements.

Return type

NdrPdrResult

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=1800.0, trace_enabled=False, traffic_directions=2)¶

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 uni-directional target transmit rate [pps].
maximum_transmit_rate (float) – Maximal uni-directional target transmit rate [pps].
plr_target (float) – Fraction 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].
trace_enabled (bool) – True if trace enabled else False.
traffic_directions (int) – Traffic is bi- (2) or uni- (1) directional. Default: 2

Returns

Average and stdev of estimated aggregate rate giving PLR.

Return type

2-tuple of float

2.51. 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.52. VPPUtil suite¶

2.53. VatExecutor suite¶

2.54. 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.55. VhostUser suite¶

2.56. 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.

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 = None¶: 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.57. VppConfigGenerator suite¶

2.58. VppCounters suite¶

2.59. ssh suite¶

Library for SSH connection management.

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

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.

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

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.

Returns

Stdout, Stderr.

Return type

tuple(str, str)

Raises

RuntimeError – If bash return code is not 0.

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

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.

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

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.

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 – Path to local file that should be uploaded; or

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

exception resources.libraries.python.ssh.SSHTimeout¶

Bases: Exception

This exception is raised when a timeout occurs.

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.60. tcp suite¶

2.61. topology suite¶

Defines nodes and topology structure.

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

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.

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.

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.

PAPI = 'PAPI'¶

STATS = 'STATS'¶

class resources.libraries.python.topology.NodeSubTypeTG¶

Bases: object

Defines node sub-type TG - traffic generator.

IXNET = 'IXNET'¶

MOONGEN = 'MOONGEN'¶

TREX = 'TREX'¶