man/man8/tc-etf.8

   1 .TH ETF 8 "05 Jul 2018" "iproute2" "Linux"
   2 .SH NAME
   3 ETF \- Earliest TxTime First (ETF) Qdisc
   4 .SH SYNOPSIS
   5 .B tc qdisc ... dev
   6 dev
   7 .B parent
   8 classid
   9 .B [ handle
  10 major:
  11 .B ] etf clockid
  12 clockid
  13 .B [ delta
  14 delta_nsecs
  15 .B ] [ deadline_mode ]
  16 .B [ offload ]
  17
  18 .SH DESCRIPTION
  19 The ETF (Earliest TxTime First) qdisc allows applications to control
  20 the instant when a packet should be dequeued from the traffic control
  21 layer into the netdevice. If
  22 .B offload
  23 is configured and supported by the network interface card, the it will
  24 also control when packets leave the network controller.
  25
  26 ETF achieves that by buffering packets until a configurable time
  27 before their transmission time (i.e. txtime, or deadline), which can
  28 be configured through the
  29 .B delta
  30 option.
  31
  32 The qdisc uses a rb-tree internally so packets are always 'ordered' by
  33 their txtime and will be dequeued following the (next) earliest txtime
  34 first.
  35
  36 It relies on the SO_TXTIME socket option and the SCM_TXTIME CMSG in
  37 each packet field to configure the behavior of time dependent sockets:
  38 the clockid to be used as a reference, if the expected mode of txtime
  39 for that socket is deadline or strict mode, and if packet drops should
  40 be reported on the socket's error queue. See
  41 .BR socket(7)
  42 for more information.
  43
  44 The etf qdisc will drop any packets with a txtime in the past, or if a
  45 packet expires while waiting for being dequeued.
  46
  47 This queueing discipline is intended to be used by TSN (Time Sensitive
  48 Networking) applications, and it exposes a traffic shaping functionality
  49 that is commonly documented as "Launch Time" or "Time-Based Scheduling"
  50 by vendors and the documentation of network interface controllers.
  51
  52 ETF is meant to be installed under another qdisc that maps packet flows
  53 to traffic classes, one example is
  54 .BR mqprio(8).
  55
  56 .SH PARAMETERS
  57 .TP
  58 clockid
  59 .br
  60 Specifies the clock to be used by qdisc's internal timer for measuring
  61 time and scheduling events. The qdisc expects that packets passing
  62 through it to be using this same
  63 .B clockid
  64 as the reference of their txtime timestamps. It will drop packets
  65 coming from sockets that do not comply with that.
  66
  67 For more information about time and clocks on Linux, please refer
  68 to
  69 .BR time(7)
  70 and
  71 .BR clock_gettime(3).
  72
  73 .TP
  74 delta
  75 .br
  76 After enqueueing or dequeueing a packet, the qdisc will schedule its
  77 next wake-up time for the next txtime minus this delta value.
  78 This means
  79 .B delta
  80 can be used as a fudge factor for the scheduler latency of a system.
  81 This value must be specified in nanoseconds.
  82 The default value is 0 nanoseconds.
  83
  84 .TP
  85 deadline_mode
  86 .br
  87 When
  88 .B deadline_mode
  89 is set, the qdisc will handle txtime with a different semantics,
  90 changed from a 'strict' transmission time to a deadline.
  91 In practice, this means during the dequeue flow
  92 .BR etf(8)
  93 will set the txtime of the packet being dequeued to 'now'.
  94 The default is for this option to be disabled.
  95
  96 .TP
  97 offload
  98 .br
  99 When
 100 .B offload
 101 is set,
 102 .BR etf(8)
 103 will try to configure the network interface so time-based transmission
 104 arbitration is enabled in the controller. This feature is commonly
 105 referred to as "Launch Time" or "Time-Based Scheduling" by the
 106 documentation of network interface controllers.
 107 The default is for this option to be disabled.
 108
 109 .SH EXAMPLES
 110
 111 ETF is used to enforce a Quality of Service. It controls when each
 112 packets should be dequeued and transmitted, and can be used for
 113 limiting the data rate of a traffic class. To separate packets into
 114 traffic classes the user may choose
 115 .BR mqprio(8),
 116 and configure it like this:
 117
 118 .EX
 119 # tc qdisc add dev eth0 handle 100: parent root mqprio num_tc 3 \\
 120         map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \\
 121         queues 1@0 1@1 2@2 \\
 122         hw 0
 123 .EE
 124 .P
 125 To replace the current queueing discipline by ETF in traffic class
 126 number 0, issue:
 127 .P
 128 .EX
 129 # tc qdisc replace dev eth0 parent 100:1 etf \\
 130         clockid CLOCK_TAI delta 300000 offload
 131 .EE
 132
 133 With the options above, etf will be configured to use CLOCK_TAI as
 134 its clockid_t, will schedule packets for 300 us before their txtime,
 135 and will enable the functionality on that in the network interface
 136 card. Deadline mode will not be configured for this mode.
 137
 138 .SH AUTHORS
 139 Jesus Sanchez-Palencia <jesus.sanchez-palencia@intel.com>
 140 .br
 141 Vinicius Costa Gomes <vinicius.gomes@intel.com>