From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jesus Sanchez-Palencia Subject: [PATCH v4 iproute2-next 3/3] man: Add initial manpage for tc-etf(8) Date: Mon, 9 Jul 2018 16:56:13 -0700 Message-ID: <20180709235613.23642-4-jesus.sanchez-palencia@intel.com> References: <20180709235613.23642-1-jesus.sanchez-palencia@intel.com> Cc: jhs@mojatatu.com, xiyou.wangcong@gmail.com, jiri@resnulli.us, dsahern@gmail.com, Jesus Sanchez-Palencia To: netdev@vger.kernel.org Return-path: Received: from mga14.intel.com ([192.55.52.115]:9285 "EHLO mga14.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754535AbeGJABf (ORCPT ); Mon, 9 Jul 2018 20:01:35 -0400 In-Reply-To: <20180709235613.23642-1-jesus.sanchez-palencia@intel.com> Sender: netdev-owner@vger.kernel.org List-ID: Add an initial manpage for tc-etf covering all config options, basic concepts and operation modes. Signed-off-by: Jesus Sanchez-Palencia --- man/man8/tc-etf.8 | 141 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 man/man8/tc-etf.8 diff --git a/man/man8/tc-etf.8 b/man/man8/tc-etf.8 new file mode 100644 index 00000000..30a12de7 --- /dev/null +++ b/man/man8/tc-etf.8 @@ -0,0 +1,141 @@ +.TH ETF 8 "05 Jul 2018" "iproute2" "Linux" +.SH NAME +ETF \- Earliest TxTime First (ETF) Qdisc +.SH SYNOPSIS +.B tc qdisc ... dev +dev +.B parent +classid +.B [ handle +major: +.B ] etf clockid +clockid +.B [ delta +delta_nsecs +.B ] [ deadline_mode ] +.B [ offload ] + +.SH DESCRIPTION +The ETF (Earliest TxTime First) qdisc allows applications to control +the instant when a packet should be dequeued from the traffic control +layer into the netdevice. If +.B offload +is configured and supported by the network interface card, the it will +also control when packets leave the network controller. + +ETF achieves that by buffering packets until a configurable time +before their transmission time (i.e. txtime, or deadline), which can +be configured through the +.B delta +option. + +The qdisc uses a rb-tree internally so packets are always 'ordered' by +their txtime and will be dequeued following the (next) earliest txtime +first. + +It relies on the SO_TXTIME socket option and the SCM_TXTIME CMSG in +each packet field to configure the behavior of time dependent sockets: +the clockid to be used as a reference, if the expected mode of txtime +for that socket is deadline or strict mode, and if packet drops should +be reported on the socket's error queue. See +.BR socket(7) +for more information. + +The etf qdisc will drop any packets with a txtime in the past, or if a +packet expires while waiting for being dequeued. + +This queueing discipline is intended to be used by TSN (Time Sensitive +Networking) applications, and it exposes a traffic shaping functionality +that is commonly documented as "Launch Time" or "Time-Based Scheduling" +by vendors and the documentation of network interface controllers. + +ETF is meant to be installed under another qdisc that maps packet flows +to traffic classes, one example is +.BR mqprio(8). + +.SH PARAMETERS +.TP +clockid +.br +Specifies the clock to be used by qdisc's internal timer for measuring +time and scheduling events. The qdisc expects that packets passing +through it to be using this same +.B clockid +as the reference of their txtime timestamps. It will drop packets +coming from sockets that do not comply with that. + +For more information about time and clocks on Linux, please refer +to +.BR time(7) +and +.BR clock_gettime(3). + +.TP +delta +.br +After enqueueing or dequeueing a packet, the qdisc will schedule its +next wake-up time for the next txtime minus this delta value. +This means +.B delta +can be used as a fudge factor for the scheduler latency of a system. +This value must be specified in nanoseconds. +The default value is 0 nanoseconds. + +.TP +deadline_mode +.br +When +.B deadline_mode +is set, the qdisc will handle txtime with a different semantics, +changed from a 'strict' transmission time to a deadline. +In practice, this means during the dequeue flow +.BR etf(8) +will set the txtime of the packet being dequeued to 'now'. +The default is for this option to be disabled. + +.TP +offload +.br +When +.B offload +is set, +.BR etf(8) +will try to configure the network interface so time-based transmission +arbitration is enabled in the controller. This feature is commonly +referred to as "Launch Time" or "Time-Based Scheduling" by the +documentation of network interface controllers. +The default is for this option to be disabled. + +.SH EXAMPLES + +ETF is used to enforce a Quality of Service. It controls when each +packets should be dequeued and transmitted, and can be used for +limiting the data rate of a traffic class. To separate packets into +traffic classes the user may choose +.BR mqprio(8), +and configure it like this: + +.EX +# tc qdisc add dev eth0 handle 100: parent root mqprio num_tc 3 \\ + map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \\ + queues 1@0 1@1 2@2 \\ + hw 0 +.EE +.P +To replace the current queueing discipline by ETF in traffic class +number 0, issue: +.P +.EX +# tc qdisc replace dev eth0 parent 100:1 etf \\ + clockid CLOCK_TAI delta 300000 offload +.EE + +With the options above, etf will be configured to use CLOCK_TAI as +its clockid_t, will schedule packets for 300 us before their txtime, +and will enable the functionality on that in the network interface +card. Deadline mode will not be configured for this mode. + +.SH AUTHORS +Jesus Sanchez-Palencia +.br +Vinicius Costa Gomes -- 2.18.0