Virtnet CLI Commands

User Front End CLI

To communicate with the virtio-net-controller backend service, a user frontend program, virtnet, is installed on the BlueField which is based on r emote procedure call (RPC) protocol with JSON format output. Run the following command to check its usage:

Copy
Copied!

            
            # virtnet -h usage: virtnet [-h] [-v]
               {hotplug,unplug,list,query,modify,log,version,update,debug} ...
 
NVIDIA virtio-net-controller command line interface v1.9.13
 
positional arguments:
  {hotplug,unplug,list,query,modify,log,version,update,debug}
                        ** Use -h for sub-command usage
    hotplug             hotplug virtnet device
    unplug              unplug virtnet device
    list                list all virtnet devices
    query               query all or individual virtnet device(s)
    modify              modify virtnet device
    log                 set log level
    version             show virtio net controller version info
    update              update controller
    debug               For debug purpose, cmds can be changed without notice
 
optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

Virtnet supports command line autocomplete by inputting one command with tab.

To check the currently running controller version:

Copy
Copied!

            
            # virtnet -v
v1.9.16

Hotplug

This command hotplugs a virtio-net PCIe PF device exposed to the host side.

Syntax

Copy
Copied!

            
            virtnet hotplug -i IB_DEVICE -m MAC -t MTU -n MAX_QUEUES -s MAX_QUEUE_SIZE [-h] [-u SF_NUM] [-f FEATURES] [-l]

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit
`--ib_device`	`-i`	String	Yes	RDMA device (e.g., `mlx5_0`) of the physical port on top of which the hotplug device is created. Options: `mlx5_0` – port 1 `mlx5_1` – port 2 `mlx5_bond_0` – LAG
`--features`	`-f`	Hex Number	No	Feature bits to be enabled in hex format. Refer to the "Virtio-net Feature Bits" page. Note Note that some features are enabled by default. Query the device to show the supported bits.
`--mac`	`-m`	Number	Yes	MAC address of the virtio-net device. Note Controller does not validate the MAC address (other than its length). The user must ensure MAC is valid and unique.
`--mtu`	`-t`	Number	Yes	Maximum transmission unit (MTU) size of the virtio-net device. It must be less than the uplink rep MTU size.
`--max_queues`	`-n`	Number	Yes	Max number of virt queues could be created for the virtio-net device. TX, RX, ctrl queues are counted separately (e.g., 3 has 1 TX VQ, 1 RX VQ, 1 Ctrl VQ).
`--max_queue_size`	`-s`	Number	Yes	Maximum number of buffers in the virt queue, between 0x4 and 0x8000. Must be power of 2.
`--sf_num`	`-u`	Number	No	SF number to be used for this hotplug device, must between 2000 and 2999.
`--legacy`	`-l`	N/A	No	Create legacy (transitional) hotplug device

Output

Entry	Type	Description
`bdf`	String	The PCIe BDF (bus:device:function) number enumerated by host. The user should see this PCIe device from host side.
`vuid`	String	Unique device SN. It can be used as an index to query/modify/unplug this device.
`id`	Num	Unique device ID. It can be used as an index to query/modify/unplug this device.
`transitional`	Num	Is the current device a transitional hotplug device. 0 – modern device 1 – transitional device
`sf_rep_net_device`	String	The SF representor name represents the virtio-net device. It should be added into the OVS bridge.
`mac`	String	The hotplug virtio-net device MAC address
`errno`	Num	Error number if hotplug failed. 0 – success non-0 – failed
`errstr`	String	Explanation of the error number

Example

Hotplug one device with MAC address 0C:C4:7A:FF:22:93, MTU 1500, and 3 virtio queues (1 tx, 1 rx, 1 ctrl) with a depth of 1024 entries. The device is created on the physical port of mlx5_0.

Copy
Copied!

            
            # virtnet hotplug -i mlx5_0 -f 0x80000 -m 0C:C4:7A:FF:22:93 -t 1500 -n 3 -s 1024
{
  "bdf": "15:00.0",
  "vuid": "MT2151X03152VNETS1D0F0",
  "id": 0,
  "transitional": 0,
  "sf_rep_net_device": "en3f0pf0sf2000",
  "mac": "0C:C4:7A:FF:22:93",
  "errno": 0,
  "errstr": "Success"
}

Unplug

This command unplugs a virtio-net PCIe PF device.

Syntax

Copy
Copied!

            
            virtnet unplug [-h] [-p PF | -u VUID]

Only one of --pf and --vuid is needed to unplug the device.

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit
`--pf`	`-p`	Number	Yes	Unique device ID returned when doing hotplug. Can be retrieved by using `virtnet list`.
`--vuid`	`-u`	String	Yes	Unique device SN returned when doing hotplug. Can be retrieved by using `virtnet list`.

Output

Entry	Type	Description
`errno`	Num	Error number if operation failed 0 – success non-0 – failed
`errstr`	String	Explanation of the error number

Entry

Type

Description

errno

Num

Error number if operation failed

0 – success
non-0 – failed

errstr

String

Explanation of the error number

Example

Unplug hotplug device using the PF ID:

Copy
Copied!

            
            # virtnet unplug -p 0
{'id': '0x1'}
{
  "errno": 0,
  "errstr": "Success"
}

