[iproute2] man: tc-taprio.8: document the full offload feature

Commit Message

Vladimir Oltean Jan. 21, 2021, 9:47 p.m. UTC

From: Vladimir Oltean <[e-mail]>

Since this feature's introduction in commit 9c66d1564676 ("taprio: Add
support for hardware offloading") from kernel v5.4, it never got
documented in the man pages. Due to this reason, we see customer reports
of seemingly contradictory information: the community manpages claim
there is no support for full offload, nonetheless many silicon vendors
have already implemented it.

This patch documents the full offload feature (enabled by specifying
"flags 2" to the taprio qdisc) and gives one more example that tries to
illustrate some of the finer points related to the usage.

Signed-off-by: Vladimir Oltean <[e-mail]>
---
 man/man8/tc-taprio.8 | 58 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 50 insertions(+), 8 deletions(-)

Comments

Vladimir Oltean Jan. 21, 2021, 9:57 p.m. UTC | #1

On Thu, Jan 21, 2021 at 11:47:08PM +0200, Vladimir Oltean wrote:
> +Enables the full-offload feature. In this mode, taprio will pass the gate
> +control list to the NIC which will execute cyclically it in hardware.

Ugh, I meant "execute it cyclically" not "execute cyclically it".
David, could you fix this up or do I need to resend?

David Ahern Jan. 21, 2021, 11:10 p.m. UTC | #2

On 1/21/21 2:57 PM, Vladimir Oltean wrote:
> On Thu, Jan 21, 2021 at 11:47:08PM +0200, Vladimir Oltean wrote:
>> +Enables the full-offload feature. In this mode, taprio will pass the gate
>> +control list to the NIC which will execute cyclically it in hardware.
> 
> Ugh, I meant "execute it cyclically" not "execute cyclically it".
> David, could you fix this up or do I need to resend?
> 

I'll fix up

Vladimir Oltean Jan. 22, 2021, 12:37 a.m. UTC | #3

On Thu, Jan 21, 2021 at 04:10:06PM -0700, David Ahern wrote:
> On 1/21/21 2:57 PM, Vladimir Oltean wrote:
> > On Thu, Jan 21, 2021 at 11:47:08PM +0200, Vladimir Oltean wrote:
> >> +Enables the full-offload feature. In this mode, taprio will pass the gate
> >> +control list to the NIC which will execute cyclically it in hardware.
> > 
> > Ugh, I meant "execute it cyclically" not "execute cyclically it".
> > David, could you fix this up or do I need to resend?
> > 
> 
> I'll fix up

And I just noticed that ".BR etf(8)" needs to be on a line of its own. Sorry...

David Ahern Jan. 22, 2021, 1:11 a.m. UTC | #4

On 1/21/21 5:37 PM, Vladimir Oltean wrote:
> On Thu, Jan 21, 2021 at 04:10:06PM -0700, David Ahern wrote:
>> On 1/21/21 2:57 PM, Vladimir Oltean wrote:
>>> On Thu, Jan 21, 2021 at 11:47:08PM +0200, Vladimir Oltean wrote:
>>>> +Enables the full-offload feature. In this mode, taprio will pass the gate
>>>> +control list to the NIC which will execute cyclically it in hardware.
>>>
>>> Ugh, I meant "execute it cyclically" not "execute cyclically it".
>>> David, could you fix this up or do I need to resend?
>>>
>>
>> I'll fix up
> 
> And I just noticed that ".BR etf(8)" needs to be on a line of its own. Sorry...
> 

send a new version

Patch

diff --git a/man/man8/tc-taprio.8 b/man/man8/tc-taprio.8
index e1d19ba19089..ed3a2c06e0e9 100644
--- a/man/man8/tc-taprio.8
+++ b/man/man8/tc-taprio.8
@@ -92,7 +92,11 @@  in the schedule;
 clockid
 .br
 Specifies the clock to be used by qdisc's internal timer for measuring
-time and scheduling events.
+time and scheduling events. This argument must be omitted when using the
+full-offload feature (flags 0x2), since in that case, the clockid is
+implicitly /dev/ptpN (where N is given by
+.B ethtool -T eth0 | grep 'PTP Hardware Clock'
+), and therefore not necessarily synchronized with the system's CLOCK_TAI.
 
 .TP
 sched-entry
@@ -115,13 +119,26 @@  before moving to the next entry.
 .TP
 flags
 .br
-Specifies different modes for taprio. Currently, only txtime-assist is
-supported which can be enabled by setting it to 0x1. In this mode, taprio will
-set the transmit timestamp depending on the interval in which the packet needs
-to be transmitted. It will then utililize the
-.BR etf(8)
-qdisc to sort and transmit the packets at the right time. The second example
-can be used as a reference to configure this mode.
+This is a bit mask which specifies different modes for taprio.
+.RS
+.TP
+.I 0x1
+Enables the txtime-assist feature. In this mode, taprio will set the transmit
+timestamp depending on the interval in which the packet needs to be
+transmitted. It will then utililize the .BR etf(8) qdisc to sort and transmit
+the packets at the right time. The second example can be used as a reference to
+configure this mode.
+.TP
+.I 0x2
+Enables the full-offload feature. In this mode, taprio will pass the gate
+control list to the NIC which will execute cyclically it in hardware.
+When using full-offload, there is no need to specify the
+.B clockid
+argument.
+
+The txtime-assist and full-offload features are mutually exclusive, i.e.
+setting flags to 0x3 is invalid.
+.RE
 
 .TP
 txtime-delay
@@ -178,5 +195,30 @@  for more information about configuring the ETF qdisc.
               offload delta 200000 clockid CLOCK_TAI
 .EE
 
+The following is an example to enable the full-offload mode in taprio. The
+.B base-time
+is 200 ns and the
+.B cycle-time
+is implicitly calculated as the sum of all
+.B sched-entry
+durations (i.e. 20 us + 20 us + 60 us = 100 us). Because the
+.B base-time
+is when the administratively configured schedule will become operational, this
+in turn means that the hardware will start executing the schedule at a PTP time
+equal to the smallest integer multiple of 100 us, plus 200 ns, that is larger
+than the NIC's current PTP time.
+
+.EX
+# tc qdisc add dev eth0 parent root taprio \\
+              num_tc 8 \\
+              map 0 1 2 3 4 5 6 7 \\
+              queues 1@0 1@1 1@2 1@3 1@4 1@5 1@6 1@7 \\
+              base-time 200 \\
+              sched-entry S 80 20000 \\
+              sched-entry S a0 20000 \\
+              sched-entry S df 60000 \\
+              flags 0x2
+.EE
+
 .SH AUTHORS
 Vinicius Costa Gomes <[e-mail]>