testpmd - Testpmd Interactive Remote Shell

Testpmd interactive shell.

Typical usage example in a TestSuite:

testpmd = TestPmd(self.sut_node)
devices = testpmd.get_devices()
for device in devices:
    print(device)
testpmd.close()
class TestPmd

Bases: DPDKShell

Testpmd interactive shell.

The testpmd shell users should never use the send_command() method directly, but rather call specialized methods. If there isn’t one that satisfies a need, it should be added.

ports_started

Indicates whether the ports are started.

Type:

bool

__init__(name: str | None = None, privileged: bool = True, **app_params: typing_extensions.Unpack.<class 'framework.params.types.TestPmdParamsDict'>) → None

Overrides __init__(). Changes app_params to kwargs.

property path: PurePath

The path to the testpmd executable.

property ports: list[api.testpmd.types.TestPmdPort]

The ports of the instance.

This caches the ports returned by show_port_info_all(). To force an update of port information, execute show_port_info_all() or show_port_info().

Returns: The list of known testpmd ports.

start(verify: bool = True) → None

Start packet forwarding with the current configuration.

Parameters:

verify (bool) – If True , a second start command will be sent in an attempt to verify packet forwarding started as expected.

Raises:

InteractiveCommandExecutionError – If verify is True and forwarding fails to start or ports fail to come up.

stop(verify: bool = True) → str

Stop packet forwarding.

Parameters:

verify (bool) – If True , the output of the stop command is scanned to verify that forwarding was stopped successfully or not started. If neither is found, it is considered an error.

Raises:

InteractiveCommandExecutionError – If verify is True and the command to stop forwarding results in an error.

Returns:

Output gathered from the stop command and all other preceding logs in the buffer. This output is most often used to view forwarding statistics that are displayed when this command is sent as well as any verbose packet information that hasn’t been consumed prior to calling this method.

Return type:

str

get_devices() → list[api.testpmd.types.TestPmdDevice]

Get a list of device names that are known to testpmd.

Uses the device info listed in testpmd and then parses the output.

Returns:

A list of devices.

Return type:

list[api.testpmd.types.TestPmdDevice]

Wait until the link status on the given port is “up”.

Parameters:

  • port_id (int) – Port to check the link status on.

  • timeout – Time to wait for the link to come up. The default value for this argument may be modified using the --timeout command-line argument or the DTS_TIMEOUT environment variable.

Returns:

Whether the link came up in time or not.

Return type:

bool

set_forward_mode(mode: SimpleForwardingModes, verify: bool = True) → None

Set packet forwarding mode.

Parameters:

  • mode (SimpleForwardingModes) – The forwarding mode to use.

  • verify (bool) – If True the output of the command will be scanned in an attempt to verify that the forwarding mode was set to mode properly.

Raises:

InteractiveCommandExecutionError – If verify is True and the forwarding mode fails to update.

stop_all_ports(verify: bool = True) → None

Stops all the ports.

Parameters:

verify (bool) – If True, the output of the command will be checked for a successful execution.

Raises:

InteractiveCommandExecutionError – If verify is True and the ports were not stopped successfully.

start_all_ports(verify: bool = True) → None

Starts all the ports.

Parameters:

verify (bool) – If True, the output of the command will be checked for a successful execution.

Raises:

InteractiveCommandExecutionError – If verify is True and the ports were not started successfully.

set_ports_queues(number_of: int) → None

Sets the number of queues per port.

Parameters:

number_of (int) – The number of RX/TX queues to create per port.

Raises:

InternalError – If number_of is invalid.

close_all_ports(verify: bool = True) → None

Close all ports.

Parameters:

verify (bool) – If True the output of the close command will be scanned in an attempt to verify that all ports were stopped successfully. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and at lease one port failed to close.

show_port_info_all() → list[api.testpmd.types.TestPmdPort]

Returns the information of all the ports.

Returns:

A list containing all the ports information as TestPmdPort.

Return type:

list[TestPmdPort]

show_port_info(port_id: int) → TestPmdPort

Returns the given port information.

Parameters:

port_id (int) – The port ID to gather information for.

Raises:

InteractiveCommandExecutionError – If port_id is invalid.

