testpmd - TestPMD Parameters Modelling

Module containing all the TestPmd-related parameter classes.

class PortTopology

Bases: StrEnum

Enum representing the port topology.

paired = 'paired'

(0,1), (2,3), (4,5).

Type:

In paired mode, the forwarding is between pairs of ports, e.g.

chained = 'chained'

In chained mode, the forwarding is to the next available port in the port mask, e.g.: (0,1), (1,2), (2,0).

The ordering of the ports can be changed using the portlist testpmd runtime function.

loop = 'loop'

In loop mode, ingress traffic is simply transmitted back on the same interface.

class PortNUMAConfig

Bases: NamedTuple

DPDK port to NUMA socket association tuple.

port: int

socket: int

static __new__(_cls, port: int, socket: int)

Create new instance of PortNUMAConfig(port, socket)

class FlowDirection

Bases: Flag

Flag indicating the direction of the flow.

A bi-directional flow can be specified with the pipe:

>>> TestPmdFlowDirection.RX | TestPmdFlowDirection.TX
<TestPmdFlowDirection.TX|RX: 3>

RX = 1

TX = 2

class RingNUMAConfig

Bases: NamedTuple

Tuple associating DPDK port, direction of the flow and NUMA socket.

port: int

direction: FlowDirection

socket: int

static __new__(_cls, port: int, direction: FlowDirection, socket: int)

Create new instance of RingNUMAConfig(port, direction, socket)

class EthPeer

Bases: NamedTuple

Tuple associating a MAC address to the specified DPDK port.

port_no: int

mac_address: str

static __new__(_cls, port_no: int, mac_address: str)

Create new instance of EthPeer(port_no, mac_address)

class TxIPAddrPair

Bases: NamedTuple

Tuple specifying the source and destination IPs for the packets.

source_ip: str

dest_ip: str

static __new__(_cls, source_ip: str, dest_ip: str)

Create new instance of TxIPAddrPair(source_ip, dest_ip)

class TxUDPPortPair

Bases: NamedTuple

Tuple specifying the UDP source and destination ports for the packets.

If leaving dest_port unspecified, source_port will be used for the destination port as well.

source_port: int

dest_port: int | None

static __new__(_cls, source_port: int, dest_port: int | None = None)

Create new instance of TxUDPPortPair(source_port, dest_port)

class DisableRSS

Bases: Params

Disables RSS (Receive Side Scaling).

__init__() → None

class SetRSSIPOnly

Bases: Params

Sets RSS (Receive Side Scaling) functions for IPv4/IPv6 only.

__init__() → None

class SetRSSUDP

Bases: Params

Sets RSS (Receive Side Scaling) functions for IPv4/IPv6 and UDP.

__init__() → None

class RSSSetting

Bases: EnumType

Enum representing a RSS setting. Each property is a class that needs to be initialised.

Disabled

alias of DisableRSS

SetIPOnly

alias of SetRSSIPOnly

SetUDP

alias of SetRSSUDP

class SimpleForwardingModes

Bases: StrEnum

The supported packet forwarding modes for TestPmdShells.

io = 'io'

mac = 'mac'

macswap = 'macswap'

rxonly = 'rxonly'

csum = 'csum'

icmpecho = 'icmpecho'

ieee1588 = 'ieee1588'

fivetswap = '5tswap'

shared_rxq = 'shared-rxq'

recycle_mbufs = 'recycle_mbufs'

class TXOnlyForwardingMode

Bases: Params

Sets a TX-Only forwarding mode.

multi_flow

Generates multiple flows if set to True.

Type:

Literal[True, None]

segments_length

Sets TX segment sizes or total packet length.

Type:

list[int] | None

__init__(*, multi_flow: Literal[True, None] = None, segments_length: list[int] | None = None) → None

class FlowGenForwardingMode

Bases: Params

Sets a flowgen forwarding mode.

clones

Set the number of each packet clones to be sent. Sending clones reduces host CPU load on creating packets and may help in testing extreme speeds or maxing out Tx packet performance. N should be not zero, but less than ‘burst’ parameter.

