Snapshot and Read a devlink Region Safely

A network card is misbehaving and the vendor wants a firmware dump, so you reach for devlink region. You will find a region, snapshot it, read the bytes and clean up, in about fifteen minutes.

The commands use the devlink utility from iproute2 6.1.0, packaged here as iproute2 6.1.0-1ubuntu6.4.

• You need: a devlink-capable device and a region name supplied by its driver. There are no generic region names: the driver decides what is exposed.
• What it changes: most queries are read-only, but creating and deleting snapshots change device-side diagnostic state.
• Privileges: use an account with the required netlink privilege if the command reports a permission error. Do not add sudo automatically.

1. Check the installed command

Start with the version and the built-in command list. Both are read-only:

$ devlink -V
devlink utility, iproute2-6.1.0
$ devlink region help
Usage: devlink region show [ DEV/REGION ]
       devlink region del DEV/REGION snapshot SNAPSHOT_ID
       devlink region new DEV/REGION [ snapshot SNAPSHOT_ID ]
       devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
       devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH

Help formatting can vary between iproute2 releases. The shape that matters is DEV/REGION, such as pci/0000:00:05.0/cr-space. Keep it together: bus, device and region are one argument, not three.

$ command -v devlink
/usr/bin/devlink
$ dpkg-query -W -f='${Package} ${Version}\n' iproute2
iproute2 6.1.0-1ubuntu6.4

2. List the regions your device exposes

Ask the kernel and drivers what is available:

$ devlink region show
pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] max 8
pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 8

That output is a representative format from the kernel documentation, not a promise about your machine. An empty result is valid: it means no regions are currently exposed.

• Copy, do not guess. Take an exact DEV/REGION from your own output.
• Note the size. You will need it when you choose an address and length.
• Note existing snapshot IDs. They are listed in square brackets.

If the command fails with an unsupported-operation or missing-device message, check that the driver is loaded and the device is present. Do not invent a region name. Installing a newer iproute2 does not prove the driver supports regions.

3. Create a snapshot

A snapshot freezes the region as a driver-defined diagnostic capture. It is the safer choice when you want a consistent view for later reads. Swap the placeholder for the value from your own region show output:

$ REGION='pci/0000:00:05.0/fw-health'
$ devlink region new "$REGION"
pci/0000:00:05.0/fw-health: snapshot 5

Without an explicit identifier, devlink asks the kernel to assign a unique snapshot ID. Write the number down straight away. IDs and the maximum count are device-specific, so yours will not be 5.

Some regions do not support on-demand snapshots. In that case use a snapshot already listed by region show, or a direct read, but only if the driver documents that it is safe.

$ devlink region show "$REGION"
pci/0000:00:05.0/fw-health: size 64 snapshot [5] max 8

Creating a snapshot does not edit firmware or repair the fault. It only requests diagnostic data from a driver. If the command is rejected, stop and follow the driver's documentation.

4. Dump the captured region

Dump everything in the snapshot when the region is small or you need a complete capture:

$ devlink region dump "$REGION" snapshot 5
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8

The left column is the region offset. The rest is the returned data in hexadecimal. The contents are driver-specific, so devlink does not turn them into a universal error report. For a support case, save the output with ordinary shell redirection:

$ devlink region dump "$REGION" snapshot 5 > fw-health-snapshot-5.txt
$ test -s fw-health-snapshot-5.txt && echo 'dump saved'
dump saved

5. Read only the bytes you need

For a focused look, give an address and a length. The address is a region offset, and hexadecimal is accepted by the documented example:

$ devlink region read "$REGION" snapshot 5 address 0x10 length 16
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8

The range must make sense for the size shown by region show. A bad offset or length is a command or driver error, not a cue to retry with random values. A snapshot read is stable against the captured data. A direct read leaves out the snapshot part:

$ devlink region read "$REGION" address 16 length 16

6. Remove the snapshot when finished

Snapshots eat into a device-defined allowance, so delete yours once you have what you need. Make sure any dump you want has been saved first:

$ devlink region del "$REGION" snapshot 5
$ devlink region show "$REGION"
pci/0000:00:05.0/fw-health: size 64 snapshot [] max 8

Deletion removes snapshot 5 from the region. It does not restore or alter the underlying hardware state.

Common traps

• Empty output is not a fault. An empty region show does not mean the device is broken. The driver may expose no regions, or the device may not be registered with devlink.
• Snapshot IDs are local. Use the ID together with the exact region and devlink instance that reported it.
• A dump is not a diagnosis. devlink does not decode the bytes. Read the driver's documentation before interpreting fields or changing hardware settings.
• sudo cannot conjure features. Elevated privileges will not fix an unsupported region, an invalid offset or a missing driver.