Schedule Ethernet Traffic Windows with tc-taprio

A NIC that shares one wire between control traffic and everything else needs a gate schedule, and tc-taprio builds it. You will attach a TAPRIO queueing discipline to an Ethernet interface, map packet priorities to traffic classes, define a repeating gate schedule, and verify what the kernel accepted. TAPRIO is for time-aware transmission, not general bandwidth shaping. Allow 20 to 30 minutes for a first configuration, plus time to confirm the interface's queue and clock capabilities.

The examples match the installed iproute2 package, version 6.1.0-1ubuntu6.4, and its tc-taprio(8) manual page dated 25 September 2018. You need an interface with a suitable multi-queue driver, a schedule designed for the traffic, and root privileges for changes. Do not test this on an interface carrying a remote administration session.

1. Inspect the interface before changing it

Choose the interface and record its current qdisc. These are read-only commands and do not need sudo:

$ IFACE=eth0
$ ip -br link show "$IFACE"
$ tc qdisc show dev "$IFACE"
$ ethtool -l "$IFACE"
$ ethtool -T "$IFACE"

Replace eth0 with a real interface. The queue layout in the configuration must fit the device. In particular, each count@offset range must be contiguous and must not overlap another traffic class. TAPRIO supports up to 16 traffic classes, but that does not mean the NIC has 16 usable transmission queues.

Checkpoint: keep the output of tc qdisc show. You will need the old qdisc configuration if this interface is already configured by a network manager or another traffic-control service.

2. Read the schedule as a cycle

A TAPRIO schedule consists of ordered sched-entry records. Each record has the form S gate-mask interval. The only command supported by this installed manual is S, which sets the gate states. A set bit opens the corresponding traffic class: mask 01 opens class 0, 02 opens class 1, and 04 opens class 2. A mask of 00 closes all three.

The interval is in nanoseconds. The following three-entry cycle gives each class a 300 microsecond window in turn, so the cycle time is 900,000 nanoseconds:

sched-entry S 01 300000
sched-entry S 02 300000
sched-entry S 04 300000

The base-time is an absolute nanosecond timestamp measured by the selected clockid. A base time in the past is valid: TAPRIO advances it by whole cycle lengths until it reaches the next future occurrence. That behaviour is useful for a recurring schedule, but it does not make a badly chosen clock or phase correct.

3. Apply a software schedule

For an ordinary software schedule, use CLOCK_TAI and supply a base time appropriate to the clock on the host. The number below is the style of value expected by tc; replace it with a timestamp chosen for your deployment rather than copying an old example blindly:

$ BASE_TIME_NS=1720000000000000000
# tc qdisc replace dev "$IFACE" parent root handle 100: taprio \
    num_tc 3 \
    map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
    queues 1@0 1@1 2@2 \
    base-time "$BASE_TIME_NS" \
    sched-entry S 01 300000 \
    sched-entry S 02 300000 \
    sched-entry S 04 300000 \
    clockid CLOCK_TAI

map contains one traffic-class number for each packet priority from 0 through 15. In this example, priority 3 maps to class 0, priority 2 maps to class 1, and the remaining priorities map to class 2. The queues values assign one device queue to classes 0 and 1, then two queues to class 2.

This command changes the root qdisc and can alter live traffic immediately. The replace form is convenient for iteration, but it can replace an existing root qdisc. Run it only with a maintenance plan and elevated privileges.

Checkpoint: ask tc what it installed:

# tc -s qdisc show dev "$IFACE"
# tc qdisc show dev "$IFACE"
qdisc taprio 100: root ...

The exact statistics and formatting vary. The useful evidence is a taprio qdisc on the expected interface, with the schedule and class information shown by the installed command.

4. Check the priority and clock assumptions

TAPRIO gates traffic classes, not arbitrary application names. Confirm how the packets you care about acquire priorities before attributing them to a window. A VLAN priority, socket priority, filter, or driver policy may be involved. The map line only describes the mapping from priority numbers once those priorities exist.

CLOCK_TAI is a host clock choice. It is not automatically the same clock as a NIC's PTP hardware clock. If the schedule must align with hardware or another host, check synchronisation and the device's PTP capability before choosing a phase. A schedule that parses successfully can still be operationally wrong if the participating clocks are not aligned.

Do not omit clockid for the software configuration. The manual says it must be omitted for full offload, where the device's PTP clock is used implicitly. That is a separate mode with separate hardware support.

5. Use ETF only for the documented txtime-assist mode

TAPRIO also has a txtime-assist mode, selected with flags 0x1. In that mode TAPRIO assigns transmit timestamps and uses an ETF child qdisc to send packets at the requested time. The delay passed to TAPRIO must be greater than the ETF delta. Configure ETF from its own tc-etf(8) documentation and match the same clock deliberately.

Do not combine txtime assist with full offload. The installed manual explicitly says flags 0x1 and flags 0x2 are mutually exclusive, so flags 0x3 is invalid. Full offload passes the gate control list to a capable NIC, which then executes it in hardware; it is not a fallback that every Ethernet adapter supports.

A full-offload shape is structurally similar to the software example, but it omits clockid and sets flags 0x2:

# tc qdisc replace dev "$IFACE" parent root taprio \
    num_tc 3 \
    map 0 1 2 0 1 2 0 1 2 0 1 2 0 1 2 0 \
    queues 1@0 1@1 1@2 \
    base-time "$BASE_TIME_NS" \
    sched-entry S 01 20000 \
    sched-entry S 02 20000 \
    sched-entry S 04 60000 \
    flags 0x2

Use this only after confirming NIC and driver support. A successful parse is not proof that hardware offload is available.

6. Diagnose rejection without guessing

If tc rejects the command, first check the interface name, queue count, and whether another qdisc or network manager owns the root. Then reduce the configuration to the smallest valid schedule and add one feature at a time. Common traps are overlapping queue ranges, too many queues for the device, a non-contiguous range, a malformed gate mask, and a base time written in the wrong clock or unit.

Remember that every interval is nanoseconds. The values 300000 and 300000000 mean 300 microseconds and 300 milliseconds respectively. Check the cycle by adding every interval yourself. If the phase matters, calculate the next base time using the same clock named in the qdisc rather than relying on a wall-clock string.

For a read-only diagnostic snapshot, run:

$ tc -s qdisc show dev "$IFACE"
$ ip -details link show dev "$IFACE"
$ ethtool -T "$IFACE"

Capture this output with the exact command and kernel version when asking a driver maintainer for help. Do not infer hardware support from the presence of the taprio keyword alone.

7. Remove the test schedule carefully

Removing the qdisc changes live traffic and may expose the interface's default queueing behaviour. Before testing, record the previous root configuration and make sure you have console access. When you are ready to remove the TAPRIO qdisc:

# tc qdisc del dev "$IFACE" root
# tc qdisc show dev "$IFACE"

That removes the TAPRIO configuration. It does not reconstruct a custom qdisc that was there before. Restore the recorded configuration through the system's normal network-management method, and restart that method only during an approved maintenance window.