The Linux Kernel Logo
  • Development process
  • Submitting patches
  • Code of conduct
  • Maintainer handbook
  • All development-process docs
  • Core API
  • Driver APIs
  • Subsystems
    • Core subsystems
    • Human interfaces
    • Networking interfaces
      • Networking
        • AF_XDP
        • Bare UDP Tunnelling Module Documentation
        • batman-adv
        • SocketCAN - Controller Area Network
        • The UCAN Protocol
        • Hardware Device Drivers
        • Networking Diagnostics
        • Distributed Switch Architecture
        • Linux Devlink Documentation
        • CAIF
        • Netlink interface for ethtool
        • IEEE 802.15.4 Developer’s Guide
        • ISO 15765-2 (ISO-TP)
        • J1939 Documentation
        • Linux Networking and Network Devices APIs
        • MSG_ZEROCOPY
        • FAILOVER
        • Net DIM - Generic Network Dynamic Interrupt Moderation
        • NET_FAILOVER
        • Page Pool API
        • PHY Abstraction Layer
        • phylink
        • IP-Aliasing
        • Ethernet Bridging
        • SNMP counter
        • Checksum Offloads
        • Segmentation Offloads
        • Scaling in the Linux Networking Stack
        • Kernel TLS
        • Kernel TLS offload
        • In-Kernel TLS Handshake
        • Linux NFC subsystem
        • Netdev private dataroom for 6lowpan interfaces
        • 6pack Protocol
        • ARCnet Hardware
        • ARCnet
        • ATM
        • AX.25
        • Linux Ethernet Bonding Driver HOWTO
        • cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
        • DCCP protocol
        • DCTCP (DataCenter TCP)
        • Device Memory TCP
        • DNS Resolver Module
        • Softnet Driver Issues
        • EQL Driver: Serial IP Load Balancing HOWTO
        • LC-trie implementation notes
        • Linux Socket Filtering aka Berkeley Packet Filter (BPF)
        • Generic HDLC layer
        • Generic Netlink
        • Netlink Family Specifications
        • Generic networking statistics for netlink users
          • Collecting:
          • Export to userspace (Dump):
          • TCA_STATS/TCA_XSTATS backward compatibility:
          • Locking:
          • Rate Estimator:
          • Authors:
        • The Linux kernel GTP tunneling module
        • Identifier Locator Addressing (ILA)
        • IOAM6 Sysfs variables
        • io_uring zero copy Rx
        • IP dynamic address hack-port v0.03
        • IPsec
        • IP Sysctl
        • IPv6
        • IPVLAN Driver HOWTO
        • IPvs-sysctl
        • Kernel Connection Multiplexor
        • L2TP
        • The Linux LAPB Module Interface
        • How to use packet injection with mac80211
        • Management Component Transport Protocol (MCTP)
        • MPLS Sysfs variables
        • Multipath TCP (MPTCP)
        • MPTCP Sysfs variables
        • HOWTO for multiqueue network device support
        • Multi-PF Netdev
        • NAPI
        • Common Networking Struct Cachelines
        • Netconsole
        • Netdev features mess and how to get out from it alive
        • Network Devices, the Kernel, and You!
        • Netfilter Sysfs variables
        • NETIF Msg Level
        • Netmem Support for Network Drivers
        • Resilient Next-hop Groups
        • Netfilter Conntrack Sysfs variables
        • Netfilter’s flowtable infrastructure
        • OPEN Alliance 10BASE-T1x MAC-PHY Serial Interface (TC6) Framework Support
        • Open vSwitch datapath developer documentation
        • Operational States
        • Packet MMAP
        • Linux Phonet protocol family
        • PHY link topology
        • HOWTO for the linux packet generator
        • PLIP: The Parallel Line Internet Protocol Device
        • PPP Generic Driver and Channel Interface
        • The proc/net/tcp and proc/net/tcp6 variables
        • Power Sourcing Equipment (PSE) Documentation
        • How to use radiotap headers
        • RDS
        • Linux wireless regulatory documentation
        • Network Function Representors
        • RxRPC Network Protocol
        • SOCKET OPTIONS
        • SECURITY
        • EXAMPLE CLIENT USAGE
        • Linux Kernel SCTP
        • LSM/SeLinux secid
        • Seg6 Sysfs variables
        • struct sk_buff
        • SMC Sysctl
        • NIC SR-IOV APIs
        • Interface statistics
        • Stream Parser (strparser)
        • Ethernet switch device driver model (switchdev)
        • Sysfs tagging
        • TC Actions - Environmental Rules
        • TC queue based filtering
        • TCP Authentication Option Linux implementation (RFC5925)
        • Thin-streams and TCP
        • Team
        • Timestamping
        • Linux Kernel TIPC
        • Transparent proxy support
        • Universal TUN/TAP device driver
        • The UDP-Lite protocol (RFC 3828)
        • Virtual Routing and Forwarding (VRF)
        • Virtual eXtensible Local Area Networking documentation
        • Linux X.25 Project
        • X.25 Device Driver Interface
        • XFRM device - offloading the IPsec computations
        • XFRM proc - /proc/net/xfrm_* files
        • XFRM
        • XFRM Syscall
        • XDP RX Metadata
        • AF_XDP TX Metadata
      • NetLabel
      • InfiniBand
      • ISDN
      • MHI
    • Storage interfaces
    • Other subsystems
  • Locking
  • Licensing rules
  • Writing documentation
  • Development tools
  • Testing guide
  • Hacking guide
  • Tracing
  • Fault injection
  • Livepatching
  • Rust
  • Administration
  • Build system
  • Reporting issues
  • Userspace tools
  • Userspace API
  • Firmware
  • Firmware and Devicetree
  • CPU architectures
  • Unsorted documentation
  • Translations
The Linux Kernel
  • Kernel subsystem documentation
  • Networking
  • Generic networking statistics for netlink users
  • View page source

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;
        ...
};

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;

        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:

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 was called.

Locking:¶

Locks are taken before writing and released once all statistics have been written. Locks are always released in case of an error. You are responsible for making sure that the lock is initialized.

Rate Estimator:¶

  1. Prepare an estimator attribute. Most likely this would be in user space. The value of this TLV should contain a tc_estimator structure. As usual, such a TLV needs to be 32 bit aligned and therefore the length needs to be appropriately set, etc. The estimator interval and ewma log need to be converted to the appropriate values. tc_estimator.c::tc_setup_estimator() is advisable to be used as the conversion routine. It does a few clever things. It takes a time interval in microsecs, a time constant also in microsecs and a struct tc_estimator to be populated. The returned tc_estimator can be transported to the kernel. Transfer such a structure in a TLV of type 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:

    int ret = gen_new_estimator(my_basicstats,my_rate_est_stats,
        mystats_lock, attr_with_tcestimator_struct);
    
    if ret == 0
        success
    else
        failed
    

From now on, every time you dump my_rate_est_stats it will contain up-to-date info.

Once you are done, call gen_kill_estimator(my_basicstats, my_rate_est_stats) Make sure that my_basicstats and my_rate_est_stats 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>

Previous Next

© Copyright The kernel development community.

Built with Sphinx using a theme provided by Read the Docs.