isochron(8)
💅 isochron(8) 💅
okay bestie, buckle up, because this is the isochron(8) page from the ISOCHRON manual and it's honestly a whole journey. grab a snack. 🍓
✨ NAME ✨
isochron — a Time sensitive network testing tool. that's it, that's the name, short and iconic. 👑
🌸 SYNOPSIS 🌸
isochron VERB [OPTIONS]
VERB := { daemon | orchestrate | send | rcv | report }so you always pick a VERB first, then the options. five verbs, five vibes. 🫶
🦋 DESCRIPTION 🦋
okay so isochron is a Linux user space application for testing the timing characteristics of endpoints and bridges in Ethernet networks. literally what it says on the tin.
here's the whole plan: the tool sends network packets between one instance of the program (the sender) and another one (the receiver), and it takes timestamps at various points along the way. the receiver also has a second network socket, and it uses that one to transmit its collected timestamps back towards the sender. the sender then aggregates all the timestamps, and optionally records them to a file which you can query at a later time. cute, right? 💾
⏰ the four time bases (they must be in sync, no exceptions)
timestamps get taken in 4 different time bases, and all four have to be in sync with one another or the whole thing is giving chaos:
- Software timestamping using the sender's system clock
- Hardware timestamping inside the sender's NIC
- Hardware timestamping inside the receiver's NIC
- Software timestamping using the receiver's system clock
and the way it makes sure you can directly compare timestamps from different time bases? it monitors the synchronization status of external programs like ptp4l (which synchronizes a local NIC to a remote NIC) and phc2sys (which synchronizes the system clock to a local NIC) from the linuxptp project. teamwork makes the dream work fr fr. 🤝
🌈 what it's actually for
Isochron (isochronous traffic == running at equal intervals, iykyk) is meant to be used in conjunction with Time Sensitive Networking equipment as defined by IEEE 802.1 and IEEE 802.3. the measurements can be used for profiling the software latency of the endpoints, or the forwarding latency of switches. both slay.
⚠️ heads up bestie: the isochron program, in both the sender and the receiver role, requires a network card with the ability to perform hardware timestamping of any packet, since the isochron test packets are not PTP event messages. so like. pick your NIC accordingly. 💀
and if you're using it in a time sensitive network, isochron expects to be the exclusive owner of a traffic class, and it must be informed of that traffic class' time slot length and offset within the global schedule. no sharing, no sneaking in. 💅
🎀 the priority diagram moment
below is an example where isochron uses priority 5, ptp4l uses priority 7, these two traffic classes have media reservations using a time-aware shaper, and the other applications are classified as best-effort and go towards their own time slot:
base-time base-time + cycle-time
|---------------------------------|---------------------------------|
Ethernet media reservation:
|xxxxxxxxxxxxxxxxxxxxxxx|---------|xxxxxxxxxxxxxxxxxxxxxxx|---------| tc012346
<---------------------> <--------------------->
best effort best effort
|-----------------------|xxxx|----|-----------------------|xxxx|----| tc5
<--> <-->
isochron isochron
|----------------------------|xxxx|----------------------------|xxxx| tc7
<--> <-->
ptp4l ptp4l🧚 zooming in on one time slot
focusing on a single time slot (isochron's traffic class 5), the diagram below overlaps a few timelines in order to detail how isochron interprets the command line arguments and how the time is spent:
cycle (N - 1) cycle N cycle (N + 1)
base-time - cycle-time base-time base-time + cycle-time
| | |
| Media reservation | |
| for isochron | |
v v v
|-----------------------|xxxx|----|-----------------------|xxxx|----|-->
| window T0 T1 | window T2 T3 |
| size <----> | size <----> |
| | |
| The shift time specifies | |
| the offset of the time slot | shift-time (H) |
| from the beginning of the cycle |---------------------->| |
| | | |
|-----------------------|xxxx|----|-----------------------|xxxx|----|-->
| | |
| The advance time specifies | |
| how much in advance of the | advance-time (A) |
| deadline to wake up |<---------------------------| |
| | | | |
|-----------------------|xxxx|----|-----------------------|xxxx|----|-->
| | |
| isochron schedules a wakeup | |
| at application base time b and | |
| actually wakes up at time w | |
| | |
|----------------------------|xxxxxxx|------------------------------|-->
| b | w |
| | |
| The time spent by isochron from | |
| wakeup until it enqueues a | |
| packet is negligible and not | |
| measured. The next timestamp | |
| is the pre-qdisc software | |
| TX timestamp (s). | |
| | |
|---------------------------------|--|xxxxx|------------------------|-->
| | w s |
| isochron requests the NIC | |
| driver to take a software TX | |
| timestamp (t). | |
| | |
|---------------------------------|--------|xxxxx|------------------|-->
| | s t |
| isochron requests the NIC | |
| driver to take a hardware TX | |
| timestamp (T). | |
| There are multiple cases. | |
| | |
| If no TSN qdisc is used, the | |
| packet is transmitted right | |
| away, earlier than the | |
| scheduled TX time if all | |
| is well. | |
| | T2 T3 |
|---------------------------------|-----------------------|xxxx|----|-->
|---------------------------------|--------------|xxxxx|------------|-->
| | t T |
| If tc-taprio is used, the | |
| packet is transmitted as soon | |
| as the MAC gate opens (which | |
| may be a few hundred ns later | |
| than the scheduled TX time). | |
| | T2 T3 |
|---------------------------------|-----------------------|xxxx|----|-->
|---------------------------------|--------------|xxxxxxxxx|--------|-->
| | t T ~= S |
| If tc-etf is used, the | |
| packet is transmitted according | |
| to the specified SO_TXTIME cmsg | |
| cmsg, and there is no MAC gate | |
| open/close event per se. | |
| | |
|---------------------------------|--------------|xxxxxxxxx|--------|-->
| | t T ~= S |
| | |
T0, T2: MAC gate open events for cyclic scheduled traffic
T1, T3: MAC gate close events🔥 the deadlines (aka the vibe check)
- when a regular qdisc is used, the deadline which needs to be satisfied by isochron is
(T < S). - when the
tc-taprioqdisc is used, the deadline is(t < T2). - when the
tc-etfqdisc is used, the deadline is(s + delta < S), wheredeltais the "fudge factor" of thetc-etfqdisc.
three different qdiscs, three different rules, zero wiggle room. 😤
💀 BUGS 💀
not me having to tell you this but: versions starting with 0.x should be expected to be unstable, and not necessarily maintain binary compatibility on the network (between sender and receiver) or on the filesystem (the format of the report file).
⚠️ when using an unstable version, it is expected that the producer and the consumer of the data are running the same version of isochron. do not mix and match, bestie, I am begging. 🙈
👑 AUTHOR 👑
isochron was written by Vladimir Oltean vladimir.oltean@nxp.com. we love a credited author. 🫶
🌈 SEE ALSO 🌈
isochron-daemon(8)isochron-orchestrate(1)isochron-send(8)isochron-rcv(8)isochron-report(1)taprio(8)etf(8)
go read those too, they're the rest of the friend group. 💜
🎀 COMMENTS 🎀
this man page was written using pandoc by the same author. self-documenting king behaviour honestly. ✨
and that's the whole thing! it came to you straight from the ISOCHRON manual, closing out on its own isochron(8) footer — thanks for reading the whole page with me, bestie. you ate. 💅💖
📦 where this page comes from
- debian trixie: isochron 0.9-0.2 · GPL-2.0-only
- ubuntu questing: isochron 0.9-0.2
- ubuntu resolute: isochron 0.9-0.2build1 · GPL-2.0-only
- ubuntu stonking: isochron 0.9-0.2build1 · GPL-2.0-only
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms