Inspect and Tune a devlink Shared Buffer Safely

You will use devlink sb to inspect a switch device's shared buffers, pools, port thresholds and traffic-class bindings. You will also take an occupancy snapshot before reading watermarks. Allow 15 minutes for inspection, or longer if you need to test a live traffic path. Configuration changes can affect packet buffering, so do the write steps in a maintenance window and keep the original values ready for recovery.

1. Check the installed tool and identify the device

This guide follows the installed devlink-sb(8) interface from iproute2 6.1.0. Shared-buffer support is device and driver specific. The commands do not create a shared buffer on hardware that has none.

$ devlink -V
devlink utility, iproute2-6.1.0
$ devlink sb show

The last command lists available shared buffers when a supported device is present. It prints nothing on a host with no device exposing this feature, which is different from a command syntax error. If the list is empty, stop at this checkpoint and confirm the driver, hardware and devlink device name before attempting a change.

For the examples below, set a shell variable to the exact device name reported by your host. A PCI devlink name often looks like pci/0000:03:00.0, but do not copy that value unless your own output contains it.

$ DEV='pci/0000:03:00.0'
$ devlink sb show "$DEV"
$ devlink sb pool show "$DEV"

2. Record the current pools before changing anything

Pool output includes the pool type, size, threshold type and cell size. The cell size is the allocation granularity. A driver may round, round down or reject a requested size that is not a multiple of that value, so record the displayed values rather than assuming the requested number will be applied exactly.

$ devlink sb pool show "$DEV"
$ devlink sb port pool show "$DEV/1"
$ devlink sb tc bind show "$DEV/1" tc 0 type ingress
$ devlink sb tc bind show "$DEV/1" tc 0 type egress

Replace 1 with a port index that exists on your device, and query the ingress and egress traffic classes you actually use. The manual describes traffic-class indices as usually ranging from 0 to 8, but the device decides the valid range. Save this output in your change record. It is the practical rollback reference because devlink sb has no general undo command.

3. Understand static and dynamic thresholds

Each pool has a threshold type. With static, port-pool and traffic-class thresholds are byte values. With dynamic, those thresholds are to_alpha values from 0 to 20. The tool applies the manual's formula, alpha = 2 ^ (to_alpha - 10), and the resulting alpha controls the maximum usage as a proportion of free buffer space.

That makes a dynamic value of 10 produce alpha 1, which corresponds to half of the free buffer in the documented formula. Values below 10 reduce the proportion and values above 10 increase it. This is a threshold policy, not a request to allocate a fixed number of bytes. Confirm the pool's thtype before interpreting or setting any threshold.

4. Change one pool attribute, only when authorised

Changing a pool size or threshold is a privileged, service-impacting operation. First capture the exact current pool index, size and threshold type from the previous command. Then choose a value supported by the driver and your traffic design. The following is a template, not a safe value for every switch:

$ sudo devlink sb pool set "$DEV" pool 0 size 1048576 thtype static
$ devlink sb pool show "$DEV" pool 0

Use sb 0 explicitly when selecting a non-default shared buffer. If you omit the shared-buffer index, the command selects index 0. The size is in bytes. A successful command does not mean the driver accepted the number unchanged, so verify the resulting size and type immediately.

Recovery is to run pool set again with the recorded size and threshold type. If the driver rounded the old size, restore the value shown by the original pool show output. Do not guess a rollback value after a failed change.

5. Set a port-pool threshold or traffic-class binding

Once the pool is correct, a port-pool threshold controls that port's use of the pool. The unit follows the pool's threshold type. This example changes port 1, pool 0 to a static threshold of 4096 bytes:

$ sudo devlink sb port pool set "$DEV/1" pool 0 th 4096
$ devlink sb port pool show "$DEV/1" pool 0

For a dynamic pool, th 4096 would be interpreted as a to_alpha value and would be outside the documented 0 to 20 range. Use a value in that range instead, and verify it after the change.

A traffic class can be bound to a pool with its own threshold:

$ sudo devlink sb tc bind set "$DEV/1" tc 0 type ingress pool 0 th 8
$ devlink sb tc bind show "$DEV/1" tc 0 type ingress

The threshold unit again follows the selected pool's type. To recover, repeat the command with the original pool index and threshold recorded in step 2. Test ingress and egress separately; changing one does not document the other.

6. Measure occupancy before judging the change

Occupancy values are not available for browsing until you request a snapshot. Take the snapshot on the device, then read either the whole device or a specific port:

$ sudo devlink sb occupancy snapshot "$DEV"
$ devlink sb occupancy show "$DEV"
$ devlink sb occupancy show "$DEV/1"

The output reports current and maximum values as current_value/max_value for port-pool and port-traffic-class combinations. The snapshot is a measurement point, not a continuous monitor. Repeat it under the workload you are investigating and compare like-for-like traffic conditions.

To start a new watermark measurement, clear the device's maximum occupancy values, then take another snapshot before reading them:

$ sudo devlink sb occupancy clearmax "$DEV"
$ sudo devlink sb occupancy snapshot "$DEV"
$ devlink sb occupancy show "$DEV"

Clearing watermarks loses the previous maximums, so export or record them first if they matter to an incident review. This operation does not restore pool configuration.