| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Date: Tue, 28 Apr 2020 00:01:41 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>,
"David S. Miller" <davem@...emloft.net>,
Jakub Kicinski <kuba@...nel.org>, netdev@...r.kernel.org
Subject: [PATCH 26/38] 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@...nel.org>
---
.../{gen_stats.txt => gen_stats.rst} | 98 ++++++++++---------
Documentation/networking/index.rst | 1 +
net/core/gen_stats.c | 2 +-
3 files changed, 56 insertions(+), 45 deletions(-)
rename Documentation/networking/{gen_stats.txt => gen_stats.rst} (60%)
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 179b18ce45ff..595a83b9a61b 100644
--- 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::
-Update statistics, in dequeue() methods only, (while owning qdisc->running)
-mystruct->tstats.packet++;
-mystruct->qstats.backlog += skb->pkt_len;
+ struct mystruct {
+ struct gnet_stats_basic bstats;
+ struct gnet_stats_queue qstats;
+ ...
+ };
+
+Update statistics, in dequeue() methods only, (while owning qdisc->running)::
+
+ 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@...g.ch>
-Jamal Hadi Salim <hadi@...erus.ca>
+- Thomas Graf <tgraf@...g.ch>
+- Jamal Hadi Salim <hadi@...erus.ca>
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 42e556509e22..33afbb67f3fa 100644
--- 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 1d653fbfcf52..e491b083b348 100644
--- a/net/core/gen_stats.c
+++ b/net/core/gen_stats.c
@@ -6,7 +6,7 @@
* Jamal Hadi Salim
* Alexey Kuznetsov, <kuznet@....inr.ac.ru>
*
- * See Documentation/networking/gen_stats.txt
+ * See Documentation/networking/gen_stats.rst
*/
#include <linux/types.h>
--
2.25.4
Powered by blists - more mailing lists