Type:

int | None

flows

Set the number of flows to be generated, where 1 <= N <= INT32_MAX.

Type:

int | None

segments_length

Set TX segment sizes or total packet length.

Type:

list[int] | None

__init__(*, clones: int | None = None, flows: int | None = None, segments_length: list[int] | None = None) → None

class NoisyForwardingMode

Bases: Params

Sets a noisy forwarding mode.

forward_mode

Set the noisy VNF forwarding mode.

Type:

Optional[Literal[<SimpleForwardingModes.io: ‘io’>, <SimpleForwardingModes.mac: ‘mac’>, <SimpleForwardingModes.macswap: ‘macswap’>, <SimpleForwardingModes.fivetswap: ‘5tswap’>]]

tx_sw_buffer_size

Set the maximum number of elements of the FIFO queue to be created for buffering packets.

Type:

int | None

tx_sw_buffer_flushtime

Set the time before packets in the FIFO queue are flushed.

Type:

int | None

lkup_memory

Set the size of the noisy neighbor simulation memory buffer in MB to N.

Type:

int | None

lkup_num_reads

Set the size of the noisy neighbor simulation memory buffer in MB to N.

Type:

int | None

lkup_num_writes

Set the number of writes to be done in noisy neighbor simulation memory buffer to N.

Type:

int | None

lkup_num_reads_writes

Set the number of r/w accesses to be done in noisy neighbor simulation memory buffer to N.

Type:

int | None

__init__(*, forward_mode: ~typing.Optional[~typing.Literal[<SimpleForwardingModes.io: 'io'>, <SimpleForwardingModes.mac: 'mac'>, <SimpleForwardingModes.macswap: 'macswap'>, <SimpleForwardingModes.fivetswap: '5tswap'>]] = SimpleForwardingModes.io, tx_sw_buffer_size: int | None = None, tx_sw_buffer_flushtime: int | None = None, lkup_memory: int | None = None, lkup_num_reads: int | None = None, lkup_num_writes: int | None = None, lkup_num_reads_writes: int | None = None) → None

class HairpinMode

Bases: Flag

Flag representing the hairpin mode.

TWO_PORTS_LOOP = 1

Two hairpin ports loop.

TWO_PORTS_PAIRED = 2

Two hairpin ports paired.

EXPLICIT_TX_FLOW = 16

Explicit Tx flow rule.

FORCE_RX_QUEUE_MEM_SETTINGS = 256

Force memory settings of hairpin RX queue.

FORCE_TX_QUEUE_MEM_SETTINGS = 512

Force memory settings of hairpin TX queue.

RX_QUEUE_USE_LOCKED_DEVICE_MEMORY = 4096

Hairpin RX queues will use locked device memory.

RX_QUEUE_USE_RTE_MEMORY = 8192

Hairpin RX queues will use RTE memory.

TX_QUEUE_USE_LOCKED_DEVICE_MEMORY = 65536

Hairpin TX queues will use locked device memory.

TX_QUEUE_USE_RTE_MEMORY = 262144

Hairpin TX queues will use RTE memory.

class RXRingParams

Bases: Params

Sets the RX ring parameters.

descriptors

Set the number of descriptors in the RX rings to N, where N > 0.

Type:

int | None

prefetch_threshold

Set the prefetch threshold register of RX rings to N, where N >= 0.

Type:

int | None

host_threshold

Set the host threshold register of RX rings to N, where N >= 0.

Type:

int | None

write_back_threshold

Set the write-back threshold register of RX rings to N, where N >= 0.

Type:

int | None

free_threshold

Set the free threshold of RX descriptors to N, where 0 <= N < value of -–rxd.

Type:

int | None

__init__(*, descriptors: int | None = None, prefetch_threshold: int | None = None, host_threshold: int | None = None, write_back_threshold: int | None = None, free_threshold: int | None = None) → None

class RXMultiQueueMode

Bases: Flag

Flag representing the RX multi-queue mode.

