isochron-report(1)

✨ NAME ✨

isochron-report — gather statistics from logged isochron data 💅

okay so bestie, you're reading isochron-report(1), the report side of the isochron trio, and yes it does exactly what the name says: it digs through the data you already logged and pulls the numbers out. no cap. 🫶

---

🌸 SYNOPSIS 🌸

isochron report [OPTIONS]

---

🦋 DESCRIPTION 🦋

bestie listen. this command opens an isochron.dat file — the one that isochron send generated for you — and filters the requested data out of it. that's the whole vibe. 💖

---

🎀 OPTIONS 🎀

• -h, --help — prints the short help message and then dips. bye! 👋
• -F, --input-file <PATH> — tell it where your input file lives. optional, and if you don't say anything it just assumes isochron.dat.
• -m, --summary — optionally calculate and print a summary of the built-in metrics. the math girlies love this one. 🧮
• -s, --start <NUMBER> — the sequence number of the first packet that counts for printing and for statistics calculation. optional; defaults to sequence number 1 (the very first packet, obviously).
• -S, --stop <NUMBER> — the sequence number of the last packet that counts for printing and for statistics calculation. optional; defaults to a sequence number equal to the number of packets of the test (i.e. the last packet). 💜
• -f, --printf-format <STRING> — the format a packet gets printed in. optional; if you don't specify it, per-packet information is not printed. so like, nothing per-packet. silence. 🙈
• -a, --printf-args <STRING> — the built-in variables that get printed per packet.

---

🌈 PRINTF FORMAT 🌈

the --printf-format argument is a free-form string, and it can also hold up to 256 printf-like codes, each prefixed by the % (percent) character. isochron swaps those printf codes out for each packet, using internal variables taken from the log. heads up: the newline character is NOT added automatically between packets, so if you want lines you better put that \n in yourself. 😭

the printf codes isochron understands are:

• %d — print a built-in variable as a signed integer in decimal format.
• %u — print a built-in variable as an unsigned integer in decimal format.
• %x — print a built-in variable as an unsigned integer in hexadecimal format.
• %T — print a built-in variable in human-readable time format (sec.nsec).

---

🦄 PRINTF VARIABLES 🦄

the --printf-args argument is an array of single-character isochron variable codes. the program pairs each variable code with the printf code from the format specifier, going left to right, to figure out how to print it. so the vibes have to line up in order, iykyk. ✨

the variable codes isochron understands are:

• A — advance time as defined by isochron send --advance-time. can be printed using %d, %u, %x or %T.
• B — base time as defined by isochron send --base-time, then adjusted by the sender application using the shift time and advanced into the immediate future at the time of the test. the base time minus the advance time denotes the programmed time of the wakeup timer for the sender's first packet. can be printed using %d, %u, %x or %T.
• C — cycle time as defined by isochron send --cycle-time. can be printed using %d, %u, %x or %T.
• H — shift time as defined by isochron send --shift-time. can be printed using %d, %u, %x or %T.
• W — window size as defined by isochron send --window-size. can be printed using %d, %u, %x or %T.
• S — scheduled TX time of the packet (the time at which the packet must hit the wire). can be printed using %d, %u, %x or %T.
• w — the actual value of the CLOCK_TAI system clock when the sender starts executing code again immediately after its wakeup timer for the packet has expired. can be printed using %d, %u, %x or %T.
• T — TX hardware timestamp of the packet, taken by the NIC of the sender. can be printed using %d, %u, %x or %T.
• t — TX software timestamp of the packet, taken by the NIC driver of the sender right before hardware transmission. can be printed using %d, %u, %x or %T.
• s — TX software timestamp of the packet, taken by the network stack prior to entering the packet scheduler (qdisc). can be printed using %d, %u, %x or %T.
• q — sequence number of the packet, starting from 1. can be printed using %u or %x.
• a — the arrival time of the packet, i.e. the actual value of the CLOCK_TAI system clock when the receiver starts executing code again immediately after fully receiving the packet. can be printed using %d, %u, %x or %T.
• R — RX hardware timestamp of the packet, taken by the NIC of the receiver. can be printed using %d, %u, %x or %T.
• r — RX software timestamp of the packet, taken by the NIC driver right after reception from hardware. can be printed using %d, %u, %x or %T.

---

👑 BUILT-IN METRICS 👑

when you run with the --summary option, isochron defines some latency-related metrics and then calculates the following statistics on them: maximum value, minimum value, packet sequence number associated with the min and max, mean value, standard deviation. it's giving data science. 📊

the built-in metrics are:

Path delay

R - T (HW TX timestamp to HW RX timestamp)

Sender latency

t - w (actual sender wakeup time to SW TX timestamp)

MAC latency

T - S (scheduled TX time to HW TX timestamp)

Application latency budget ("time to spare per cycle")

S - T (time until HW TX timestamp would exceed scheduled TX time)

Wakeup latency

w - (S - A) (programmed wakeup time, i.e. scheduled TX time minus advance time, to actual wakeup time)

Driver latency (actually driver + qdisc latency)

t - s (pre-qdisc timestamp to driver-level software TX timestamp)

Arrival latency

a - R (HW RX timestamp to application)

---

notice how the "MAC latency" and the "Application latency budget" is the same metric, but calculated in reverse. 👀 the data is interpreted by the application depending on whether the hardware was expected to send the packet right away, or queue it until the scheduled TX time like in the case of the tc-taprio and tc-etf qdiscs.

---

💅 EXAMPLES 💅

1. to obtain the summary of the built-in metrics:

isochron report \
    --input-file isochron.dat \
    --summary

2. to see the detailed network timestamps for a single packet:

isochron report \
    --input-file isochron.dat \
    --printf-format "seqid %u scheduled for %T, TX qdisc %T sw %T hw %T, RX hw %T sw %T\n" \
    --printf-args "qSstTRr" \
    --start 173972 --stop 173972

3. to export data in comma-separated value format, for calculating user-defined metrics externally:

isochron report \
    --input-file isochron.dat \
    --printf-format "%d,%d\n" \
    --printf-args "TR" \
    > isochron.csv

4. user-defined arithmetic on the built-in isochron variables can also be delegated to a scripting language interpreter such as Python, by configuring the isochron printf format specifier to generate output in Python syntax:

isochron report \
    --printf-format "pdelay=%d - %d\nprint(\"path_delay[%u] =\", pdelay)\n" \
    --printf-args "RTq" \
    | python3 -

5. for more complex arithmetic, the per-packet internal variables can be stored inside arrays:

printf "wakeup_latency = {}\n" > isochron_data.py
isochron report \
    --printf-format "wakeup_latency[%u] = %d - (%d - %d)\n" \
    --printf-args "qwSA" \
    >> isochron_data.py
cat << 'EOF' > isochron_postprocess.py
#!/usr/bin/env python3

from isochron_data import wakeup_latency
import numpy as np

w = np.array(list(wakeup_latency.values()))
print("Wakeup latency: min {}, max {}, mean {}, median {}, stdev {}".format(np.min(w), np.max(w), np.mean(w), np.median(w), np.std(w)))
EOF
python3 ./isochron_postprocess.py

---

🍓 AUTHOR 🍓

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

---

🌟 SEE ALSO 🌟

isochron(8) isochron-send(8) isochron-rcv(8)

---

💜 COMMENTS 💜

this man page was written using pandoc by the same author. iconic behavior honestly. 🎀

---

okay bestie that's the whole page!! 🦋 the footer at the bottom just says isochron-report(1) — that's the manual and section this lives in, part of the ISOCHRON collection — so go log some data and go read it. slay, periodt. 💖✨👑