List

This command lists all existing virtio-net devices, with global information and individual information for each device.

Syntax

Copy
Copied!

            
            virtnet list [-h]

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit

Output

The output has two main sections. The first section wrapped by the controller are global configurations and capabilities.

Entry	Type	Description
`controller`	String	Entries under this section is global information for the controller
`emulation_manager`	String	The RDMA device manager used to manage internal resources. Should be default `mlx5_0`.
`max_hotplug_devices`	String	Maximum number of devices that can be hotpluged
`max_virt_net_devices`	String	Total number of emulated devices managed by the device emulation manager
`max_virt_queues`	String	Maximum number of virt queues supported per device
`max_tunnel_descriptors`	String	Maximum number of descriptors the device can send in a single tunnel request
`supported_features`	String	Total list of features supported by device
`supported_virt_queue_types`	String	Currently supported virt queue types: Packed and Split
`supported_event_modes`	String	Currently supported event modes: `no_msix_mode`, `qp_mode`, `msix_mode`

Each device has its own section under devices.

Entry	Type	Description
`devices`	String	Entries under this section is per device information
`pf_id`	String	Physical function ID
`function_type`	String	Function type: Static PF, hotplug PF, VF
`transitional`	Number	The current device a transitional hotplug device: 0 – modern device 1 – transitional device
`vuid`	String	Unique device SN, it can be used as an index to query/modify/unplug a device
`msix_num_pool_size`	Number	Number of free dynamic MSIX available for the VFs on this PF
`min_msix_num`	Number	The minimum number of dynamic MSI-Xs that can be set for an virtio-net VF
`max_msix_num`	Number	The maximum number of dynamic MSI-Xs that can be set for an virtio-net VF
`bdf`	String	Bus:device:function to describe the virtio-net PCIe device
`sf_num`	Number	Scalable function number used for this virtio-net device
`sf_parent_device`	String	The RDMA device to be used to create the SF
`sf_parent_device_pci_addr`	String	The PCIe device address (bus:device:function) to be used to create the SF
`sf_rep_net_device`	String	The SF rep net device name represents the virtio-net device
`sf_rep_net_ifindex`	Number	The SF rep net interface index
`sf_rdma_device`	String	The SF RDMA device interface name
`sf_vhca_id`	String	Virtual HCA identifier for the SF. This is normally used for internal information.
`msix_config_vector`	String	MSIX vector number which is used for virtio config space
`num_msix`	Number	Maximum number of MSI-X available for this device
`max_queues`	Number	Maximum virtual queues can be created for this device, driver can choose to create less
`max_queues_size`	Number	Maximum virtual queue depth in byte can be created for each VQ, driver can use less
`net_mac`	String	The virtio-net device MAC address
`net_mtu`	Number	The virtio-net device MTU, default 1500
`speed`	Number	The virtio-net device link speed in Mb/s
`supported_hash_types`	Number	Supported hash types for this device in hex. Only applicable when `VIRTIO_NET_F_HASH_REPORT` is enabled: `VIRTIO_NET_HASH_TYPE_IPv4 (bit 0)` `VIRTIO_NET_HASH_TYPE_TCPv4 (bit 1)` `VIRTIO_NET_HASH_TYPE_UDPv4 (bit 2)` `VIRTIO_NET_HASH_TYPE_IPv6 (bit 3)` `VIRTIO_NET_HASH_TYPE_TCPv6 (bit 4)` `VIRTIO_NET_HASH_TYPE_UDPv6 (bit 5)`
`rss_max_key_size`	Number	The maximum supported length of RSS key. Only applicable when `VIRTIO_NET_F_RSS` or `VIRTIO_NET_F_HASH_REPORT` is enabled.

Example

The following is an example of a list with 1 static PF created:

