ETF(8)

🎀 ETF(8) 🎀

Linux 💖

✨ NAME ✨

okay so ETF stands for Earliest TxTime First (ETF) Qdisc 💅 it's a queueing discipline that's literally all about timing your packets perfectly 🦋

💫 SYNOPSIS 💫

tc qdisc ... dev dev parent classid [ handle major: ] etf clockid
clockid [ delta delta_nsecs ] [ deadline_mode ] [ offload ]

🌸 DESCRIPTION 🌸

bestie, the ETF (Earliest TxTime First) qdisc lets apps decide the exact moment a packet gets dequeued from the traffic control layer and handed off to the netdevice 😭 if offload is configured and the network interface card supports it, it will also control when packets leave the network controller 🔥

ETF does this by holding packets in a buffer until a set amount of time before their transmission time (aka the txtime, or deadline) ⏰ you set that amount with the delta option 🫶

the qdisc keeps an rb-tree internally, so packets are always kept in order by their txtime and get dequeued following the (next) earliest txtime first 👑 it's giving organized, no cap ✨

it relies on the SO_TXTIME socket option and the SCM_TXTIME CMSG in each packet field to set up how time-dependent sockets behave: which clockid is the reference, whether the txtime for that socket is in deadline or strict mode, and whether packet drops should get reported on the socket's error queue 🧚 see socket(7) for more info!!

the etf qdisc will drop any packet with a txtime in the past, or any packet that expires while it's waiting to be dequeued 💀 rip to those

this queueing discipline is meant for TSN (Time Sensitive Networking) apps, and it gives you traffic shaping that vendors and NIC documentation usually call "Launch Time" or "Time-Based Scheduling" 🌈 main character energy for sure

ETF is supposed to sit under another qdisc that sorts packet flows into traffic classes, like mqprio(8) 🍓

🎀 PARAMETERS 🎀

• clockid
  • this is the clock the qdisc's internal timer uses to measure time and schedule events ⏱️ the qdisc expects packets going through it to use this same clockid as the reference for their txtime timestamps, and it will drop packets from sockets that don't follow that 🙈
  • for more on time and clocks on Linux, check out time(7) and clock_gettime(3) 💜
• delta
  • after enqueueing or dequeueing a packet, the qdisc schedules its next wake-up for the next txtime minus this delta value ✨ so delta works like a fudge factor for your system's scheduler latency 🫶
  • this value has to be in nanoseconds, and the default is 0 nanoseconds
• deadline_mode
  • when deadline_mode is set, the qdisc treats txtime differently: instead of a 'strict' transmission time, it becomes a deadline 🔥 in practice, during the dequeue flow etf(8) sets the txtime of the packet being dequeued to 'now' 💅
  • it's disabled by default
• offload
  • when offload is set, etf(8) tries to configure the network interface so time-based transmission arbitration is enabled in the controller 🚀 NICs docs usually call this "Launch Time" or "Time-Based Scheduling" too
  • it's disabled by default
• skip_sock_check
  • okay so etf(8) currently drops any packet that doesn't have a socket attached, or whose socket doesn't have the SO_TXTIME socket option set 😭 but that breaks if the launchtime is set by another entity inside the kernel (like some other Qdisc) 🙈
  • setting skip_sock_check skips the check for a socket attached to the packet ✨

🍓 EXAMPLES 🍓

ETF is used to enforce Quality of Service 💖 it controls when each packet should be dequeued and transmitted, and it can limit the data rate of a traffic class 🌸 to split packets into traffic classes, you can use mqprio(8), and configure it like this:

# tc qdisc add dev eth0 handle 100: parent root mqprio 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 \
     hw 0

to replace the current queueing discipline with ETF in traffic class number 0, issue:

# tc qdisc replace dev eth0 parent 100:1 etf \
     clockid CLOCK_TAI delta 300000 offload

with the options above, etf is set to use CLOCK_TAI as its clockid_t, schedules packets 300 us before their txtime, and enables the functionality on the network interface card 🦋 deadline mode isn't configured for this one, so no deadline vibes here 💅

👑 AUTHORS 👑

• Jesus Sanchez-Palencia <jesus.sanchez-palencia@intel.com> 🫶
• Vinicius Costa Gomes <vinicius.gomes@intel.com> 🫶

that's a wrap, bestie!! 🌈 iproute2 · 05 Jul 2018 ✨ stay timed, stay iconic 💅🎀