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