Copy
Copied!

            
            # virtnet list
{
  "controller": {
    "emulation_manager": "mlx5_0",
    "max_hotplug_devices": "3",
    "max_virt_net_devices": "4",
    "max_virt_queues": "64",
    "max_tunnel_descriptors": "6",
    "supported_features": {
      "value": "0x8b30037700ef982f",
      "    0": "VIRTIO_NET_F_CSUM",
      "    1": "VIRTIO_NET_F_GUEST_CSUM",
      "    2": "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS",
      "    3": "VIRTIO_NET_F_MTU",
      "    5": "VIRTIO_NET_F_MAC",
      "   11": "VIRTIO_NET_F_HOST_TSO4",
      "   12": "VIRTIO_NET_F_HOST_TSO6",
      "   15": "VIRTIO_F_MRG_RX_BUFFER",
      "   16": "VIRTIO_NET_F_STATUS",
      "   17": "VIRTIO_NET_F_CTRL_VQ",
      "   18": "VIRTIO_NET_F_CTRL_RX",
      "   19": "VIRTIO_NET_F_CTRL_VLAN",
      "   21": "VIRTIO_NET_F_GUEST_ANNOUNCE",
      "   22": "VIRTIO_NET_F_MQ",
      "   23": "VIRTIO_NET_F_CTRL_MAC_ADDR",
      "   32": "VIRTIO_F_VERSION_1",
      "   33": "VIRTIO_F_IOMMU_PLATFORM",
      "   34": "VIRTIO_F_RING_PACKED",
      "   36": "VIRTIO_F_ORDER_PLATFORM",
      "   37": "VIRTIO_F_SR_IOV",
      "   38": "VIRTIO_F_NOTIFICATION_DATA",
      "   40": "VIRTIO_F_RING_RESET",
      "   41": "VIRTIO_F_ADMIN_VQ",
      "   52": "VIRTIO_NET_F_VQ_NOTF_COAL",
      "   53": "VIRTIO_NET_F_NOTF_COAL",
      "   56": "VIRTIO_NET_F_HOST_USO",
      "   57": "VIRTIO_NET_F_HASH_REPORT",
      "   59": "VIRTIO_NET_F_GUEST_HDRLEN",
      "   63": "VIRTIO_NET_F_SPEED_DUPLEX"
    },
    "supported_virt_queue_types": {
      "value": "0x1",
      "    0": "SPLIT"
    },
    "supported_event_modes": {
      "value": "0x5",
      "    0": "NO_MSIX_MODE",
      "    2": "MSIX_MODE"
    }
  },
  "devices": [
    {
      "pf_id": 0,
      "function_type": "static PF",
      "transitional": 0,
      "vuid": "MT2349X00017VNETS0D0F1",
      "msix_num_pool_size": 0,
      "min_msix_num": 0,
      "max_msix_num": 64,
      "bdf": "39:00.1",
      "sf_num": 1000,
      "sf_parent_device": "mlx5_0",
      "sf_parent_device_pci_addr": "0000:03:00.0",
      "sf_rep_net_device": "en3f0pf0sf1000",
      "sf_rep_net_ifindex": 10,
      "sf_rdma_device": "mlx5_2",
      "sf_vhca_id": "0x4C",
      "msix_config_vector": "0x0",
      "num_msix": 64,
      "max_queues": 63,
      "max_queues_size": 256,
      "net_mac": "52:0C:6A:4F:80:66",
      "net_mtu": 1500,
      "speed": 25000,
      "supported_hash_types": 0,
      "rss_max_key_size": 0
    }
  ]
}

Query

This command queries detailed information for a given device, including all VQ information if created.

Syntax

Copy
Copied!

            
            virtnet query [-h] {[-a] | [-p PF] [-v VF] | [-u VUID]} [--dbg_stats] [-b] [--latency_stats] [-q QUEUE_ID] [--stats_clear]

Info

The options --pf , --vf , --vuid , and --all are mutually exclusive, but one of them must be applied.

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit
`--all`	`-a`	N/A	No	Query all the detailed information for all available devices. It can be time consuming if a large number of devices is available.
`--pf`	`-p`	Number	No	Unique device ID for the PF. Can be retrieved by using `virtnet list`.
`--vf`	`-v`	Number	No	Unique device ID for the VF. Can be retrieved by using `virtnet list`.
`--vuid`	`-u`	String	No	Unique device SN for the device (PF/VF). Can be retrieved by using `virtnet list`.
`--queue_id`	`-q`	Number	No	Queue index of the device VQs
`--brief`	`-b`	N/A	No	Query brief information of the device (does not print VQ information)
`--dbg_stats`	N/A	N/A	No	Print debug counters and information Note May be depreciated in the future.
`--stats_clear`	N/A	N/A	No	Clear all the debug counter stats Note May be depreciated in the future.

Output

Output has two main sections.

The first section wrapped by devices are configuration and capabilities in device level.

