[PATCH net-next] netlink: specs: netdev: clarify Tx queue stats

[PATCH net-next] netlink: specs: netdev: clarify Tx queue stats

[Jakub Kicinski]

AI has been complaining during mpnic review that we don't count
the offload stats on completion. This is expected. We don't want
to force drivers to fully re-interpret the skb on completion just
to get slightly more accurate values of informational offload
counters. It's fine to update those as we produce the send queue
descriptors.

This was always the intent: the tx-packets / tx-bytes docs
explicitly call out that the packets must have been successfully
sent, while the offload counters say nothing to this effect.
The checksum counter doc does use past tense which is probably
what threw reviewers off. Rephrase it.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
CC: donald.hunter@gmail.com
CC: sdf@fomichev.me
CC: razor@blackwall.org
CC: daniel@iogearbox.net
---
 Documentation/netlink/specs/netdev.yaml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/netlink/specs/netdev.yaml b/Documentation/netlink/specs/netdev.yaml
index 4303593e5003..0de7f93f0c4c 100644
--- a/Documentation/netlink/specs/netdev.yaml
+++ b/Documentation/netlink/specs/netdev.yaml
@@ -378,6 +378,11 @@ doc: >-
       up to the total number of events, will only be reported for currently
       active objects, and will likely report the number of events since last
       reconfiguration.
+      Basic Tx counters (`tx-packets` and `tx-bytes`) count only packets which
+      successfully reached the device, while offload-related counters
+      (e.g. `tx-needs-csum`, `tx-hw-gso-packets`) may be incremented at
+      submission time, and so may include packets which never reached
+      the device (e.g. dropped due to a queue flush or reconfiguration).
     attributes:
       -
         name: ifindex
@@ -510,9 +515,8 @@ doc: >-
       -
         name: tx-needs-csum
         doc: |
-          Number of packets that required the device to calculate the checksum.
-          This counter includes the number of GSO wire packets for which device
-          calculated the L4 checksum.
+          Number of packets which requested the device to fill in the checksum.
+          For GSO packets, this counter counts wire packets.
         type: uint
       -
         name: tx-hw-gso-packets
-- 
2.56.0