Create and Inspect vDPA Devices with vdpa dev

vdpa dev lists, inspects, creates and removes vDPA devices through iproute2, provided the host already exposes a suitable management device. This walks through all four, following the installed vdpa-dev(8) manual on this machine.

Allow about fifteen minutes for inspection. Creating a device takes longer if you first need to identify a hardware or simulator management device. You need a shell, the iproute2 package, and a vDPA management device exposed by the kernel and its driver. Read-only inspection is normally unprivileged, but adding and deleting devices usually require the privileges allowed by your host's device policy.

This guide uses iproute2 6.1.0-1ubuntu6.4. The installed utility reports itself as vdpa utility, iproute2-6.1.0. Hardware drivers, available management devices and vendor-specific statistics are host-dependent.

1. Confirm the installed command

Start with the version and top-level help. These commands only inspect the executable:

$ vdpa -V
vdpa utility, iproute2-6.1.0
$ vdpa --help
Usage: vdpa [ OPTIONS ] OBJECT { COMMAND | help }

The top-level utility supports the mgmtdev and dev objects. This guide is about dev. Keep the full subcommand spelling in scripts, even though iproute2 commonly accepts abbreviated options.

Checkpoint: verify which binary will run before troubleshooting a different installation:

$ command -v vdpa
/usr/sbin/vdpa

2. List the devices that already exist

Use vdpa dev show without a device name to request all vDPA devices:

$ vdpa dev show
vdpa0
vdpa1

The output is one device name per line when devices are available. Your names and count will differ. A device name such as vdpa0 is an identifier to pass to later commands, not proof that the device is a network device.

On a host without a usable vDPA Netlink endpoint, the installed command instead reports an error such as:

$ vdpa dev show
Failed to connect to vdpa Netlink

That is an environment or kernel-interface problem. Do not try to solve it by inventing a device name or by running the same read-only query repeatedly as root. Check that the relevant driver is present and that the host is intended to provide vDPA.

3. Inspect one device and its configuration

After you have an exact name from the previous step, ask for its attributes:

$ vdpa dev show vdpa0
vdpa0

The manual describes the basic display format as the vDPA device name. More detailed attributes can depend on the iproute2 build and the device implementation. To inspect the configuration view for one device, run:

$ vdpa dev config show vdpa0
vdpa0

Omitting the device name from vdpa dev config show asks for all device configurations. Use the named form while investigating one device so that output from several devices cannot be mistaken for the values of the device you intend to change.

Checkpoint: save the exact device name and capture the two read-only outputs before making a change. If either command fails, stop here. A failed inspection is not a reason to guess the management device or the device's capabilities.

4. Query vendor-specific statistics when supported

The vDPA manual exposes vendor statistics by device and virtqueue index. For example, this asks for statistics for queue index 1:

$ vdpa dev vstats show vdpa0 qidx 1
packets 0
bytes 0

The output is a set of name-value pairs, with a numeric value for each field. The field names and values belong to the vendor and device. The example output is illustrative of the documented shape, not a guaranteed list of counters.

A virtqueue index is not automatically valid just because it is an integer. Use an index exposed by the device or the relevant driver documentation. If the command fails, record the exact device and index and treat unsupported statistics as a device capability or driver issue.

5. Identify a management device before creating anything

vdpa dev add needs both a new device name and an existing management device. The management device is the MGMTDEV argument, not the name you want to give the new device. List management devices with the companion object:

$ vdpa mgmtdev show
vdpa_sim_net
auxiliary/mlx5_core.sf.1

Only use a management-device name that your own host prints. The names above are examples from the manual's documented forms and are not a promise that either driver is installed. A simulator management device may be appropriate for a test host; a hardware management device can affect a real adapter and its service configuration.

Warning: Adding a device changes kernel and driver state. Confirm the management device, intended name, MAC address and MTU with the system owner before running the next step. Use a maintenance window for hardware-backed devices.

6. Add a network vDPA device

For a network vDPA device, provide a unique name, the management device, and optionally a MAC address and MTU:

$ sudo vdpa dev add name demo0 mgmtdev vdpa_sim_net mac 00:11:22:33:44:55 mtu 1500

The manual also documents max_vqp for the maximum number of virtqueue pairs:

$ sudo vdpa dev add name demo0 mgmtdev vdpa_sim_net mac 00:11:22:33:44:55 max_vqp 8

Do not combine both examples. Choose values supported by your management device. The MAC and MTU arguments apply to network-type vDPA devices; they are not general-purpose attributes for every vDPA implementation. If the command succeeds, verify the result rather than relying on the absence of an error:

$ vdpa dev show demo0
demo0
$ vdpa dev config show demo0
demo0

If creation fails, preserve the error text. Commonly useful facts are whether the management device exists, whether the requested name is already in use, and whether the chosen attributes are supported. Do not retry with random values on a production adapter.

7. Remove a device only after checking its owner

Deletion is the inverse operation, but it is not a harmless cleanup command. Removing a device can disrupt a guest, service or network path using it. Check the device name and its consumers first, then schedule the change:

$ vdpa dev show demo0
demo0
$ sudo vdpa dev del demo0

There is no separate undo command in vdpa-dev(8). Recovery means recreating the device with the original management device and the same supported arguments. Record those arguments before deletion. After removal, verify that the name is gone:

$ vdpa dev show demo0
Failed to find device demo0

The exact failure text can vary by iproute2 and the kernel. The useful check is that demo0 no longer appears in a complete vdpa dev show listing. If deletion reports that the device is busy, stop and remove the consumer through its normal administrative procedure instead of forcing the change.

Done means