DOKK / manpages / debian 12 / isochron / isochron-send.8.en
isochron-send(8) ISOCHRON isochron-send(8)

isochron-send - Start an isochron test in the role of a sender

isochron send [OPTIONS]

This command sends test packets using the specified transport (plain Ethernet or UDP).

prints the short help message and exits
specify the network interface on which packets will be sent
specify the destination MAC address to be used for the test packets. Should coincide with the MAC address that the receiver listens for. Can be either unicast or multicast. Necessary only for the L2 transport (plain Ethernet). Optional if the --client option is also specified, case in which the sender can directly query the receiver for the destination MAC address it listens for.
specify the source MAC address to be used for the test packets. Optional, defaults to the network interface’s unicast address. Necessary only for the L2 transport.
specify the SO_PRIORITY (traffic class) to communicate to the kernel for test packets. Used by qdiscs such as tc-mqprio or tc-taprio. Optional, defaults to 0.
specify the TCP port on which the receiver program is listening for incoming connections. This socket is used for management and statistics. Optional, defaults to port 5000.
specify the scheduled transmission time for the first packet. This can be further shifted forward and backwards in time with the --shift-time argument. This time can be in the past, and in that case it is automatically advanced by an integer number of cycles until it becomes larger than the current time by at least one second. The time base is CLOCK_TAI. Optional, defaults to 0.
specify the amount in advance of the scheduled packet transmission time that isochron will wake up at. Optional, defaults to the cycle time minus the window size, so that the sender will wake up at the earliest possible moment and have the longest possible amount of time for preparing for transmission.
shift the base time by the specified amount of nanoseconds, either in the past or in the future. Useful when enqueuing packets into a NIC which uses a tc-taprio qdisc and the time slot corresponding to the applications’s traffic class is not the first one. When used in this way, the base time of the application can be specified as equal to the base time of the tc-taprio schedule, and the shift time can be specified as the length of all time slots prior to the one in which the application should enqueue. Optional, defaults to 0.
specify the interval between consecutive wakeup times for the purpose of sending a packet.
in case the NIC uses a tc-taprio schedule, specify the duration in nanoseconds of the time slot corresponding to the application’s priority. This will prevent isochron from waking up too early and potentially enqueuing the packet prematurely in its time slot from the previous cycle. With a correctly configured window size, the wakeup time will be set no earlier than the end of the previous time slot, making this condition impossible (assuming proper system clock synchronization). Optional, defaults to 0.
specify the number of packets to send for this test. Optional, if left unspecified the program will run indefinitely, but will not collect logs.
specify the size of test frames. The size is counted from the first octet of the destination MAC address until the last octet of data before the FCS.
disable the process of collecting TX timestamps.
insert a VLAN header with the specified VLAN ID in the test packets. The VLAN PCP is set to be equal to the priority configured with --priority. This results in lower overhead compared to using a kernel VLAN interface to insert the VLAN tag. Optional, defaults to no VLAN header being inserted.
specify the IPv4 or IPv6 address at which the receiver is listening for management/statistics connections. Optional, defaults to not attempting to connect to the receiver. In this case, the sender operates in a limited mode where it does not collect logs or check for the receiver’s sync status or expected destination MAC address. The receiver will also not log packets unless the sender connects to it.
when not connected to the receiver’s management/statistics socket, the sender will, by default, print the packets and their TX timestamps, to standard output at the end of the test. This option suppresses the print. Optional, defaults to false.
specify the EtherType for test packets sent using the L2 transport. Optional, defaults to 0xdead.
when set, the sender will not monitor the local (and optionally remote, if --client is used) ptp4l and phc2sys processes for synchronization status, and will proceed to send test packets regardless. Optional, defaults to false.
when set, will only monitor the sync status of the local station. The assumption is that the receiver interface is implicitly synchronized (shares the same PHC as the sender interface), and therefore no ptp4l instance runs on it, so the sync status cannot be monitored. Optional, defaults to false.
when set, the sender will write to the kernel’s ftrace buffer in order to mark the moment when it wakes up for transmitting a packet, and the moment after the packet has been enqueued into the kernel. The option is useful for debugging latency issues together with trace-cmd and kernelshark, since the packet’s sequence number is logged, and therefore, latencies reported by isochron report can be quickly be associated with the kernel trace buffer. Optional, defaults to false.
when set, the sender will record this information to the output file. This changes the interpretation of the logged data, for example TX timestamps with tc-taprio are expected to be higher than the scheduled transmission time, otherwise they are expected to be lower. The option is expected to be set when enqueuing to a NIC where tc-taprio is used as the qdisc.
when set, the sender will use 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 requested by the sender is equal to the scheduled transmission time for the packet. This option is expected to be set when enqueuing to a NIC where tc-etf is used as the qdisc.
when set, this sets the SOF_TXTIME_DEADLINE_MODE flag for the data socket. This can only be used together with --txtime. This option changes the kernel’s interpretation of the TX time, in that it is 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.
when set, the program requests the kernel to change its scheduling policy to SCHED_FIFO for the duration of the test.
when set, the program requests the kernel to change its scheduling policy to SCHED_RR for the duration of the test.
when either --sched-fifo or --sched-rr is used, the program requests the kernel to change its scheduling priority for the duration of the test.
a bit mask of CPUs on which the sender thread is allowed to be scheduled. The other threads of the program are not affected by this selection. Optional, defaults to the CPU affinity of the isochron process.
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 are taken by the kernel 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 ensure that its timers fire correctly. If the option is absent, isochron queries the kernel’s CLOCK_TAI offset and attempts to use that. If isochron can also query the UTC offset from ptp4l’s TIME_PROPERTIES_DATA_SET using management messages, it does that and compares that offset to the kernel’s UTC offset. The UTC offset reported by ptp4l has the highest priority, and if the application detects that this is different from the kernel’s CLOCK_TAI offset, it changes the kernel offset to the value queried from ptp4l.
this option specifies the IPv4 or IPv6 address of the receiver, which will be placed in the test packet datagrams. Mandatory if the UDP transport is used. Note that when 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. The isochron program does not have control over which interface will be used for sending the test packets, so the user should ensure that the kernel’s routing table will select the correct interface for this destination IP address.
-2, --l2
this option specifies that the plain Ethernet transport should be used for the test packets. Optional, defaults to true. Cannot be used together with --l4.
-4, --l4
this option specifies that the UDP transport should be used for test packets. Optional, defaults to false. Cannot be used together with --l2.
if the UDP transport is used, this option specifies the destination UDP port for test packets. Optional, defaults to 6000.
isochron queries ptp4l’s state by creating and sending PTP management messages over a local UNIX domain socket. This option specifies the path of this socket in the filesystem. Optional, defaults to /var/run/ptp4l.
this option provides the domainNumber value to be used when constructing PTP management messages sent to the ptp4l process. It must coincide with the domainNumber used by ptp4l, otherwise it will not respond to management messages. Optional, defaults to 0.
this option provides the transportSpecific value to be used when constructing PTP management messages sent to the ptp4l process. It must coincide with the transportSpecific used by ptp4l, otherwise it will not respond to management messages. Optional, defaults to 0. Note that PTP variants such as IEEE 802.1AS/gPTP require this value to be set to a different value such as 1.
when the program is configured to monitor the sync status of ptp4l and phc2sys, this option specifies the positive threshold in nanoseconds by which the absolute offset reported by these external programs is qualified as sufficient to start the test. Mandatory unless --omit-sync is specified.
isochron monitors the synchronization quality between the NIC’s PTP Hardware Clock (PHC) and the system time by successively reading the system time, the PHC time and the system time again, several times in a row, and picking the group of 3 time readouts that took the least amount of time overall. This option specifies how many readouts should be performed before picking the fastest one. Optional, defaults to 5.
save the packet timestamps to a file that can be queried at a later time using isochron report. Defaults to “isochron.dat”. This requires the --client option, since logging only TX timestamps is not supported.

To start an isochron sender with PTP synchronization and a tc-taprio qdisc:

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

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

isochron(8) isochron-rcv(8) isochron-report(1)

This man page was written using pandoc (http://pandoc.org/) by the same author.