isochron-send(8)

📦
version 0.9 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ isochron-send(8) ✨

okay bestie, sit DOWN, because we're about to talk about isochron-send from the ISOCHRON family of manual pages, section 8, and it's giving very serious networking main character energy 💅

🌸 NAME 🌸

isochron-send — start an isochron test while playing the role of the sender 🫶

🦋 SYNOPSIS 🦋

isochron send [OPTIONS]

💖 DESCRIPTION 💖

this command sends test packets, and it does it using whatever transport you told it to use — either plain Ethernet or UDP. that's the whole vibe. simple. iconic. no cap. ✨

👑 OPTIONS 👑

so like. here's every single flag, and yes we're doing ALL of them, because we don't skip. periodt. 🎀

  • -h, --help — prints the short help message and then dips out. that's it, that's the flag. 💫
  • -i, --interface <IFNAME> — tells everyone which network interface the packets are gonna be sent on. pick your fave. 🌈
  • -d, --dmac <MACADDRESS> — sets the destination MAC address for the test packets. it should match the MAC address that the receiver is listening for, so coordinate with your bestie on the other end, fr fr. it can be either unicast or multicast. this one is only necessary for the L2 transport (plain Ethernet). it's optional if you also passed --client, because in that case the sender can just go ask the receiver directly what destination MAC address it's listening for. 👑
  • -A, --smac <MACADDRESS> — sets the source MAC address for the test packets. optional, and it defaults to the network interface's unicast address. only necessary for the L2 transport. 💅
  • -p, --priority <NUMBER> — sets the SO_PRIORITY (that's the traffic class) that gets communicated to the kernel for the test packets. qdiscs like tc-mqprio or tc-taprio actually use this. optional, defaults to 0. 🌸
  • -P, --stats-port <NUMBER> — sets the TCP port where the receiver program is listening for incoming connections. this socket is the management-and-statistics socket, iykyk. optional, defaults to port 5000. 🎀
  • -b, --base-time <TIME> — sets the scheduled transmission time for the very first packet. you can shift this forward and backwards in time later with the --shift-time argument. here's the cute part: this time is allowed to be in the past, and if it is, it gets automatically advanced by an integer number of cycles until it's larger than the current time by at least one second. the time base is CLOCK_TAI. optional, defaults to 0. ⏰
  • -a, --advance-time <TIME> — sets how far in advance of the scheduled packet transmission time isochron will wake up. optional, and it defaults to the cycle time minus the window size, which means the sender wakes up at the earliest possible moment and gets the longest possible amount of time to prepare for transmission. bestie said "early bird gets the worm" 🐦
  • -S, --shift-time <TIME> — shifts the base time by the specified amount of nanoseconds, either into the past or into the future. this is super useful when you're enqueuing packets into a NIC that uses a tc-taprio qdisc and the time slot for your application's traffic class is not the first one. when you use it that way, you can set the application's base time equal to the base time of the tc-taprio schedule, and set the shift time to the length of all the time slots that come before the one your application should enqueue in. optional, defaults to 0. 🦋
  • -c, --cycle-time <TIME> — sets the interval between consecutive wakeup times, for the purpose of sending a packet. 💫
  • -w, --window-size <TIME> — when the NIC uses a tc-taprio schedule, this sets the duration in nanoseconds of the time slot that corresponds to the application's priority. this stops isochron from waking up too early and potentially enqueuing the packet prematurely into its time slot from the previous cycle. with a correctly configured window size, the wakeup time gets set no earlier than the end of the previous time slot, which makes that condition impossible (assuming proper system clock synchronization, obviously). optional, defaults to 0. 🔥
  • -n, --num-frames <NUMBER> — sets how many packets to send for this test. optional — and if you leave it unspecified, the program just runs indefinitely, but it will not collect logs. go off, infinite loop, we guess 😭
  • -s, --frame-size <NUMBER> — sets the size of the test frames. the size is counted from the first octet of the destination MAC address all the way until the last octet of data before the FCS. measure carefully, bestie 📏
  • -T, --no-ts — disables the whole process of collecting TX timestamps. 🙈
  • -v, --vid <NUMBER> — inserts a VLAN header with the specified VLAN ID into the test packets. the VLAN PCP gets set equal to the priority you configured with --priority. this has lower overhead compared to using a kernel VLAN interface to insert the VLAN tag, so it's the efficient choice, and we love that. optional, defaults to no VLAN header being inserted at all. 🎀
  • -C, --client <IPADDRESS> — sets the IPv4 or IPv6 address where the receiver is listening for management/statistics connections. optional, and it defaults to not attempting to connect to the receiver. and when you don't connect, the sender operates in a limited mode where it does not collect logs and does not check the receiver's sync status or its expected destination MAC address. also, the receiver won't log packets unless the sender connects to it, so like... keep that in mind. 💀
  • -q, --quiet — when the sender is not connected to the receiver's management/statistics socket, it will by default print the packets and their TX timestamps to standard output at the end of the test. this option suppresses that print. optional, defaults to false. shhh 🤫
  • -e, --etype <NUMBER> — sets the EtherType for test packets sent using the L2 transport. optional, defaults to 0xdead. cute hex, love that for us 🍓
  • -o, --omit-sync — when set, the sender will not monitor the local ptp4l and phc2sys processes for synchronization status (and optionally the remote ones too, if --client is being used), and it'll just proceed to send test packets regardless. optional, defaults to false. chaotic but valid ✨
  • -y, --omit-remote-sync — when set, it will only monitor the sync status of the local station. the assumption here is that the receiver interface is implicitly synchronized (it shares the same PHC as the sender interface), and therefore no ptp4l instance runs on it, so the sync status can't be monitored anyway. optional, defaults to false. 🧚
  • -m, --tracemark — when set, the sender writes to the kernel's ftrace buffer to mark the moment it wakes up to transmit a packet, plus the moment right after the packet has been enqueued into the kernel. this is the debugging bestie for latency issues — use it together with trace-cmd and kernelshark, because the packet's sequence number gets logged, which means latencies reported by the isochron report can be quickly associated with the kernel trace buffer. optional, defaults to false. 🔍
  • -Q, --taprio — when set, the sender records this information to the output file. this changes how the logged data is interpreted — for example, with tc-taprio, TX timestamps are expected to be higher than the scheduled transmission time, whereas otherwise they're expected to be lower. you're expected to set this option when you're enqueuing to a NIC where tc-taprio is the qdisc. 👑
  • -x, --txtime — when set, the sender uses the SO_TXTIME socket option when enqueuing packets to the kernel. this also changes the interpretation of logged data, similar to --taprio. the TX time that the sender requests is equal to the scheduled transmission time for the packet. you're expected to set this option when enqueuing to a NIC where tc-etf is the qdisc. 🔥
  • -D, --deadline — when set, this sets the SOF_TXTIME_DEADLINE_MODE flag for the data socket. heads up: this can only be used together with --txtime. this option changes the kernel's interpretation of the TX time — it's no longer the PTP time at which the packet should be sent, but rather the latest moment in time at which the packet should be sent. so like, the deadline. obviously. ⏳
  • -f, --sched-fifo — when set, the program requests that the kernel change its scheduling policy to SCHED_FIFO for the duration of the test. 💅
  • -r, --sched-rr — when set, the program requests that the kernel change its scheduling policy to SCHED_RR for the duration of the test. 🌀
  • -H, --sched-priority <NUMBER> — when either --sched-fifo or --sched-rr is being used, the program requests that the kernel change its scheduling priority for the duration of the test. ⭐
  • -M, --cpu-mask <NUMBER> — a bit mask of the CPUs on which the sender thread is allowed to be scheduled. note that the program's other threads are not affected by this selection. optional, defaults to the CPU affinity of the isochron process. 📌
  • -O, --utc-tai-offset <NUMBER> — the program uses the CLOCK_TAI time base for its timers and for all reported timestamps, and this option specifies the correction in seconds to apply to software timestamps, which the kernel takes in the CLOCK_REALTIME (UTC) time base. if this option is present, isochron will also change the kernel's CLOCK_TAI offset to the specified value, to make sure its timers fire correctly. if the option is absent, isochron queries the kernel's CLOCK_TAI offset and tries to use that. and if isochron can also query the UTC offset from ptp4l's TIME_PROPERTIES_DATA_SET using management messages, it does that too and compares that offset to the kernel's UTC offset. plot twist: the UTC offset reported by ptp4l has the highest priority, so if the application detects that it's different from the kernel's CLOCK_TAI offset, it changes the kernel offset to the value queried from ptp4l. ptp4l is the one in charge here, basically 👑
  • -J, --ip-destination <IPADDRESS> — sets the IPv4 or IPv6 address of the receiver, which gets placed in the test packet datagrams. mandatory if the UDP transport is used, no exceptions. also, a heads up: when you're using the UDP transport, the destination IP address should have a static entry in the kernel's IP neighbor table, to avoid unpredictable latencies caused by the kernel's neighbor resolution process. and one more thing — the isochron program does not have control over which interface gets used for sending the test packets, so you (yes, you, bestie) should make sure the kernel's routing table will select the correct interface for this destination IP address. the program is not gonna hold your hand on this one 🫶
  • -2, --l2 — this option specifies that the plain Ethernet transport should be used for the test packets. optional, defaults to true. and it cannot be used together with --l4. pick a lane, we can't do both 💀
ok and that's the end of part one, bestie — there's more coming, so don't go anywhere 🎀
  • -4, --l4 — bestie, this one says "we're doing UDP for the test packets." 💌 Optional, and it defaults to false. ⚠️ You cannot use it together with --l2, okay? Pick a lane. 🛣️
  • -W, --data-port <NUMBER> — if you went with the UDP transport, this is the destination UDP port for test packets. 🎯 Optional, defaults to 6000. That's the whole vibe. ✨
  • -U, --unix-domain-socket <PATH> — so isochron finds out what ptp4l is up to by creating and sending PTP management messages over a local UNIX domain socket. 🧦 This option tells it where that socket lives in the filesystem. Optional, defaults to /var/run/ptp4l. 📁
  • -N, --domain-number <NUMBER> — this is the domainNumber value used when constructing the PTP management messages that get sent to the ptp4l process. 📨 It must match the domainNumber that ptp4l is using, otherwise it literally will not respond to management messages and you'll be sitting there like 👁️👄👁️. Optional, defaults to 0.
  • -t, --transport-specific <NUMBER> — same energy, different field: this provides the transportSpecific value used when constructing PTP management messages sent to ptp4l. 🛰️ It must coincide with the transportSpecific that ptp4l uses, or again — no response, ghosted. 💀 Optional, defaults to 0. And heads up 🫶: PTP variants like IEEE 802.1AS/gPTP need this set to a different value, such as 1.
  • -X, --sync-threshold <TIME> — when the program is set up to monitor the sync status of ptp4l and phc2sys, this specifies the positive threshold in nanoseconds that the absolute offset reported by those external programs has to beat to count as "good enough to start the test." 🏁 Mandatory — unless you passed --omit-sync, in which case you're off the hook. 🙈
  • -R, --num-readings <NUMBER> — okay so here's what isochron does: it monitors the synchronization quality between the NIC's PTP Hardware Clock (PHC) and the system time by reading the system time, then the PHC time, then the system time again — several times in a row — and then it picks the group of 3 time readouts that took the least amount of time overall. 🕵️‍♀️ Iconic detective work, honestly. This option says how many readouts happen before picking the fastest one. Optional, defaults to 5. ⏱️
  • -F, --output-file <PATH> — save the packet timestamps to a file so you can query them later with isochron report. 📝 Defaults to isochron.dat. This requires the --client option, because logging only TX timestamps is not supported — the girlies need both sides of the story. 💅

🌈 EXAMPLES 🌈

Wanna spin up an isochron sender with PTP synchronization and a tc-taprio qdisc? Say less. 👑

ip link set eth0 up && ip addr add 192.168.100.1/24 dev eth0
ptp4l -i eth0 -2 -P --step_threshold 0.00002 &
phc2sys -a -rr --step_threshold 0.00002 &
tc qdisc add dev eth0 root taprio num_tc 5 \
    map 0 1 2 3 4 \
    queues 1@0 1@1 1@2 1@3 1@4 \
    base-time 0 \
    sched-entry S 10  50000 \
    sched-entry S 0f 450000 \
    flags 2
taskset $((1 << 0)) isochron send \
    --cpu-mask $((1 << 1)) \
    --interface eth0 \
    --cycle-time 0.0005 \
    --frame-size 64 \
    --num-frames 1000000 \
    --client 192.168.100.2 \
    --quiet \
    --sync-threshold 2000 \
    --output-file isochron.dat \
    --taprio \
    --priority 4 \
    --sched-rr \
    --sched-priority 98 \
    --window-size 50000

Copy it, run it, thrive. 🫶✨

👑 AUTHOR 👑

isochron was written by Vladimir Oltean vladimir.oltean@nxp.com 💖

🦋 SEE ALSO 🦋

isochron(8) isochron-rcv(8) isochron-report(1) — go read them, they're all part of the same slay. 📚

💬 COMMENTS 💬

This man page was written using pandoc by the same author. 🎀

And that's a wrap, bestie!! 🌸 This was the isochron-send(8) manual page — that's the source and the version footer vibe right there, with its date and everything. Not me getting emotional over a man page 😭💜 Go forth and send some packets. Periodt. 💅✨

📦 where this page comes from