From: Jakub Kicinski <kuba@kernel.org>
To: netdev@vger.kernel.org
Cc: davem@davemloft.net, andrew@lunn.ch, mkubecek@suse.cz,
idosch@nvidia.com, Jakub Kicinski <kuba@kernel.org>
Subject: [RFC net-next 2/6] docs: ethtool: document standard statistics
Date: Wed, 14 Apr 2021 13:23:21 -0700 [thread overview]
Message-ID: <20210414202325.2225774-3-kuba@kernel.org> (raw)
In-Reply-To: <20210414202325.2225774-1-kuba@kernel.org>
Add documentation for ETHTOOL_MSG_STATS_GET.
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
Documentation/networking/ethtool-netlink.rst | 74 ++++++++++++++++++++
1 file changed, 74 insertions(+)
diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index f8219e2f489e..086a80eb17be 100644
--- a/Documentation/networking/ethtool-netlink.rst
+++ b/Documentation/networking/ethtool-netlink.rst
@@ -210,6 +210,7 @@ All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix
``ETHTOOL_MSG_TUNNEL_INFO_GET`` get tunnel offload info
``ETHTOOL_MSG_FEC_GET`` get FEC settings
``ETHTOOL_MSG_FEC_SET`` set FEC settings
+ ``ETHTOOL_MSG_STATS_GET`` get standard statistics
===================================== ================================
Kernel to userspace:
@@ -246,6 +247,7 @@ All constants identifying message types use ``ETHTOOL_CMD_`` prefix and suffix
``ETHTOOL_MSG_TUNNEL_INFO_GET_REPLY`` tunnel offload info
``ETHTOOL_MSG_FEC_GET_REPLY`` FEC settings
``ETHTOOL_MSG_FEC_NTF`` FEC settings
+ ``ETHTOOL_MSG_STATS_GET_REPLY`` standard statistics
===================================== =================================
``GET`` requests are sent by userspace applications to retrieve device
@@ -1391,6 +1393,78 @@ accessible.
``ETHTOOL_A_MODULE_EEPROM_DATA`` has an attribute length equal to the amount of
bytes driver actually read.
+STATS_GET
+=========
+
+Get standard statistics for the interface. Note that this is not
+a re-implementation of ``ETHTOOL_GSTATS`` which exposed driver-defined
+stats.
+
+Request contents:
+
+ ======================================= ====== ==========================
+ ``ETHTOOL_A_STATS_HEADER`` nested request header
+ ``ETHTOOL_A_STATS_GROUPS`` bitset requested groups of stats
+ ======================================= ====== ==========================
+
+Kernel response contents:
+
+ +---------------------------------+--------+----------------------------------+
+ | ``ETHTOOL_A_STATS_HEADER`` | nested | reply header |
+ +---------------------------------+--------+----------------------------------+
+ | ``ETHTOOL_A_STATS_GRP`` | nested | one or more groups of statistics |
+ +-+-------------------------------+--------+----------------------------------+
+ | | ``ETHTOOL_A_STATS_GRP_ID`` | u32 | group ID - ``ETHTOOL_STATS_*`` |
+ +-+-------------------------------+--------+----------------------------------+
+ | | ``ETHTOOL_A_STATS_GRP_SS_ID`` | u32 | string set ID for names |
+ +-+-------------------------------+--------+----------------------------------+
+ | | ``ETHTOOL_A_STATS_*`` | u64 | actual statistics |
+ +-+-------------------------------+--------+----------------------------------+
+
+Users specify which groups of statistics they are requesting via
+the ``ETHTOOL_A_STATS_GROUPS`` bitset. Currently defined values are:
+
+ ====================== ======== ===============================================
+ ETHTOOL_STATS_ETH_MAC eth-mac Basic IEEE 802.3 MAC statistics (30.3.1.1.*)
+ ETHTOOL_STATS_ETH_PHY eth-phy Basic IEEE 802.3 PHY statistics (30.3.2.1.*)
+ ETHTOOL_STATS_ETH_CTRL eth-ctrl Basic IEEE 802.3 MAC Ctrl statistics (30.3.3.*)
+ ETHTOOL_STATS_RMON rmon RMON (RFC 2819) statistics
+ ====================== ======== ===============================================
+
+Each group should have a corresponding ``ETHTOOL_A_STATS_GRP`` in the reply.
+``ETHTOOL_A_STATS_GRP_ID`` identifies which group's statistics nest contains.
+``ETHTOOL_A_STATS_GRP_SS_ID`` identifies the string set ID for the names of
+the statistics in the group, if available.
+
+Statistics are added directly to the ``ETHTOOL_A_STATS_GRP`` nest. Each group
+has its own interpretation of attribute IDs above
+``ETHTOOL_A_STATS_GRP_FIRST_ATTR``. Attribute IDs correspond to strings from
+the string set identified by ``ETHTOOL_A_STATS_GRP_SS_ID``. Complex statistics
+(such as RMON histogram entries) are also listed directly in
+``ETHTOOL_A_STATS_GRP`` and do not have a string defined in the string set.
+
+RMON "histogram" counters count number of packets within given size range.
+Because RFC does not specify the ranges beyond the standard 1518 MTU devices
+differ in definition of buckets. For this reason the definition of packet ranges
+is left to each driver.
+
+ ================================= ====== ===================================
+ ETHTOOL_A_STATS_RMON_HIST nested contains the attributes below
+ ETHTOOL_A_STATS_RMON_HIST_BKT_LOW u32 low bound of the packet size bucket
+ ETHTOOL_A_STATS_RMON_HIST_BKT_HI u32 high bound of the bucket
+ ETHTOOL_A_STATS_RMON_HIST_VAL u64 packet counter
+ ETHTOOL_A_STATS_RMON_HIST_TX nested same as HIST but counting Tx pkts
+ ================================= ====== ===================================
+
+Low and high bounds are inclusive, for example:
+
+ ============================= ==== ====
+ RFC statistic low high
+ ============================= ==== ====
+ etherStatsPkts64Octets 0 64
+ etherStatsPkts512to1023Octets 512 1023
+ ============================= ==== ====
+
Request translation
===================
--
2.30.2
next prev parent reply other threads:[~2021-04-14 20:24 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-14 20:23 [RFC net-next 0/6] ethtool: add uAPI for reading standard stats Jakub Kicinski
2021-04-14 20:23 ` [RFC net-next 1/6] docs: networking: extend the statistics documentation Jakub Kicinski
2021-04-14 20:23 ` Jakub Kicinski [this message]
2021-04-14 20:23 ` [RFC net-next 3/6] ethtool: add a new command for reading standard stats Jakub Kicinski
2021-04-14 20:23 ` [RFC net-next 4/6] ethtool: add interface to read standard MAC stats Jakub Kicinski
2021-04-15 6:12 ` Saeed Mahameed
2021-04-15 15:38 ` Jakub Kicinski
2021-04-15 22:46 ` Saeed Mahameed
2021-04-15 23:05 ` Jakub Kicinski
2021-04-15 23:52 ` Saeed Mahameed
2021-04-14 20:23 ` [RFC net-next 5/6] ethtool: add interface to read standard MAC Ctrl stats Jakub Kicinski
2021-04-14 20:23 ` [RFC net-next 6/6] ethtool: add interface to read RMON stats Jakub Kicinski
2021-04-15 5:51 ` [RFC net-next 0/6] ethtool: add uAPI for reading standard stats Saeed Mahameed
2021-04-15 15:45 ` Jakub Kicinski
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210414202325.2225774-3-kuba@kernel.org \
--to=kuba@kernel.org \
--cc=andrew@lunn.ch \
--cc=davem@davemloft.net \
--cc=idosch@nvidia.com \
--cc=mkubecek@suse.cz \
--cc=netdev@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).