Entry	Type	Description
`devices`	String	Entries under this section is per device information
`pf_id`	String	Physical function ID
`transitional`	Number	Is the current device a transitional hotplug device 0 – modern device 1 – transitional device
`vuid`	String	Unique device SN. Can be used as an index to query/modify/unplug a device.
`pci_bdf`	String	Bus:device:function to describe the virtio-net PCIe device
`pci_dev_id`	String	Virtio-net PCIe device ID. Default: 0x1041. Note May be depreciated in the future.
`pci_vendor_id`	String	Virtio-net PCIe vendor ID. Default: 0x1af4. Note May be depreciated in the future.
`pci_class_code`	String	Virtio-net PCIe device class code. Default: 0x20000. Note May be depreciated in the future.
`pci_subsys_id`	String	Virtio-net PCIe vendor ID. Default: 0x1041. Note May be depreciated in the future.
`pci_subsys_vendor_id`	String	Virtio-net PCIe sub-system vendor ID. Default: 0x1af4. Note May be depreciated in the future.
`pci_revision_id`	String	Virtio-net PCIe revision ID. Default: 1. Note May be depreciated in the future.
`pci_max_vfs`	Number	Maximum number of virtio-net virtual functions can be created for this PF. Valid only for PFs.
`enabled_vfs`	Number	Currently enabled number of virtio-net virtual functions for this PF
`device_features`	String	Enabled device feature bits according to virtio spec
`driver_features`	String	Enabled driver feature bits according to virtio spec. Valid only when driver probes the device.
`status`	String	Device status field bit masks according to virtio spec `ACKNOWLEDGE (bit 0)` `DRIVER (bit 1)` `DRIVER_OK (bit 2)` `FEATURES_OK (bit 3)` `DEVICE_NEEDS_RESET (bit 6)` `FAILED (bit 7)`
`msix_config_vector`	String	MSI-X vector number which is used for virtio config space
`num_msix`	Number	Maximum number of MSI-X available for this device
`max_queues`	Number	Maximum virtual queues can be created for this device, driver can choose to create less
`enabled_queues`	Number	Currently enabled virtual queues by driver
`pci_vhca_id`	Number	Virtual HCA identifier for the general virtio-net device. This is normally used for internal information.
`enabled`	Number	Is the current virtio-net device enabled? May be 0 or 1. 0 means that FLR has occurred for the device.
`reset`	Number	Is the current virtio-net device undergoing reset? May be 0 or 1.
`net_link_status`	Number	Link status of the virtio-net device on the host side. 0 – down 1 – up
`net_mac`	Number	The virtio-net device MAC address
`net_max_queue_pairs`	Number	Maximum number of data VQ pairs. One VQ pair has one TX queue and one RX queue. It does not count control or admin VQ. Normally equal to `ethtool -l <virtio-dev>`.
`net_mtu`	Number	The virtio-net device MTU. Default: 1500.
`speed`	Number	The virtio-net device link speed in Mb/s
`supported_hash_types`	Number	Supported hash types for this device in hex. Only applicable when `VIRTIO_NET_F_HASH_REPORT` is enabled. `VIRTIO_NET_HASH_TYPE_IPv4 (bit 0)` `VIRTIO_NET_HASH_TYPE_TCPv4 (bit 1)` `VIRTIO_NET_HASH_TYPE_UDPv4 (bit 2)` `VIRTIO_NET_HASH_TYPE_IPv6 (bit 3)` `VIRTIO_NET_HASH_TYPE_TCPv6 (bit 4)` `VIRTIO_NET_HASH_TYPE_UDPv6 (bit 5)`
`rss_max_key_size`	Number	The maximum supported length of RSS key. Only applicable when `VIRTIO_NET_F_RSS` or `VIRTIO_NET_F_HASH_REPORT` is enabled.
`sf_num`	Number	Sub function number used for this virtio-net device
`sf_parent_device_pci_addr`	String	The PCI device address (bus:device:function) to be used to create the SF
`sf_rep_net_device`	String	The SF rep net device name represents the virtio-net device
`sf_rep_net_ifindex`	Number	The SF rep net interface index
`sf_rdma_device`	String	The SF RDMA device interface name
`sf_cross_mkey`	Number	The cross device MKEY created for SF
`sf_vhca_id`	Number	Virtual HCA identifier for the SF. This is normally used for internal information.
`rqt_num`	Number	The RQ table ID used for this virtio-net device

The second section wrapped by enabled-queues-info are information for each VQ.

Entry	Type	Description
`index`	Number	VQ index starting from 0 to `enabled_queues`
`size`	Number	Driver VQ depth in bytes. It is bounded by device `max_queues_size` .
`msix_vector`	Number	The MSI-X vector number used for this VQ
`enable`	Number	If current VQ is enabled or not 0 – disabled 1 – enabled
`notify_offset`	Number	Driver reads this to calculate the offset from start of notification structure at which this virtqueue is located
`descriptor_address`	Number	The driver writes the physical address of descriptor area
`driver_address`	Number	The driver writes the physical address of driver area
`device_address`	Number	The driver writes the physical address of device area
`received_desc`	Number	Total number of received descriptors by the device on this VQ
`completed_desc`	Number	Total number of completed descriptors by the device on this VQ
`bad_desc_errors`	Number	Total number of bad descriptors received on this VQ
`error_cqes`	Number	Total number of error CQ entries on this VQ
`exceed_max_chain`	Number	Total number of chained descriptors received that exceed the max allowed chain by device
`invalid_buffer`	Number	Total number of times device tried to read or write buffer that is not registered to the device
`batch_number`	Number	The number of RX decriptors for the last received packet. Valid for DPA.
`dma_q_used_number`	Number	The dma q index used for this VQ. Valid for DPA.
`handler_schd_number`	Number	Scheduler number for this VQ. Valid for DPA.
`aux_handler_schd_number`	Number	Aux scheduler number for this VQ. Valid for DPA.
`max_post_desc_number`	Number	Maximum number of posted descriptors on this VQ. Valid for DPA.
`total_bytes`	Number	Total number of bytes handled by this VQ. Valid for DPA.
`rq_cq_max_count`	Number	Event generation moderation counter of the queue. Valid for RQ.
`rq_cq_period`	Number	Event generation moderation timer for the queue in 1 µ sec granularity. Valid for RQ.
`rq_cq_period_mode`	Number	Current period mode for RQ 0x0 – `default_mode` – use device best defaults 0x1 – `upon_event` – `queue_period` timer restarts upon event generation 0x2 – `upon_cqe` – `queue_period` timer restarts upon completion generation

Example

The following is an example of querying the information of first PF:

Copy
Copied!

            
            # virtnet query -p 0
{
  "devices": [
    {
      "pf_id": 0,
      "transitional": 0,
      "vuid": "MT2349X00017VNETS0D0F1",
      "pci_bdf": "39:00.1",
      "pci_dev_id": "0x1041",
      "pci_vendor_id": "0x1af4",
      "pci_class_code": "0x20000",
      "pci_subsys_id": "0x1041",
      "pci_subsys_vendor_id": "0x1af4",
      "pci_revision_id": "1",
      "pci_max_vfs": "0",
      "enabled_vfs": "0",
      "device_feature": {
        "value": "0x8930032300e7182f",
        "    0": "VIRTIO_NET_F_CSUM",
        "    1": "VIRTIO_NET_F_GUEST_CSUM",
        "    2": "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS",
        "    3": "VIRTIO_NET_F_MTU",
        "    5": "VIRTIO_NET_F_MAC",
        "   11": "VIRTIO_NET_F_HOST_TSO4",
        "   12": "VIRTIO_NET_F_HOST_TSO6",
        "   16": "VIRTIO_NET_F_STATUS",
        "   17": "VIRTIO_NET_F_CTRL_VQ",
        "   18": "VIRTIO_NET_F_CTRL_RX",
        "   21": "VIRTIO_NET_F_GUEST_ANNOUNCE",
        "   22": "VIRTIO_NET_F_MQ",
        "   23": "VIRTIO_NET_F_CTRL_MAC_ADDR",
        "   32": "VIRTIO_F_VERSION_1",
        "   33": "VIRTIO_F_IOMMU_PLATFORM",
        "   37": "VIRTIO_F_SR_IOV",
        "   40": "VIRTIO_F_RING_RESET",
        "   41": "VIRTIO_F_ADMIN_VQ",
        "   52": "VIRTIO_NET_F_VQ_NOTF_COAL",
        "   53": "VIRTIO_NET_F_NOTF_COAL",
        "   56": "VIRTIO_NET_F_HOST_USO",
        "   59": "VIRTIO_NET_F_GUEST_HDRLEN",
        "   63": "VIRTIO_NET_F_SPEED_DUPLEX"
      },
      "driver_feature": {
        "value": "0x8000002300e7182f",
        "    0": "VIRTIO_NET_F_CSUM",
        "    1": "VIRTIO_NET_F_GUEST_CSUM",
        "    2": "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS",
        "    3": "VIRTIO_NET_F_MTU",
        "    5": "VIRTIO_NET_F_MAC",
        "   11": "VIRTIO_NET_F_HOST_TSO4",
        "   12": "VIRTIO_NET_F_HOST_TSO6",
        "   16": "VIRTIO_NET_F_STATUS",
        "   17": "VIRTIO_NET_F_CTRL_VQ",
        "   18": "VIRTIO_NET_F_CTRL_RX",
        "   21": "VIRTIO_NET_F_GUEST_ANNOUNCE",
        "   22": "VIRTIO_NET_F_MQ",
        "   23": "VIRTIO_NET_F_CTRL_MAC_ADDR",
        "   32": "VIRTIO_F_VERSION_1",
        "   33": "VIRTIO_F_IOMMU_PLATFORM",
        "   37": "VIRTIO_F_SR_IOV",
        "   63": "VIRTIO_NET_F_SPEED_DUPLEX"
      },
      "status": {
        "value": "0xf",
        "    0": "ACK",
        "    1": "DRIVER",
        "    2": "DRIVER_OK",
        "    3": "FEATURES_OK"
      },
      "msix_config_vector": "0x0",
      "num_msix": "64",
      "max_queues": "63",
      "enabled_queues": "63",
      "pci_vhca_id": "0x1",
      "enabled": "1",
      "reset": "0",
      "net_link_status": "1",
      "net_mac": "52:0C:6A:4F:80:66",
      "net_max_queue_pairs": "31",
      "net_mtu": "1500",
      "speed": "25000",
      "supported_hash_types": "0x0",
      "rss_max_key_size": "0",
      "sf_num": 1000,
      "sf_parent_device_pci_addr": "0000:03:00.0",
      "sf_rep_net_device": "en3f0pf0sf1000",
      "sf_rep_net_ifindex": 10,
      "sf_rdma_device": "mlx5_2",
      "sf_cross_mkey": "0x19242",
      "sf_vhca_id": "0x4C",
      "rqt_num": "0x0",
      "enabled-queues-info": [
        {
          "index": "0",
          "size": "256",
          "msix_vector": "0x1",
          "enable": "1",
          "notify_offset": "0",
          "descriptor_address": "0x10cece000",
          "driver_address": "0x10cecf000",
          "device_address": "0x10cecf240",
          "received_desc": "256",
          "completed_desc": "0",
          "bad_desc_errors": "0",
          "error_cqes": "0",
          "exceed_max_chain": "0",
          "invalid_buffer": "0",
          "batch_number": "64",
          "dma_q_used_number": "6",
          "handler_schd_number": "4",
          "aux_handler_schd_number": "3",
          "max_post_desc_number": "0",
          "total_bytes": "0",
          "rq_cq_max_count": "0",
          "rq_cq_period": "0",
          "rq_cq_period_mode": "1"
        },
        ......
        }
      ]
    }
  ]
}

Modify Device

This command modifies the attributes of a given device.

Syntax

Copy
Copied!

            
            virtnet modify [-h] [-p PF] [-v VF] [-u VUID] [-a] {device,queue} ...

Info

