docs: networking: convert gen_stats.txt to ReST

- add SPDX header;
- mark code blocks and literals as such;
- mark tables as such;
- mark lists as such;
- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>

diff --git a/Documentation/networking/gen_stats.txt b/Documentation/networking/gen_stats.rst
similarity index 60%
rename from Documentation/networking/gen_stats.txt
rename to Documentation/networking/gen_stats.rst
index 179b18c..595a83b 100644 (file)
--- a/Documentation/networking/gen_stats.txt
+++ b/Documentation/networking/gen_stats.rst
@@ -1,67 +1,76 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================================
 Generic networking statistics for netlink users
-======================================================================
+===============================================
 
 Statistic counters are grouped into structs:
 
+==================== ===================== =====================
 Struct               TLV type              Description
-----------------------------------------------------------------------
+==================== ===================== =====================
 gnet_stats_basic     TCA_STATS_BASIC       Basic statistics
 gnet_stats_rate_est  TCA_STATS_RATE_EST    Rate estimator
 gnet_stats_queue     TCA_STATS_QUEUE       Queue statistics
 none                 TCA_STATS_APP         Application specific
+==================== ===================== =====================
 
 
 Collecting:
 -----------
 
-Declare the statistic structs you need:
-struct mystruct {
-       struct gnet_stats_basic bstats;
-       struct gnet_stats_queue qstats;
-       ...
-};
+Declare the statistic structs you need::
+
+       struct mystruct {
+               struct gnet_stats_basic bstats;
+               struct gnet_stats_queue qstats;
+               ...
+       };
+
+Update statistics, in dequeue() methods only, (while owning qdisc->running)::
 
-Update statistics, in dequeue() methods only, (while owning qdisc->running)
-mystruct->tstats.packet++;
-mystruct->qstats.backlog += skb->pkt_len;
+       mystruct->tstats.packet++;
+       mystruct->qstats.backlog += skb->pkt_len;
 
 
 Export to userspace (Dump):
 ---------------------------
 
-my_dumping_routine(struct sk_buff *skb, ...)
-{
-       struct gnet_dump dump;
+::
 
-       if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
-                                 TCA_PAD) < 0)
-               goto rtattr_failure;
+    my_dumping_routine(struct sk_buff *skb, ...)
+    {
+           struct gnet_dump dump;
 
-       if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
-           gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
-               gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
-               goto rtattr_failure;
+           if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
+                                   TCA_PAD) < 0)
+                   goto rtattr_failure;
 
-       if (gnet_stats_finish_copy(&dump) < 0)
-               goto rtattr_failure;
-       ...
-}
+           if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
+               gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
+                   gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
+                   goto rtattr_failure;
+
+           if (gnet_stats_finish_copy(&dump) < 0)
+                   goto rtattr_failure;
+           ...
+    }
 
 TCA_STATS/TCA_XSTATS backward compatibility:
 --------------------------------------------
 
 Prior users of struct tc_stats and xstats can maintain backward
 compatibility by calling the compat wrappers to keep providing the
-existing TLV types.
+existing TLV types::
 
-my_dumping_routine(struct sk_buff *skb, ...)
-{
-    if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
-                                    TCA_XSTATS, &mystruct->lock, &dump,
-                                    TCA_PAD) < 0)
-               goto rtattr_failure;
-       ...
-}
+    my_dumping_routine(struct sk_buff *skb, ...)
+    {
+       if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
+                                       TCA_XSTATS, &mystruct->lock, &dump,
+                                       TCA_PAD) < 0)
+                   goto rtattr_failure;
+           ...
+    }
 
 A struct tc_stats will be filled out during gnet_stats_copy_* calls
 and appended to the skb. TCA_XSTATS is provided if gnet_stats_copy_app
@@ -77,7 +86,7 @@ are responsible for making sure that the lock is initialized.
 
 
 Rate Estimator:
---------------
+---------------
 
 0) Prepare an estimator attribute. Most likely this would be in user
    space. The value of this TLV should contain a tc_estimator structure.
@@ -92,18 +101,19 @@ Rate Estimator:
    TCA_RATE to your code in the kernel.
 
 In the kernel when setting up:
+
 1) make sure you have basic stats and rate stats setup first.
 2) make sure you have initialized stats lock that is used to setup such
    stats.
-3) Now initialize a new estimator:
+3) Now initialize a new estimator::
 
-   int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
-       mystats_lock, attr_with_tcestimator_struct);
+    int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
+       mystats_lock, attr_with_tcestimator_struct);
 
-   if ret == 0
-       success
-   else
-       failed
+    if ret == 0
+       success
+    else
+       failed
 
 From now on, every time you dump my_rate_est_stats it will contain
 up-to-date info.
@@ -115,5 +125,5 @@ are still valid (i.e still exist) at the time of making this call.
 
 Authors:
 --------
-Thomas Graf <tgraf@suug.ch>
-Jamal Hadi Salim <hadi@cyberus.ca>
+- Thomas Graf <tgraf@suug.ch>
+- Jamal Hadi Salim <hadi@cyberus.ca>

diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 42e5565..33afbb6 100644 (file)
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -61,6 +61,7 @@ Contents:
    framerelay
    generic-hdlc
    generic_netlink
+   gen_stats
 
 .. only::  subproject and html
 

diff --git a/net/core/gen_stats.c b/net/core/gen_stats.c
index 1d653fb..e491b08 100644 (file)
--- a/net/core/gen_stats.c
+++ b/net/core/gen_stats.c
@@ -6,7 +6,7 @@
  *           Jamal Hadi Salim
  *           Alexey Kuznetsov, <kuznet@ms2.inr.ac.ru>
  *
- * See Documentation/networking/gen_stats.txt
+ * See Documentation/networking/gen_stats.rst
  */
 
 #include <linux/types.h>