RSS = 1

DCB = 2

VMDQ = 4

class TXRingParams

Bases: Params

Sets the TX ring parameters.

descriptors

Set the number of descriptors in the TX rings to N, where N > 0.

Type:

int | None

rs_bit_threshold

Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of --txd.

Type:

int | None

prefetch_threshold

Set the prefetch threshold register of TX rings to N, where N >= 0.

Type:

int | None

host_threshold

Set the host threshold register of TX rings to N, where N >= 0.

Type:

int | None

write_back_threshold

Set the write-back threshold register of TX rings to N, where N >= 0.

Type:

int | None

free_threshold

Set the transmit free threshold of TX rings to N, where 0 <= N <= value of --txd.

Type:

int | None

__init__(*, descriptors: int | None = None, rs_bit_threshold: int | None = None, prefetch_threshold: int | None = None, host_threshold: int | None = None, write_back_threshold: int | None = None, free_threshold: int | None = None) → None

class Event

Bases: StrEnum

Enum representing a testpmd event.

unknown = 'unknown'

queue_state = 'queue_state'

vf_mbox = 'vf_mbox'

macsec = 'macsec'

intr_lsc = 'intr_lsc'

intr_rmv = 'intr_rmv'

intr_reset = 'intr_reset'

dev_probed = 'dev_probed'

dev_released = 'dev_released'

flow_aged = 'flow_aged'

err_recovering = 'err_recovering'

recovery_success = 'recovery_success'

recovery_failed = 'recovery_failed'

all = 'all'

class SimpleMempoolAllocationMode

Bases: StrEnum

Enum representing simple mempool allocation modes.

native = 'native'

Create and populate mempool using native DPDK memory.

xmem = 'xmem'

Create and populate mempool using externally and anonymously allocated area.

xmemhuge = 'xmemhuge'

Create and populate mempool using externally and anonymously allocated hugepage area.

class AnonMempoolAllocationMode

Bases: Params

Create mempool using native DPDK memory, but populate using anonymous memory.

no_iova_contig

Enables to create mempool which is not IOVA contiguous.

Type:

Literal[True, None]

__init__(*, no_iova_contig: Literal[True, None] = None) → None

class TestPmdParams

Bases: EalParams

The testpmd shell parameters.

interactive_mode

Run testpmd in interactive mode.

Type:

Literal[True, None]

auto_start

Start forwarding on initialization.

Type:

Literal[True, None]

tx_first

Start forwarding, after sending a burst of packets first.

Type:

Literal[True, None]

stats_period

Display statistics every PERIOD seconds, if interactive mode is disabled. The default value is 0, which means that the statistics will not be displayed.

Note

This flag should be used only in non-interactive mode.

Type:

int | None

display_xstats

Display comma-separated list of extended statistics every PERIOD seconds as specified in --stats-period or when used with interactive commands that show Rx/Tx statistics (i.e. ‘show port stats’).

Type:

list[str] | None

nb_cores

Set the number of forwarding cores, where 1 <= N <= “number of cores” or RTE_MAX_LCORE from the configuration file.

Type:

int | None

coremask

Set the bitmask of the cores running the packet forwarding test. The main lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.

Type:

int | None

nb_ports

Set the number of forwarding ports, where 1 <= N <= “number of ports” on the board or RTE_MAX_ETHPORTS from the configuration file. The default value is the number of ports on the board.

Type:

int | None

port_topology

Set port topology, where mode is paired (the default), chained or loop.

Type:

framework.params.testpmd.PortTopology | None

portmask

Set the bitmask of the ports used by the packet forwarding test.

Type:

int | None

portlist

Set the forwarding ports based on the user input used by the packet forwarding test. ‘-‘ denotes a range of ports to set including the two specified port IDs ‘,’ separates multiple port values. Possible examples like –portlist=0,1 or –portlist=0-2 or –portlist=0,1-2 etc.

Type:

str | None

numa

Enable/disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs).

Type:

Literal[True, False, None]

socket_num

