Inspect and Tune a devlink Shared Buffer Safely

Your switch is dropping packets under bursts and you suspect the shared buffer, so you reach for devlink sb. You will inspect pools, port thresholds and traffic-class bindings, then take an occupancy snapshot before you read watermarks.

Allow 15 minutes for inspection, longer if you need to test a live traffic path.

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, and these commands will not create a 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. On a host with no device exposing this feature it prints nothing, which is different from a syntax error. If the list is empty, stop here and confirm the driver, hardware and devlink device name before you try a change.

For the examples below, set a shell variable to the exact device name your host reports. A PCI devlink name often looks like pci/0000:03:00.0, but do not copy that 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 size that is not a multiple of it, so record the displayed values rather than trusting that your 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 says traffic-class indices usually run from 0 to 8, but the device decides the valid range.

3. Understand static and dynamic thresholds

Each pool has a threshold type, and it changes what the numbers mean.

• Static. Port-pool and traffic-class thresholds are byte values.
• Dynamic. Those thresholds are to_alpha values from 0 to 20. The manual's formula is alpha = 2 ^ (to_alpha - 10), and the resulting alpha controls the maximum usage as a proportion of free buffer space.

So a dynamic value of 10 gives alpha 1, which is half of the free buffer in the documented formula. Values below 10 shrink that proportion and values above 10 grow it. It is a threshold policy, not a request for a fixed number of bytes.

4. Change one pool attribute, only when authorised

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 straight away.

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

With the pool correct, a port-pool threshold controls that port's use of it. The unit follows the pool's threshold type. This example sets 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

On a dynamic pool, th 4096 would be read as a to_alpha value and fall outside the documented 0 to 20 range. Use a value in that range instead, and verify it afterwards.

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. Test ingress and egress separately: changing one does not document the other.

6. Measure occupancy before judging the change

Occupancy values are not available until you request a snapshot. Take one on the device, then read the whole device or a single port:

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

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

To start a fresh watermark measurement, clear the maximum occupancy values, then snapshot again before reading:

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