Home / Alt manpages / devlink-dev(8)

  • devlink-dev(8)
  • Admin command
  • linux

Inspect and Safely Tune a devlink Device

You need to know what firmware a NIC is running, or whether a driver parameter can be changed, without bricking the card. This guide shows how to use devlink dev to identify a kernel device, inspect its parameters and embedded switch state, then pick a safe next step such as a self-test or a planned reload. Allow about fifteen minutes for inspection.

The route

Jump straight to the step you need, or tick off Done means at the end.

  • Version covered: the installed devlink-dev(8) interface from iproute2 6.1.0-1ubuntu6.4.
  • What it will not do: a firmware flash or reload needs a maintenance window and device-specific documentation, so this guide performs neither.

1. Check the installed command

Start with read-only version and help checks. These do not need elevated privileges:

$ devlink -V
devlink utility, iproute2-6.1.0
$ dpkg-query -W -f='${Package} ${Version}\n' iproute2
iproute2 6.1.0-1ubuntu6.4
$ devlink dev help

The option is -V, not the GNU-style --version. The command may work as an ordinary user, but access to a particular driver or device can depend on kernel and system policy.

Checkpoint

Record the iproute2 version, and stop if your local help shows a materially different command shape. The examples below describe the installed interface, not every newer release.

2. Find the exact device identifier

List all devlink devices before using a device-specific command:

$ devlink dev show
pci/0000:01:00.0

Your output may be empty, or show a different bus and address. Do not copy the identifier above unless it is on your machine. When a device exists, set a shell variable from your own output:

$ DEV='pci/0000:01:00.0'
$ devlink dev show "$DEV"
pci/0000:01:00.0

Keep the value quoted. An empty result means there is no visible devlink device to configure, and an invented identifier will not change that.

3. Inspect information before changing state

Read the device information and embedded switch settings first:

$ devlink dev info "$DEV"
$ devlink dev eswitch show "$DEV"
$ devlink dev param show "$DEV"
  • Fields are driver-dependent. Device information can separate fixed components from running and stored firmware versions.
  • Running and stored versions can differ after a flash and before the required restart or reset.
  • Parameter output is the menu. It shows the names and configuration modes the driver actually supports, so use those rather than guessing.

For one parameter, copy its exact name from that output and narrow the query:

$ PARAM='PARAMETER_FROM_DEVLINK_OUTPUT'
$ devlink dev param show "$DEV" name "$PARAM"

4. Run supported self-tests

Self-tests are a reasonable place to start, but a test can still exercise hardware and hurt service quality. Run them only when the driver documentation and your maintenance plan allow it:

$ devlink dev selftests show "$DEV"
$ devlink dev selftests run "$DEV" id TEST_ID

Replace TEST_ID with an identifier printed by selftests show. Omitting id requests every supported self-test, which takes longer and may be more disruptive. A successful command means the requested test completed according to the driver; keep its output with the change record.

5. Understand parameter changes before applying one

There are three configuration modes:

  • runtime applies while the driver is running and needs no reset.
  • driverinit stores a value for driver initialisation and needs a devlink reload to apply it.
  • permanent writes the value to non-volatile device memory and needs a hard reset.

The device must advertise the parameter and accept the chosen mode.

Warning

Changing a parameter is stateful and may alter traffic handling. Confirm the current value, the desired value, the driver's documentation and a recovery path before using a command like this:

$ devlink dev param set "$DEV" name PARAMETER value VALUE cmode runtime
$ devlink dev param show "$DEV" name PARAMETER

Replace both uppercase placeholders with values shown or documented for your device. There is no universal undo value: restore the previous value with the same command, if the driver still accepts it. Do not use permanent as a trial mode.

6. Treat reloads and firmware writes as maintenance work

Warning

Reload can cause a reset, downtime, link flap or loss of configuration. The default action is driver_reinit, but the driver may perform additional actions. Use limit no_reset only when the driver supports the requested operation without reset; it does not make every reload possible.

$ devlink dev reload "$DEV" action driver_reinit limit no_reset

Without limit no_reset, the driver may reset or interrupt service as needed. Check the command's reported actions and verify the device afterwards:

$ devlink dev show "$DEV"
$ devlink dev info "$DEV"
$ devlink dev eswitch show "$DEV"

Firmware activation with action fw_activate can activate a pending image and may involve a firmware reset.

Warning

Flashing is more irreversible. devlink dev flash "$DEV" file PATH writes device non-volatile memory, and the path must be available to the kernel firmware loader, such as under /lib/firmware. Verify the image, target and vendor procedure first, record the current dev info, and use the vendor's recovery process if the write fails. This guide deliberately gives no copy-and-paste flash command.

7. Diagnose the common failures

  • Empty devlink dev show. Check that the relevant driver is loaded and that the hardware exposes devlink support.
  • Unknown device. Compare the bus and address character for character with devlink dev show.
  • Parameter rejected. Query devlink dev param show "$DEV" again and check that its supported configuration mode includes the one you chose.

After a reload or self-test, verify links and the service that owns the interface through your normal monitoring.

Recovery

If a parameter change causes trouble, restore the recorded previous value if the device is reachable. For a driverinit value, schedule the required reload. A permanent value may need a hard reset and cannot be treated as an ordinary runtime rollback.

Done means

  • Version confirmed: you checked the installed iproute2 version and used the local devlink dev help syntax.
  • Real identifier: you copied a device identifier from devlink dev show.
  • Looked first: you inspected device information, eswitch state and supported parameters before changing anything.
  • Supported only: you chose only a self-test or parameter mode that the device documents and supports.
  • Maintenance mindset: you treated reload, firmware activation and flash as planned work, with a recorded recovery path.