Set the socket from which all memory is allocated in NUMA mode, where 0 <= N < number of sockets on the board.

Type:

int | None

port_numa_config

Specify the socket on which the memory pool to be used by the port will be allocated.

Type:

list[framework.params.testpmd.PortNUMAConfig] | None

ring_numa_config

Specify the socket on which the TX/RX rings for the port will be allocated. Where flag is 1 for RX, 2 for TX, and 3 for RX and TX.

Type:

list[framework.params.testpmd.RingNUMAConfig] | None

total_num_mbufs

Set the number of mbufs to be allocated in the mbuf pools, where N > 1024.

Type:

int | None

mbuf_size

Set the data size of the mbufs used to N bytes, where N < 65536. If multiple mbuf-size values are specified the extra memory pools will be created for allocating mbufs to receive packets with buffer splitting features.

Type:

list[int] | None

mbcache

Set the cache of mbuf memory pools to N, where 0 <= N <= 512.

Type:

int | None

max_pkt_len

Set the maximum packet size to N bytes, where N >= 64.

Type:

int | None

eth_peers_configfile

Use a configuration file containing the Ethernet addresses of the peer ports.

Type:

pathlib.PurePath | None

eth_peer

Set the MAC address XX:XX:XX:XX:XX:XX of the peer port N, where 0 <= N < RTE_MAX_ETHPORTS.

Type:

list[framework.params.testpmd.EthPeer] | None

tx_ip

Set the source and destination IP address used when doing transmit only test. The defaults address values are source 198.18.0.1 and destination 198.18.0.2. These are special purpose addresses reserved for benchmarking (RFC 5735).

Type:

framework.params.testpmd.TxIPAddrPair | None

tx_udp

Set the source and destination UDP port number for transmit test only test. The default port is the port 9 which is defined for the discard protocol (RFC 863).

Type:

framework.params.testpmd.TxUDPPortPair | None

enable_lro

Enable large receive offload.

Type:

Literal[True, None]

max_lro_pkt_size

Set the maximum LRO aggregated packet size to N bytes, where N >= 64.

Type:

int | None

disable_crc_strip

Disable hardware CRC stripping.

Type:

Literal[True, None]

enable_scatter

Enable scatter (multi-segment) RX.

Type:

Literal[True, None]

enable_hw_vlan

Enable hardware VLAN.

Type:

Literal[True, None]

enable_hw_vlan_filter

Enable hardware VLAN filter.

Type:

Literal[True, None]

enable_hw_vlan_strip

Enable hardware VLAN strip.

Type:

Literal[True, None]

enable_hw_vlan_extend

Enable hardware VLAN extend.

Type:

Literal[True, None]

enable_hw_qinq_strip

Enable hardware QINQ strip.

Type:

Literal[True, None]

pkt_drop_enabled

Enable per-queue packet drop for packets with no descriptors.

Type:

Literal[True, None]

rss

Receive Side Scaling setting.

Type:

framework.params.testpmd.RSSSetting | None

forward_mode

Set the forwarding mode.

Type:

framework.params.testpmd.SimpleForwardingModes | framework.params.testpmd.FlowGenForwardingMode | framework.params.testpmd.TXOnlyForwardingMode | framework.params.testpmd.NoisyForwardingMode | None

hairpin_mode

Set the hairpin port configuration.

Type:

framework.params.testpmd.HairpinMode | None

hairpin_queues

Set the number of hairpin queues per port to N, where 1 <= N <= 65535.

Type:

int | None

burst

Set the number of packets per burst to N, where 1 <= N <= 512.

Type:

int | None

enable_rx_cksum

Enable hardware RX checksum offload.

Type:

Literal[True, None]

rx_queues

Set the number of RX queues per port to N, where 1 <= N <= 65535.

Type:

int | None

rx_ring

Set the RX rings parameters.

Type:

framework.params.testpmd.RXRingParams | None

no_flush_rx

Don’t flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.

Type:

Literal[True, None]

rx_segments_offsets

Set the offsets of packet segments on receiving if split feature is engaged.