The options --pf , --vf , --vuid , and --all are mutually exclusive, but one of them must be applied.

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit
`--all`	`-a`	N/A	No	Modify all available device attributes depending on the selection of `device` or `queue`
`--pf`	`-p`	Number	No	Unique device ID for the PF. May be retrieved by using `virtnet list`.
`--vf`	`-v`	Number	No	Unique device ID for the VF. May be retrieved by using `virtnet list`.
`--vuid`	`-u`	String	No	Unique device SN for the device (PF/VF). May be retrieved by using `virtnet list`.
`device`	N/A	Number	No	Modify device specific options
`queue`	N/A	N/A	No	Modify queue specific options

Device Options

Copy
Copied!

            
            virtnet modify device [-h] [-m MAC] [-t MTU] [-e SPEED] [-l LINK]
                           [-s STATE] [-f FEATURES]
                           [-o SUPPORTED_HASH_TYPES] [-k RSS_MAX_KEY_SIZE]
                           [-r RX_MODE] [-n MSIX_NUM] [-q MAX_QUEUE_SIZE]
                           [-d DST_PORT] [-b RX_DMA_Q_NUM]
                           [-dim {enable,disable}] [-dc {enable,disable}]

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	String	No	Show the help message and exit
`--mac`	`-m`	Number	No	The virtio-net device MAC address
`--mtu`	`-t`	Number	No	The virtio-net device MTU
`--speed`	`-e`	Number	No	The virtio-net device link speed in Mb/s
`--link`	`-l`	Number	No	The virtio-net device link status 0 – down 1 – up
`--state`	`-s`	Number	No	The virtio-net device status field bit masks according to virtio spec `ACKNOWLEDGE (bit 0)` `DRIVER (bit 1)` `DRIVER_OK (bit 2)` `FEATURES_OK (bit 3)` `DEVICE_NEEDS_RESET (bit 6)` `FAILED (bit 7)`
`--features`	`-f`	Hex Number	No	The virtio-net device feature bits according to virtio spec
`--supported_hash_types`	`-o`	Hex Number	No	Supported hash types for this device in hex. Only applicable when `VIRTIO_NET_F_HASH_REPORT` is enabled. `VIRTIO_NET_HASH_TYPE_IPv4 (bit 0)` `VIRTIO_NET_HASH_TYPE_TCPv4 (bit 1)` `VIRTIO_NET_HASH_TYPE_UDPv4 (bit 2)` `VIRTIO_NET_HASH_TYPE_IPv6 (bit 3)` `VIRTIO_NET_HASH_TYPE_TCPv6 (bit 4)` `VIRTIO_NET_HASH_TYPE_UDPv6 (bit 5)`
`--rss_max_key_size`	`-k`	Number	No	The maximum supported length of RSS key. Only applicable when `VIRTIO_NET_F_RSS` or `VIRTIO_NET_F_HASH_REPORT` is enabled.
`--rx_mode`	`-r`	Hex Number	No	The RX mode exposed to driver 0 – promisc 1 – all-multi 2 – all-uni 3 – no-multi 4 – no-uni 5 – no-broadcast
`--msix_num`	`-n`	Number	No	Maximum number of VQs (both data and ctrl/admin VQ). It is bounded by the cap of `max_virt_queues` in controller level (`virtnet list`).
`--max_queue_size`	`-q`	Number	No	Maximum number of buffers in the virtqueue. Queue Size value is always a power of 2. The maximum queue size value is 32768.
`--dst_port`	`-d`	Hex Number	No	Modify IPv4 `dst_port` rules Note Will be depreciated in the future.
`--rx_dma_q_num`	`-b`	Number	No	Modify max RX DMA queue number
`--rx_dim_config`	`-dim`	String	No	Enable/disable RX dynamic interrupt moderation
`--drop_counter`	`-dc`	String	No	Enable/disable virtio-net drop counter

Note

The following modify options require unbinding the virtio device from virtio-net driver in the guest OS:

MAC
MTU
Features
Msix_num
max_queue_size

For example:

On the guest OS:

Copy
Copied!

            
            [host]# echo "bdf of virtio-dev" > /sys/bus/pci/drivers/virtio-pci/unbind

On the DPU side:

Modify the max queue size of device:

Copy
Copied!

            
            [DPU]# virtnet modify -p 0 -v 0 device -q 2048

Modify the MSI-X number of VF device:

Copy
Copied!

            
            [DPU]# virtnet modify -p 0 -v 0 device -n 8

Modify the MAC address of virtio physical device ID 0 (or with its "VUID string", which can be obtained through virtnet list/query):
Copy

Copied!
```
            
            [DPU]# virtnet modify -p 0 device -m 0C:C4:7A:FF:22:93
        
```

On the guestOS:

Copy
Copied!

            
            [host]# echo "bdf of virtio-dev" > /sys/bus/pci/drivers/virtio-pci/bind

Queue Options

Copy
Copied!

            
            virtnet modify queue [-h] -e {event,cqe} -n PERIOD -c MAX_COUNT

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	String	No	Show the help message and exit
`--period_mode`	`-e`	String	No	RQ period mode: event or cqe. Default is selected by device for best result.
`--period`	`-n`	Number	No	The event generation moderation timer for the queue in 1 µ sec granularity
`--max_count`	`-c`	Number	No	The max event generation moderation counter of the queue

Output