Returns:

An instance of TestPmdPort containing the given port’s information.

Return type:

TestPmdPort

set_mac_addr(port_id: int, mac_address: str, add: bool, verify: bool = True) → None

Add or remove a mac address on a given port’s Allowlist.

Parameters:

  • port_id (int) – The port ID the mac address is set on.

  • mac_address (str) – The mac address to be added to or removed from the specified port.

  • add (bool) – If True, add the specified mac address. If False, remove specified mac address.

  • verify (bool) – If :data:’True’, assert that the ‘mac_addr’ operation was successful. If :data:’False’, run the command and skip this assertion.

Raises:

InteractiveCommandExecutionError – If the set mac address operation fails.

set_multicast_mac_addr(port_id: int, multi_addr: str, add: bool, verify: bool = True) → None

Add or remove multicast mac address to a specified port’s allow list.

Parameters:

  • port_id (int) – The port ID the multicast address is set on.

  • multi_addr (str) – The multicast address to be added or removed from the filter.

  • add (bool) – If :data:’True’, add the specified multicast address to the port filter. If :data:’False’, remove the specified multicast address from the port filter.

  • verify (bool) – If :data:’True’, assert that the ‘mcast_addr’ operations was successful. If :data:’False’, execute the ‘mcast_addr’ operation and skip the assertion.

Raises:

InteractiveCommandExecutionError – If either the ‘add’ or ‘remove’ operations fails.

show_port_stats_all() → Tuple[list[api.testpmd.types.TestPmdPortStats], str]

Returns the statistics of all the ports.

Returns:

A tuple where the first element is the stats of all ports as TestPmdPortStats and second is the raw testpmd output that was collected from the sent command.

Return type:

Tuple[str, list[TestPmdPortStats]]

show_port_stats(port_id: int) → TestPmdPortStats

Returns the given port statistics.

Parameters:

port_id (int) – The port ID to gather information for.

Raises:

InteractiveCommandExecutionError – If port_id is invalid.

Returns:

An instance of TestPmdPortStats containing the given port’s stats.

Return type:

TestPmdPortStats

set_multicast_all(on: bool, verify: bool = True) → None

Turns multicast mode on/off for the specified port.

Parameters:

  • on (bool) – If True, turns multicast mode on, otherwise turns off.

  • verify (bool) – If True an additional command will be sent to verify that multicast mode is properly set. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and multicast mode is not properly set.

csum_set_hw(layers: ChecksumOffloadOptions, port_id: int, verify: bool = True) → None

Enables hardware checksum offloading on the specified layer.

Parameters:

  • layers (ChecksumOffloadOptions) – The layer/layers that checksum offloading should be enabled on.

  • port_id (int) – The port number to enable checksum offloading on, should be within 0-32.

  • verify (bool) – If True the output of the command will be scanned in an attempt to verify that checksum offloading was enabled on the port.

Raises:

InteractiveCommandExecutionError – If checksum offload is not enabled successfully.

flow_create(flow_rule: FlowRule, port_id: int) → int

Creates a flow rule in the testpmd session.

This command is implicitly verified as needed to return the created flow rule id.

Parameters:

  • flow_rule (FlowRule) – FlowRule object used for creating testpmd flow rule.

  • port_id (int) – Integer representing the port to use.

Raises:

InteractiveCommandExecutionError – If flow rule is invalid.

Returns:

Id of created flow rule.

Return type:

int

flow_validate(flow_rule: FlowRule, port_id: int) → bool

Validates a flow rule in the testpmd session.

Parameters:

  • flow_rule (FlowRule) – FlowRule object used for validating testpmd flow rule.

  • port_id (int) – Integer representing the port to use.

Returns:

Boolean representing whether rule is valid or not.

Return type:

bool

flow_delete(flow_id: int, port_id: int, verify: bool = True) → None

Deletes the specified flow rule from the testpmd session.

Parameters:

  • flow_id (int) – ID of the flow to remove.

  • port_id (int) – Integer representing the port to use.

  • verify (bool) – If True, the output of the command is scanned to ensure the flow rule was deleted successfully.

Raises:

InteractiveCommandExecutionError – If flow rule is invalid.