Type:

list[int] | None

rx_segments_length

Set the length of segments to scatter packets on receiving if split feature is engaged.

Type:

list[int] | None

multi_rx_mempool

Enable multiple mbuf pools per Rx queue.

Type:

Literal[True, None]

rx_shared_queue

Create queues in shared Rx queue mode if device supports. Shared Rx queues are grouped per X ports. X defaults to UINT32_MAX, implies all ports join share group 1. Forwarding engine “shared-rxq” should be used for shared Rx queues. This engine does Rx only and update stream statistics accordingly.

Type:

Union[Literal[True, None], int]

rx_offloads

Set the bitmask of RX queue offloads.

Type:

int | None

rx_mq_mode

Set the RX multi queue mode which can be enabled.

Type:

framework.params.testpmd.RXMultiQueueMode | None

tx_queues

Set the number of TX queues per port to N, where 1 <= N <= 65535.

Type:

int | None

tx_ring

Set the TX rings params.

Type:

framework.params.testpmd.TXRingParams | None

tx_offloads

Set the hexadecimal bitmask of TX queue offloads.

Type:

int | None

eth_link_speed

Set a forced link speed to the ethernet port. E.g. 1000 for 1Gbps.

Type:

int | None

disable_link_check

Disable check on link status when starting/stopping ports.

Type:

Literal[True, None]

disable_device_start

Do not automatically start all ports. This allows testing configuration of rx and tx queues before device is started for the first time.

Type:

Literal[True, None]

no_lsc_interrupt

Disable LSC interrupts for all ports, even those supporting it.

Type:

Literal[True, None]

no_rmv_interrupt

Disable RMV interrupts for all ports, even those supporting it.

Type:

Literal[True, None]

bitrate_stats

Set the logical core N to perform bitrate calculation.

Type:

int | None

latencystats

Set the logical core N to perform latency and jitter calculations.

Type:

int | None

print_events

Enable printing the occurrence of the designated events. Using TestPmdEvent.ALL will enable all of them.

Type:

list[framework.params.testpmd.Event] | None

mask_events

Disable printing the occurrence of the designated events. Using TestPmdEvent.ALL will disable all of them.

Type:

list[framework.params.testpmd.Event] | None

flow_isolate_all

Providing this parameter requests flow API isolated mode on all ports at initialization time. It ensures all traffic is received through the configured flow rules only (see flow command). Ports that do not support this mode are automatically discarded.

Type:

Literal[True, None]

disable_flow_flush

Disable port flow flush when stopping port. This allows testing keep flow rules or shared flow objects across restart.

Type:

Literal[True, None]

hot_plug

Enable device event monitor mechanism for hotplug.

Type:

Literal[True, None]

vxlan_gpe_port

Set the UDP port number of tunnel VXLAN-GPE to N.

Type:

int | None

geneve_parsed_port

Set the UDP port number that is used for parsing the GENEVE protocol to N. HW may be configured with another tunnel Geneve port.

Type:

int | None

lock_all_memory

Enable/disable locking all memory. Disabled by default.

Type:

Literal[True, False, None]

mempool_allocation_mode

Set mempool allocation mode.

Type:

framework.params.testpmd.SimpleMempoolAllocationMode | framework.params.testpmd.AnonMempoolAllocationMode | None

record_core_cycles

Enable measurement of CPU cycles per packet.

Type:

Literal[True, None]

record_burst_status

Enable display of RX and TX burst stats.

Type:

Literal[True, None]