Entry	Type	Description
`errno`	Number	Error number: 0 – success non-0 – failed
`errstr`	String	Explanation of the error number

Entry

Type

Description

errno

Number

Error number:

0 – success
non-0 – failed

errstr

String

Explanation of the error number

Example

Modify the link status of the first VF on the first PF to be down:

Copy
Copied!

            
            # virtnet modify -p 0 device -l 0
{'pf': '0x0', 'all': '0x0', 'subcmd': '0x0', 'link': '0x0'}
{
  "errno": 0,
  "errstr": "Success"
}

Log

This command manages the log level of virtio-net-controller.

Syntax

Copy
Copied!

            
            virtnet log [-h] -l {info,err,debug}

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit
`--level`	`-l`	String	Yes	Change the log level of `virtio_net_controller` from journal. Default is DEBUG.

Output

Entry	Type	Description
`Stdout`	String	Success or failed with message

Example

To change log level to info:

Copy
Copied!

            
            # virtnet log -l info
{'level': 'info'}
"Success"

To monitor current log output of the controller service with the latest 100 lines printed out:

Copy
Copied!

            
            $ journalctl -u virtio-net-controller -f -n 100

Version

This command prints current and updated version of virtio-net-controller.

Syntax

Copy
Copied!

            
            virtnet version [-h]

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit

Output

Entry	Type	Description
`Original Controller`	String	The original controller version
`Destination Controller`	String	The to be updated controller version

Example

Check current and next available controller version:

Copy
Copied!

            
            # virtnet version
[
  {
    "Original Controller": "v1.8.12"
  },
  {
    "Destination Controller": "v1.9.14"
  }
]

Update

Live update minimizes network interface down time by performing online upgrade of the virtio-net controller without necessitating a full restart.

Syntax

Copy
Copied!

            
            virtnet update [-h] [-s | -t]

Option	Abbr	Argument Type	Required	Description
`--help`	`-h`	N/A	No	Show the help message and exit
`--start`	`-s`	N/A	No	Start live update virtio-net-controller
`--status`	`-t`	N/A	No	Check live update status

Output

Entry	Type	Description
`stdout`	String	If the update started successfully

Example

To start the live update process, run:

Copy
Copied!

            
            # virtnet update -s
{'start': '0x1'}
"Update started, use 'virtnet update -t' or check logs for status"

To check the update status during the update process:

Copy
Copied!

            
            # virtnet update -t
{'status': '0x1'}
{
  "current status": "inactive",
  "last status": "success",
  "time_used (s)": 0.604152
}

Error Code

CLI commands will return non-0 error code upon failure. All error numbers are negative. When there is error happening from log, it could return error number as well.

If the error number is greater than -1000, it's standard error. Please refer to Linux error code at errno

If the error number is less or equal -1000, please refer to the table below for the explaination.

