Capture and Read a Devlink Region Snapshot Safely

You will identify a driver-exposed devlink region, create a snapshot when the driver supports it, dump the captured bytes or read a small range, and remove the snapshot afterwards. Allow about fifteen minutes for a first investigation. 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 device driver decides what is exposed. Most queries are read-only, but creating and deleting snapshots change device-side diagnostic state. Use an account with the required netlink privilege when the command reports a permission error. Do not add sudo automatically.

1. Check the installed command

Start with the version and built-in command list. This is an ordinary read-only check:

$ 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

The exact help formatting can vary between iproute2 releases. The important shape is DEV/REGION, such as pci/0000:00:05.0/cr-space. Keep the complete value together: the bus, device and region are one argument, not three separate arguments.

Checkpoint: confirm the binary and package before troubleshooting a command copied from another host:

$ 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 for the available regions:

$ 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

The output above is a representative format from the kernel documentation, not a promise about your machine. An empty result is valid and means that no devlink regions are currently exposed. A device name in documentation is an example, not a value to guess. Copy an exact DEV/REGION from your own output, then note the region size and any existing snapshot identifiers.

If the command fails with an unsupported-operation or missing-device message, check that the relevant driver is loaded and that the device is present. Do not invent a region name, and do not treat installing a newer iproute2 package as proof that the driver supports regions.

3. Create a snapshot

A snapshot freezes the region data as a driver-defined diagnostic capture. It is the safer choice when you need a consistent view for later reads. Replace the placeholder with 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. Record the returned number immediately. The available IDs and the maximum count are device-specific, so your result will differ from 5. Some regions do not support on-demand snapshots; in that case, use a snapshot already listed by region show, or use a direct read only if the driver documents that it is safe.

Checkpoint: verify that the new snapshot appears before reading it:

$ 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 reported fault. It only requests diagnostic data from a driver. If the command is rejected, stop there and follow the device driver's documentation.

4. Dump the captured region

Dump all available data from the snapshot when the region is small or a complete capture is required:

$ 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 and the remaining fields are the returned data in hexadecimal. The contents are driver-specific, so devlink does not translate them into a universal error report. Save the output with normal shell redirection if you need to attach it to a support case:

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

Use a new filename or an explicit backup before redirecting. Shell > truncates an existing file before devlink runs. The dump is diagnostic data, so check your organisation's handling rules before sending it outside the host.

5. Read only the bytes you need

For a focused inspection, provide an address and length. The address is a region offset, and hexadecimal notation 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 requested range must make sense for the region size shown by region show. A bad offset or length is a command or driver error, not a reason to retry with random values. A snapshot read is stable relative to the captured data. A direct read omits the snapshot part:

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

Direct reads inspect the live region and are not atomic. The kernel documentation specifically warns that requests of 256 bytes or more can be split into multiple chunks. Use a snapshot when a consistent capture matters, especially while investigating a changing device fault.

6. Remove the snapshot when finished

Snapshots consume a device-defined allowance. Deleting one is the reversible housekeeping action in this workflow, but first make sure any dump you need has been saved:

$ 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. If you deleted the wrong snapshot, there is no generic undo command: create a new snapshot if the driver still supports it, then record its new ID. Do not run the delete command in a batch until the region and snapshot ID have been checked.

Common traps

• An empty region show result is not evidence that the device is broken. The driver may expose no regions, or the device may not be registered with devlink.
• A snapshot ID is not a universal address. Use the ID together with the exact region and devlink instance that reported it.
• A successful dump does not decode the bytes. Consult the device driver's documentation before interpreting fields or changing hardware settings.
• Do not use sudo to bypass an unsupported region, invalid offset or missing driver. Elevated privileges cannot create a capability the driver does not provide.