__init__(*, lcore_list: framework.testbed_model.cpu.LogicalCoreList | None = None, memory_channels: int | None = None, prefix: str = 'dpdk', no_pci: ~typing.Literal[True, None] = None, vdevs: list[framework.testbed_model.virtual_device.VirtualDevice] | None = None, allowed_ports: list[framework.testbed_model.port.Port] | None = None, blocked_ports: list[framework.testbed_model.port.Port] | None = None, other_eal_param: framework.params.Params | None = None, interactive_mode: ~typing.Literal[True, None] = True, auto_start: ~typing.Literal[True, None] = None, tx_first: ~typing.Literal[True, None] = None, stats_period: int | None = None, display_xstats: list[str] | None = None, nb_cores: int | None = None, coremask: int | None = None, nb_ports: int | None = None, port_topology: framework.params.testpmd.PortTopology | None = PortTopology.paired, portmask: int | None = None, portlist: str | None = None, numa: ~typing.Literal[True, False, None] = None, socket_num: int | None = None, port_numa_config: list[framework.params.testpmd.PortNUMAConfig] | None = None, ring_numa_config: list[framework.params.testpmd.RingNUMAConfig] | None = None, total_num_mbufs: int | None = None, mbuf_size: list[int] | None = None, mbcache: int | None = None, max_pkt_len: int | None = None, eth_peers_configfile: pathlib.PurePath | None = None, eth_peer: list[framework.params.testpmd.EthPeer] | None = None, tx_ip: framework.params.testpmd.TxIPAddrPair | None = None, tx_udp: framework.params.testpmd.TxUDPPortPair | None = None, enable_lro: ~typing.Literal[True, None] = None, max_lro_pkt_size: int | None = None, disable_crc_strip: ~typing.Literal[True, None] = None, enable_scatter: ~typing.Literal[True, None] = None, enable_hw_vlan: ~typing.Literal[True, None] = None, enable_hw_vlan_filter: ~typing.Literal[True, None] = None, enable_hw_vlan_strip: ~typing.Literal[True, None] = None, enable_hw_vlan_extend: ~typing.Literal[True, None] = None, enable_hw_qinq_strip: ~typing.Literal[True, None] = None, pkt_drop_enabled: ~typing.Literal[True, None] = None, rss: framework.params.testpmd.RSSSetting | None = None, forward_mode: framework.params.testpmd.SimpleForwardingModes | framework.params.testpmd.FlowGenForwardingMode | framework.params.testpmd.TXOnlyForwardingMode | framework.params.testpmd.NoisyForwardingMode | None = None, hairpin_mode: framework.params.testpmd.HairpinMode | None = None, hairpin_queues: int | None = None, burst: int | None = None, enable_rx_cksum: ~typing.Literal[True, None] = None, rx_queues: int | None = None, rx_ring: framework.params.testpmd.RXRingParams | None = None, no_flush_rx: ~typing.Literal[True, None] = None, rx_segments_offsets: list[int] | None = None, rx_segments_length: list[int] | None = None, multi_rx_mempool: ~typing.Literal[True, None] = None, rx_shared_queue: ~typing.Union[~typing.Literal[True, None], int] = None, rx_offloads: int | None = None, rx_mq_mode: framework.params.testpmd.RXMultiQueueMode | None = None, tx_queues: int | None = None, tx_ring: framework.params.testpmd.TXRingParams | None = None, tx_offloads: int | None = None, eth_link_speed: int | None = None, disable_link_check: ~typing.Literal[True, None] = None, disable_device_start: ~typing.Literal[True, None] = None, no_lsc_interrupt: ~typing.Literal[True, None] = None, no_rmv_interrupt: ~typing.Literal[True, None] = None, bitrate_stats: int | None = None, latencystats: int | None = None, print_events: list[framework.params.testpmd.Event] | None = None, mask_events: list[framework.params.testpmd.Event] | None = <factory>, flow_isolate_all: ~typing.Literal[True, None] = None, disable_flow_flush: ~typing.Literal[True, None] = None, hot_plug: ~typing.Literal[True, None] = None, vxlan_gpe_port: int | None = None, geneve_parsed_port: int | None = None, lock_all_memory: ~typing.Literal[True, False, None] = None, mempool_allocation_mode: framework.params.testpmd.SimpleMempoolAllocationMode | framework.params.testpmd.AnonMempoolAllocationMode | None = None, record_core_cycles: ~typing.Literal[True, None] = None, record_burst_status: ~typing.Literal[True, None] = None) → None