[PATCH iproute2-next 0/2] tc/tbf and tc/htb: Allow 64 bit burst

Ioana Lazea
2026-03-23T09:31:44Z

This patchset updates the TBF and HTB queuing discipline
configurations to support burst sizes beyond the legacy 32-bit limits.
As network interface speeds increase, the kernel’s internal
representation of burst (calculated as time at a specific rate) can
easily exceed the 4 GB threshold. These changes enable userspace to
accommodate these larger values where the kernel API allows.

Additionally, if the burst exceeds the upper limit supported by
the kernel API, it is now reported as an error in userspace before
attempting the Netlink transition. Previously, such values would
silently overflow, causing corrupted values to be passed to the kernel.

The implementation follows the approach used for tc police burst
handling introduced in commit 3b26e8abf404 ("tc/police: enable use of 64
bit burst parameter"). The reasoning behind the patches proposed here is
largely based on the rationale described in the aforementioned change.

Similarly to the case of the tc police burst option, as
implemented now the TBF and HTB burst option limit the sizes of the
burst up to 4 GB (UINT_MAX for a 32 bit unsigned int) due to the
constraints in the user space tooling. Historically, TBF and HTB burst
options were capped at 32 bits, which was a sufficient limit for the
lower line rates common when they were initially developed. However,
since the underlying kernel logic treats the burst as a time-based
value, it is already capable of handling larger sizes at high rates
without requiring internal modifications. This patchset bridges that gap
in the user space tools.

The detailed technical explanation for this change was
previously detailed by Jay Vosburgh:

Link: https://lore.kernel.org/netdev/20250916215731.3431465-1-jay.vosburgh@canonical.com/

To summarize the details at the link, the burst size is limited
by the kernel to approximately 274 seconds at the specified rate, and
has no inherent 4 GB limit.

Below is a short description of the main changes made to the TBF
and HTB queuing disciplines.

In both TBF and HTB, the primary modification replaces the
unsigned integer burst variable with an unsigned 64 bit integer variable
(buffer64) so that burst sizes larger than 4 GB can be represented and
passed correctly through the kernel API.

For the TBF qdisc specifically, the following logic was added:

if (buffer64 < (1ULL << 32)) {
__u32 buffer32 = (__u32)buffer64;

addattr_l(n, 2124, TCA_TBF_BURST, &buffer32, sizeof(buffer32));
}

Increasing the burst size representation to 64 bits introduces
an issue with TCA_TBF_BURST. The kernel expects this attribute as
NLA_U32 (a 32-bit unsigned value), while the updated implementation may
produce burst values exceeding this range. Passing such values would
cause the tbf_policy validation in the kernel to fail. To avoid this,
TCA_TBF_BURST is only included when the value fits within 32 bits. When
the attribute is omitted (for example, when buffer64 exceeds the 32-bit
limit), the kernel falls back to using the value stored in qopt->buffer,
which already supports larger burst sizes.
As seen in commit 2e04ad424b03 ("sch_tbf: add
TBF_BURST/TBF_PBURST attribute"), TCA_TBF_BURST was originally
introduced to handle issues with very small burst values. Omitting the
attribute for large bursts therefore preserves the intended behavior
while avoiding incompatibilities with the kernel attribute policy.
Additionally, the burst value is explicitly cast to 32 bits where
required, ensuring that 64-bit values are not passed to kernel
interfaces expecting 32-bit fields.

These modifications bring the user space tools in line with the
kernel's internal 64-bit handling. The logic effectively avoids Netlink
attribute validation failures while preserving the original intent of
the burst mechanism for small values.

I look forward to your feedback on this approach.

Ioana Lazea (2):
tc/tbf: enable use of 64 bit burst parameter
tc/htb: enable use of 64 bit burst parameter

tc/q_htb.c | 16 ++++++++++------
tc/q_tbf.c | 24 ++++++++++++++++--------
2 files changed, 26 insertions(+), 14 deletions(-)

--
2.43.0