1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===============================================
4 Generic networking statistics for netlink users
5 ===============================================
6
7 Statistic counters are grouped into structs:
8
9 ==================== ===================== =====================
10 Struct TLV type Description
11 ==================== ===================== =====================
12 gnet_stats_basic TCA_STATS_BASIC Basic statistics
13 gnet_stats_rate_est TCA_STATS_RATE_EST Rate estimator
14 gnet_stats_queue TCA_STATS_QUEUE Queue statistics
15 none TCA_STATS_APP Application specific
16 ==================== ===================== =====================
17
18
19 Collecting:
20 -----------
21
22 Declare the statistic structs you need::
23
24 struct mystruct {
25 struct gnet_stats_basic bstats;
26 struct gnet_stats_queue qstats;
27 ...
28 };
29
30 Update statistics, in dequeue() methods only, (while owning qdisc->running)::
31
32 mystruct->tstats.packet++;
33 mystruct->qstats.backlog += skb->pkt_len;
34
35
36 Export to userspace (Dump):
37 ---------------------------
38
39 ::
40
41 my_dumping_routine(struct sk_buff *skb, ...)
42 {
43 struct gnet_dump dump;
44
45 if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
46 TCA_PAD) < 0)
47 goto rtattr_failure;
48
49 if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
50 gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
51 gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
52 goto rtattr_failure;
53
54 if (gnet_stats_finish_copy(&dump) < 0)
55 goto rtattr_failure;
56 ...
57 }
58
59 TCA_STATS/TCA_XSTATS backward compatibility:
60 --------------------------------------------
61
62 Prior users of struct tc_stats and xstats can maintain backward
63 compatibility by calling the compat wrappers to keep providing the
64 existing TLV types::
65
66 my_dumping_routine(struct sk_buff *skb, ...)
67 {
68 if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
69 TCA_XSTATS, &mystruct->lock, &dump,
70 TCA_PAD) < 0)
71 goto rtattr_failure;
72 ...
73 }
74
75 A struct tc_stats will be filled out during gnet_stats_copy_* calls
76 and appended to the skb. TCA_XSTATS is provided if gnet_stats_copy_app
77 was called.
78
79
80 Locking:
81 --------
82
83 Locks are taken before writing and released once all statistics have
84 been written. Locks are always released in case of an error. You
85 are responsible for making sure that the lock is initialized.
86
87
88 Rate Estimator:
89 ---------------
90
91 0) Prepare an estimator attribute. Most likely this would be in user
92 space. The value of this TLV should contain a tc_estimator structure.
93 As usual, such a TLV needs to be 32 bit aligned and therefore the
94 length needs to be appropriately set, etc. The estimator interval
95 and ewma log need to be converted to the appropriate values.
96 tc_estimator.c::tc_setup_estimator() is advisable to be used as the
97 conversion routine. It does a few clever things. It takes a time
98 interval in microsecs, a time constant also in microsecs and a struct
99 tc_estimator to be populated. The returned tc_estimator can be
100 transported to the kernel. Transfer such a structure in a TLV of type
101 TCA_RATE to your code in the kernel.
102
103 In the kernel when setting up:
104
105 1) make sure you have basic stats and rate stats setup first.
106 2) make sure you have initialized stats lock that is used to setup such
107 stats.
108 3) Now initialize a new estimator::
109
110 int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
111 mystats_lock, attr_with_tcestimator_struct);
112
113 if ret == 0
114 success
115 else
116 failed
117
118 From now on, every time you dump my_rate_est_stats it will contain
119 up-to-date info.
120
121 Once you are done, call gen_kill_estimator(my_basicstats,
122 my_rate_est_stats) Make sure that my_basicstats and my_rate_est_stats
123 are still valid (i.e still exist) at the time of making this call.
124
125
126 Authors:
127 --------
128 - Thomas Graf <tgraf@suug.ch>
129 - Jamal Hadi Salim <hadi@cyberus.ca>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.