set_port_mtu(port_id: int, mtu: int, verify: bool = True) → None

Change the MTU of a port using testpmd.

Some PMDs require that the port be stopped before changing the MTU, and it does no harm to stop the port before configuring in cases where it isn’t required, so ports are stopped prior to changing their MTU. On the other hand, some PMDs require that the port had already been started once since testpmd startup. Therefore, ports are also started before stopping them to ensure this has happened.

Parameters:

  • port_id (int) – ID of the port to adjust the MTU on.

  • mtu (int) – Desired value for the MTU to be set to.

  • verify (bool) – If verify is True then the output will be scanned in an attempt to verify that the mtu was properly set on the port. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and the MTU was not properly updated on the port matching port_id.

set_port_mtu_all(mtu: int, verify: bool = True) → None

Change the MTU of all ports using testpmd.

Runs set_port_mtu() for every port that testpmd is aware of.

Parameters:

  • mtu (int) – Desired value for the MTU to be set to.

  • verify (bool) – Whether to verify that setting the MTU on each port was successful or not. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and the MTU was not properly updated on at least one port.

static extract_verbose_output(output: str) → list[api.testpmd.types.TestPmdVerbosePacket]

Extract the verbose information present in given testpmd output.

This method extracts sections of verbose output that begin with the line “port X/queue Y: sent/received Z packets” and end with the ol_flags of a packet.

Parameters:

output (str) – Testpmd output that contains verbose information

Returns:

List of parsed packet information gathered from verbose information in output.

Return type:

list[api.testpmd.types.TestPmdVerbosePacket]

set_vlan_filter(port: int, enable: bool, verify: bool = True) → None

Set vlan filter on.

Parameters:

  • port (int) – The port number to enable VLAN filter on.

  • enable (bool) – Enable the filter on port if True, otherwise disable it.

  • verify (bool) – If True, the output of the command and show port info is scanned to verify that vlan filtering was set successfully.

Raises:

InteractiveCommandExecutionError – If verify is True and the filter fails to update.

set_mac_address(port: int, mac_address: str, verify: bool = True) → None

Set port’s MAC address.

Parameters:

  • port (int) – The number of the requested port.

  • mac_address (str) – The MAC address to set.

  • verify (bool) – If True, the output of the command is scanned to verify that the mac address is set in the specified port.

Raises:

InteractiveCommandExecutionError – If verify is True and the command fails to execute.

set_flow_control(port: int, flow_ctrl: TestPmdPortFlowCtrl, verify: bool = True) → None

Set the given port’s flow control.

Parameters:

  • port (int) – The number of the requested port.

  • flow_ctrl (TestPmdPortFlowCtrl) – The requested flow control parameters.

  • verify (bool) – If True, the output of the command is scanned to verify that the flow control in the specified port is set.

Raises:

InteractiveCommandExecutionError – If verify is True and the command fails to execute.

show_port_flow_info(port: int) → api.testpmd.types.TestPmdPortFlowCtrl | None

Show port info flow.

Parameters:

port (int) – The number of the requested port.

Returns:

The current port flow control parameters if supported, otherwise None.

Return type:

api.testpmd.types.TestPmdPortFlowCtrl | None

rx_vlan(vlan: int, port: int, add: bool, verify: bool = True) → None

Add specified vlan tag to the filter list on a port. Requires vlan filter to be on.

Parameters:

  • vlan (int) – The vlan tag to add, should be within 1-1005.

  • port (int) – The port number to add the tag on.

  • add (bool) – Adds the tag if True, otherwise removes the tag.

  • verify (bool) – If True, the output of the command is scanned to verify that the vlan tag was added to the filter list on the specified port.

Raises:

InteractiveCommandExecutionError – If verify is True and the tag is not added.

set_vlan_strip(port: int, enable: bool, verify: bool = True) → None

Enable or disable vlan stripping on the specified port.

Parameters:

  • port (int) – The port number to use.

  • enable (bool) – If True, will turn vlan stripping on, otherwise will turn off.

  • verify (bool) – If True, the output of the command and show port info is scanned to verify that vlan stripping was enabled on the specified port.

Raises:

