0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============================================
0004 Generic networking statistics for netlink users
0005 ===============================================
0006
0007 Statistic counters are grouped into structs:
0008
0009 ==================== ===================== =====================
0010 Struct TLV type Description
0011 ==================== ===================== =====================
0012 gnet_stats_basic TCA_STATS_BASIC Basic statistics
0013 gnet_stats_rate_est TCA_STATS_RATE_EST Rate estimator
0014 gnet_stats_queue TCA_STATS_QUEUE Queue statistics
0015 none TCA_STATS_APP Application specific
0016 ==================== ===================== =====================
0017
0018
0019 Collecting:
0020 -----------
0021
0022 Declare the statistic structs you need::
0023
0024 struct mystruct {
0025 struct gnet_stats_basic bstats;
0026 struct gnet_stats_queue qstats;
0027 ...
0028 };
0029
0030 Update statistics, in dequeue() methods only, (while owning qdisc->running)::
0031
0032 mystruct->tstats.packet++;
0033 mystruct->qstats.backlog += skb->pkt_len;
0034
0035
0036 Export to userspace (Dump):
0037 ---------------------------
0038
0039 ::
0040
0041 my_dumping_routine(struct sk_buff *skb, ...)
0042 {
0043 struct gnet_dump dump;
0044
0045 if (gnet_stats_start_copy(skb, TCA_STATS2, &mystruct->lock, &dump,
0046 TCA_PAD) < 0)
0047 goto rtattr_failure;
0048
0049 if (gnet_stats_copy_basic(&dump, &mystruct->bstats) < 0 ||
0050 gnet_stats_copy_queue(&dump, &mystruct->qstats) < 0 ||
0051 gnet_stats_copy_app(&dump, &xstats, sizeof(xstats)) < 0)
0052 goto rtattr_failure;
0053
0054 if (gnet_stats_finish_copy(&dump) < 0)
0055 goto rtattr_failure;
0056 ...
0057 }
0058
0059 TCA_STATS/TCA_XSTATS backward compatibility:
0060 --------------------------------------------
0061
0062 Prior users of struct tc_stats and xstats can maintain backward
0063 compatibility by calling the compat wrappers to keep providing the
0064 existing TLV types::
0065
0066 my_dumping_routine(struct sk_buff *skb, ...)
0067 {
0068 if (gnet_stats_start_copy_compat(skb, TCA_STATS2, TCA_STATS,
0069 TCA_XSTATS, &mystruct->lock, &dump,
0070 TCA_PAD) < 0)
0071 goto rtattr_failure;
0072 ...
0073 }
0074
0075 A struct tc_stats will be filled out during gnet_stats_copy_* calls
0076 and appended to the skb. TCA_XSTATS is provided if gnet_stats_copy_app
0077 was called.
0078
0079
0080 Locking:
0081 --------
0082
0083 Locks are taken before writing and released once all statistics have
0084 been written. Locks are always released in case of an error. You
0085 are responsible for making sure that the lock is initialized.
0086
0087
0088 Rate Estimator:
0089 ---------------
0090
0091 0) Prepare an estimator attribute. Most likely this would be in user
0092 space. The value of this TLV should contain a tc_estimator structure.
0093 As usual, such a TLV needs to be 32 bit aligned and therefore the
0094 length needs to be appropriately set, etc. The estimator interval
0095 and ewma log need to be converted to the appropriate values.
0096 tc_estimator.c::tc_setup_estimator() is advisable to be used as the
0097 conversion routine. It does a few clever things. It takes a time
0098 interval in microsecs, a time constant also in microsecs and a struct
0099 tc_estimator to be populated. The returned tc_estimator can be
0100 transported to the kernel. Transfer such a structure in a TLV of type
0101 TCA_RATE to your code in the kernel.
0102
0103 In the kernel when setting up:
0104
0105 1) make sure you have basic stats and rate stats setup first.
0106 2) make sure you have initialized stats lock that is used to setup such
0107 stats.
0108 3) Now initialize a new estimator::
0109
0110 int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
0111 mystats_lock, attr_with_tcestimator_struct);
0112
0113 if ret == 0
0114 success
0115 else
0116 failed
0117
0118 From now on, every time you dump my_rate_est_stats it will contain
0119 up-to-date info.
0120
0121 Once you are done, call gen_kill_estimator(my_basicstats,
0122 my_rate_est_stats) Make sure that my_basicstats and my_rate_est_stats
0123 are still valid (i.e still exist) at the time of making this call.
0124
0125
0126 Authors:
0127 --------
0128 - Thomas Graf <tgraf@suug.ch>
0129 - Jamal Hadi Salim <hadi@cyberus.ca>