Errno	Error Name	Error Description
`-1000`	`VIRTNET_ERR_DEV_FEATURE_VALIDATE`	Failed to validate device feature
`-1001`	`VIRTNET_ERR_DEV_NOT_FOUND`	Failed to find device
`-1002`	`VIRTNET_ERR_DEV_NOT_PLUGGED`	Failed - Device is not hotplugged
`-1003`	`VIRTNET_ERR_DEV_NOT_STARTED`	Failed - Device did not start
`-1004`	`VIRTNET_ERR_DRIVER_PROBED`	Failed - Virtio driver should not be loaded
`-1005`	`VIRTNET_ERR_EPOLL_ADD`	Failed to add epoll
`-1006`	`VIRTNET_ERR_ID_OUT_OF_RANGE`	Failed - ID input exceeds the max range
`-1007`	`VIRTNET_ERR_VUID_INVALID`	Failed - VUID is invalid
`-1008`	`VIRTNET_ERR_MAC_INVALID`	Failed - MAC is invalid
`-1009`	`VIRTNET_ERR_MSIX_INVALID`	Failed - MSIX is invalid
`-1010`	`VIRTNET_ERR_MTU_INVALID`	Failed - MTU is invalid
`-1011`	`VIRTNET_ERR_PORT_CONTEXT_NOT_FOUND`	Failed to find port contex
`-1012`	`VIRTNET_ERR_REC_CONFIG_LOAD`	Failed to load config from recovery file
`-1013`	`VIRTNET_ERR_REC_CONFIG_SAVE`	Failed to save config into recovery file
`-1014`	`VIRTNET_ERR_REC_FILE_CREATE`	Failed to create recovery file
`-1015`	`VIRTNET_ERR_REC_MAC_DEL`	Failed to delete MAC in recovery file
`-1016`	`VIRTNET_ERR_REC_MAC_LOAD`	Failed to load MAC from recovery file
`-1017`	`VIRTNET_ERR_REC_MAC_SAVE`	Failed to save MAC into recovery file
`-1018`	`VIRTNET_ERR_REC_MQ_SAVE`	Failed to save MQ into recovery file
`-1019`	`VIRTNET_ERR_REC_PFNUM_LOAD`	Failed to load PF number from recovery file
`-1020`	`VIRTNET_ERR_REC_RX_MODE_SAVE`	Failed to save RX mode into recovery file
`-1021`	`VIRTNET_ERR_REC_SF_SAVE`	Failed to save PF and SF number into recovery file
`-1022`	`VIRTNET_ERR_REC_SFNUM_LOAD`	Failed to load SF number from recovery file
`-1023`	`VIRTNET_ERR_SF_MAC_FLOW_APPLY`	Failed to apply MAC flow by SF
`-1024`	`VIRTNET_ERR_SF_MQ_UPDATE`	Failed to update MQ by SF
`-1025`	`VIRTNET_ERR_SF_RX_MODE_SET`	Failed to set RX mode by SF
`-1026`	`VIRTNET_ERR_SNAP_NET_CTRL_OPEN`	Failed to open SNAP device control
`-1027`	`VIRTNET_ERR_SNAP_CROSS_MKEY_CREATE`	Failed to create SNAP cross mkey
`-1028`	`VIRTNET_ERR_SNAP_DMA_Q_CREATE`	Failed to create SNAP DMA Q
`-1029`	`VIRTNET_ERR_SNAP_NET_DEV_QUERY`	Failed to query SNAP device
`-1030`	`VIRTNET_ERR_SNAP_NET_DEV_MODIFY`	Failed to modify SNAP device
`-1031`	`VIRTNET_ERR_SNAP_PF_HOTPLUG`	Failed to hotplug SNAP PF
`-1032`	`VIRTNET_ERR_VQ_PERIOD_UPDATE`	Failed to update VQ period
`-1033`	`VIRTNET_ERR_QUEUE_SIZE_INVALID`	Failed - Queue size is invalid
`-1034`	`VIRTNET_ERR_SF_PORT_ADD`	Failed to add SF port
`-1035`	`VIRTNET_ERR_WQ_WORKQUEUE_ALLOC`	Failed to alloc workqueue
`-1036`	`VIRTNET_ERR_ETH_VQS_OPERATION_ALLOC`	Failed to alloc eth VQS operation
`-1037`	`VIRTNET_ERR_ETH_VQS_OPERATION_COMP`	Failed to complete eth VQS operation
`-1038`	`VIRTNET_ERR_JSON_OBJ_NOT_EXIST`	Failed - JSON obj does not exist
`-1039`	`VIRTNET_ERR_DEV_LOAD_PREP`	Failed to prepare device load
`-1040`	`VIRTNET_ERR_DEV_SW_MIGRATION`	Failed to sw migrate a device
`-1041`	`VIRTNET_ERR_DEV_IS_SW_MIGRATING`	Failed - Device is migrating
`-1042`	`VIRTNET_ERR_MAX_QUEUE_SIZE`	Error - queue size must be greater than 2 and is power of 2
`-1043`	`VIRTNET_ERR_MSIX_LESS_EQUAL_THREE`	Warning - this device won't function, don't try to probe with virtio driver
`-1044`	`VIRTNET_ERR_SF_POOL_CREATING`	SF pool is creating try again later
`-1045`	`VIRTNET_ERR_DST_PORT`	Failed to set dst port rule
`-1046`	`VIRTNET_ERR_INVALID_OPTION`	Option is not supported
`-1047`	`VIRTNET_ERR_SF_CREATE`	Failed to create SF
`-1048`	`VIRTNET_ERR_DEV_SF_NUM_OUT_OF_RANGE`	SF number for hotplug device should be between 2000 and 2999
`-1049`	`VIRTNET_ERR_DEV_SF_NUM_USED`	SF number is already used
`-1050`	`VIRTNET_ERR_QUEUE_NUMBER_INVALID`	Queue index is invalid
`-1051`	`VIRTNET_ERR_SPEED_INVALID`	Invalid speed please check help menu for supported link speeds
`-1052`	`VIRTNET_ERR_SUPPORTED_HASH_TYPES_INVALID`	Invalid hash types please check help menu for supported hash types
`-1053`	`VIRTNET_ERR_RSS_MAX_KEY_SIZE_INVALID`	Invalid rss max key size supported key size is 40
`-1054`	`VIRTNET_ERR_REC_OFFLOADS_SAVE`	Failed to save OFFLOADS into recovery file
`-1055`	`VIRTNET_ERR_SF_OFFLOADS_UPDATE`	Failed to update OFFLOADS by SF
`-1056`	`VIRTNET_ERR_READ_LINK`	Failed to readlink
`-1057`	`VIRTNET_ERR_PATH_FORMAT`	Error - Path format is invalid
`-1058`	`VIRTNET_ERR_Q_COUNTER_ALLOC`	Failed to alloc q counter
`-1059`	`VIRTNET_ERR_REC_DIRTY_LOG_SAVE`	Failed to save dirty log
`-1060`	`VIRTNET_ERR_REC_DIRTY_LOG_DEL`	Failed to delete dirty log
`-1061`	`VIRTNET_ERR_REC_LM_STATUS_SAVE`	Failed to save LM status
`-1062`	`VIRTNET_ERR_REC_LM_STATUS_REC`	Failed to found LM status record
`-1063`	`VIRTNET_ERR_REC_DEV_MODE_SAVE`	Failed to save dev mode
`-1064`	`VIRTNET_ERR_REC_DEV_MODE_REC`	Failed to found dev mode record
`-1065`	`VIRTNET_ERR_UNPLUG_NOT_READY`	Error - Device is not ready to be unplugged please check host and retry

On This Page