InteractiveCommandExecutionError – If verify is True and stripping fails to update.

tx_vlan_set(port: int, enable: bool, vlan: int | None = None, verify: bool = True) → None

Set hardware insertion of vlan tags in packets sent on a port.

Parameters:

  • port (int) – The port number to use.

  • enable (bool) – Sets vlan tag insertion if True, and resets if False.

  • vlan (int | None) – The vlan tag to insert if enable is True.

  • verify (bool) – If True, the output of the command is scanned to verify that vlan insertion was enabled on the specified port.

Raises:

InteractiveCommandExecutionError – If verify is True and the insertion tag is not set.

set_promisc(port: int, enable: bool, verify: bool = True) → None

Enable or disable promiscuous mode for the specified port.

Parameters:

  • port (int) – Port number to use.

  • enable (bool) – If True, turn promiscuous mode on, otherwise turn off.

  • verify (bool) – If True an additional command will be sent to verify that promiscuous mode is properly set. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and promiscuous mode is not correctly set.

set_verbose(level: int, verify: bool = True) → None

Set debug verbosity level.

Parameters:

  • level (int) – 0 - silent except for error 1 - fully verbose except for Tx packets 2 - fully verbose except for Rx packets >2 - fully verbose

  • verify (bool) – If True the command output will be scanned to verify that verbose level is properly set. Defaults to True.

Raises:
rx_vxlan(vxlan_id: int, port_id: int, enable: bool, verify: bool = True) → None

Add or remove vxlan id to/from filter list.

Parameters:

  • vxlan_id (int) – VXLAN ID to add to port filter list.

  • port_id (int) – ID of the port to modify VXLAN filter of.

  • enable (bool) – If True, adds specified VXLAN ID, otherwise removes it.

  • verify (bool) – If True, the output of the command is checked to verify the VXLAN ID was successfully added/removed from the port.

Raises:

InteractiveCommandExecutionError – If verify is True and VXLAN ID is not successfully added or removed.

clear_port_stats(port_id: int, verify: bool = True) → None

Clear statistics of a given port.

Parameters:

  • port_id (int) – ID of the port to clear the statistics on.

  • verify (bool) – If True the output of the command will be scanned to verify that it was successful, otherwise failures will be ignored. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and testpmd fails to clear the statistics of the given port.

clear_port_stats_all(verify: bool = True) → None

Clear the statistics of all ports that testpmd is aware of.

Parameters:

verify (bool) – If True the output of the command will be scanned to verify that all ports had their statistics cleared, otherwise failures will be ignored. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and testpmd fails to clear the statistics of any of its ports.

get_capabilities_rx_offload(supported_capabilities: MutableSet[NicCapability], unsupported_capabilities: MutableSet[NicCapability]) → None

Get all rx offload capabilities and divide them into supported and unsupported.

Parameters:

  • supported_capabilities (MutableSet[NicCapability]) – Supported capabilities will be added to this set.

  • unsupported_capabilities (MutableSet[NicCapability]) – Unsupported capabilities will be added to this set.

get_port_queue_info(port_id: int, queue_id: int, is_rx_queue: bool) → TestPmdQueueInfo

Returns the current state of the specified queue.

setup_port_queue(port_id: int, queue_id: int, is_rx_queue: bool) → None

Setup a given queue on a port.

This functionality cannot be verified because the setup action only takes effect when the queue is started.

Parameters:

  • port_id (int) – ID of the port where the queue resides.

  • queue_id (int) – ID of the queue to setup.

  • is_rx_queue (bool) – Type of queue to setup. If True an RX queue will be setup, otherwise a TX queue will be setup.

stop_port_queue(port_id: int, queue_id: int, is_rx_queue: bool, verify: bool = True) → None

Stops a given queue on a port.

Parameters:

  • port_id (int) – ID of the port that the queue belongs to.

  • queue_id (int) – ID of the queue to stop.

  • is_rx_queue (bool) – Type of queue to stop. If True an RX queue will be stopped, otherwise a TX queue will be stopped.

  • verify (bool) – If True an additional command will be sent to verify the queue stopped. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and the queue fails to stop.

start_port_queue(port_id: int, queue_id: int, is_rx_queue: bool, verify: bool = True) → None

Starts a given queue on a port.

First sets up the port queue, then starts it.

Parameters:

  • port_id (int) – ID of the port that the queue belongs to.

  • queue_id (int) – ID of the queue to start.

  • is_rx_queue (bool) – Type of queue to start. If True an RX queue will be started, otherwise a TX queue will be started.

  • verify (bool) – if True an additional command will be sent to verify that the queue was started. Defaults to True.

Raises:

InteractiveCommandExecutionError – If verify is True and the queue fails to start.

get_queue_ring_size(port_id: int, queue_id: int, is_rx_queue: bool) → int

Returns the current size of the ring on the specified queue.

set_queue_ring_size(port_id: int, queue_id: int, size: int, is_rx_queue: bool, verify: bool = True) → None

Update the ring size of an Rx/Tx queue on a given port.

Queue is setup after setting the ring size so that the queue info reflects this change and it can be verified.

Parameters:

  • port_id (int) – The port that the queue resides on.

  • queue_id (int) – The ID of the queue on the port.

  • size (int) – The size to update the ring size to.

  • is_rx_queue (bool) – Whether to modify an RX or TX queue. If True an RX queue will be updated, otherwise a TX queue will be updated.

  • verify (bool) – If True an additional command will be sent to check the ring size of the queue in an attempt to validate that the size was changes properly.

Raises:

InteractiveCommandExecutionError – If verify is True and there is a failure when updating ring size.

set_queue_deferred_start(port_id: int, queue_id: int, is_rx_queue: bool, on: bool) → None

Set the deferred start attribute of the specified queue on/off.

Parameters:

  • port_id (int) – The port that the queue resides on.

  • queue_id (int) – The ID of the queue on the port.

  • is_rx_queue (bool) – Whether to modify an RX or TX queue. If True an RX queue will be updated, otherwise a TX queue will be updated.

  • on (bool) – Whether to set deferred start mode on or off. If True deferred start will be turned on, otherwise it will be turned off.

get_capabilities_rxq_info(supported_capabilities: MutableSet[NicCapability], unsupported_capabilities: MutableSet[NicCapability]) → None

Get all rxq capabilities and divide them into supported and unsupported.

Parameters:

  • supported_capabilities (MutableSet[NicCapability]) – Supported capabilities will be added to this set.

  • unsupported_capabilities (MutableSet[NicCapability]) – Unsupported capabilities will be added to this set.

get_capabilities_show_port_info(supported_capabilities: MutableSet[NicCapability], unsupported_capabilities: MutableSet[NicCapability]) → None

Get all capabilities from show port info and divide them into supported and unsupported.

Parameters:

  • supported_capabilities (MutableSet[NicCapability]) – Supported capabilities will be added to this set.

  • unsupported_capabilities (MutableSet[NicCapability]) – Unsupported capabilities will be added to this set.

get_capabilities_mcast_filtering(supported_capabilities: MutableSet[NicCapability], unsupported_capabilities: MutableSet[NicCapability]) → None

Get multicast filtering capability from mcast_addr add and check for testpmd error code.

Parameters:

  • supported_capabilities (MutableSet[NicCapability]) – Supported capabilities will be added to this set.

  • unsupported_capabilities (MutableSet[NicCapability]) – Unsupported capabilities will be added to this set.

get_capabilities_flow_ctrl(supported_capabilities: MutableSet[NicCapability], unsupported_capabilities: MutableSet[NicCapability]) → None

Get flow control capability and check for testpmd failure.

Parameters:

  • supported_capabilities (MutableSet[NicCapability]) – Supported capabilities will be added to this set.

  • unsupported_capabilities (MutableSet[NicCapability]) – Unsupported capabilities will be added to this set.

get_capabilities_physical_function(supported_capabilities: MutableSet[NicCapability], unsupported_capabilities: MutableSet[NicCapability]) → None

Store capability representing a physical function test run.

Parameters:

  • supported_capabilities (MutableSet[NicCapability]) – Supported capabilities will be added to this set.

  • unsupported_capabilities (MutableSet[NicCapability]) – Unsupported capabilities will be added to this set.