[RFC PATCH net-next 05/10] Documentation: networking: ethtool-netlink: Add link extended state

From: Amit Cohen
Date: Sun Jun 07 2020 - 11:00:47 EST


Add link extended state attributes.

Signed-off-by: Amit Cohen <amitc@xxxxxxxxxxxx>
Reviewed-by: Petr Machata <petrm@xxxxxxxxxxxx>
Reviewed-by: Jiri Pirko <jiri@xxxxxxxxxxxx>
---
Documentation/networking/ethtool-netlink.rst | 56 ++++++++++++++++++--
1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index 7e651ea33eab..4e4570ebbc4d 100644
--- a/Documentation/networking/ethtool-netlink.rst
+++ b/Documentation/networking/ethtool-netlink.rst
@@ -441,10 +441,11 @@ supports.
LINKSTATE_GET
=============

-Requests link state information. At the moment, only link up/down flag (as
-provided by ``ETHTOOL_GLINK`` ioctl command) is provided but some future
-extensions are planned (e.g. link down reason). This request does not have any
-attributes.
+Requests link state information. Link up/down flag (as provided by
+``ETHTOOL_GLINK`` ioctl command) is provided. Optionally, extended state might
+be provided as well. In general, extended state describes reasons for why a port
+is down, or why it operates in some non-obvious mode. This request does not have
+any attributes.

Request contents:

@@ -459,16 +460,63 @@ Kernel response contents:
``ETHTOOL_A_LINKSTATE_LINK`` bool link state (up/down)
``ETHTOOL_A_LINKSTATE_SQI`` u32 Current Signal Quality Index
``ETHTOOL_A_LINKSTATE_SQI_MAX`` u32 Max support SQI value
+ ``ETHTOOL_A_LINKSTATE_EXT_STATE`` u8 link extended state
+ ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` u8 link extended substate
==================================== ====== ============================

For most NIC drivers, the value of ``ETHTOOL_A_LINKSTATE_LINK`` returns
carrier flag provided by ``netif_carrier_ok()`` but there are drivers which
define their own handler.

+``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE`` are
+optional values. ethtool core can provide either both
+``ETHTOOL_A_LINKSTATE_EXT_STATE`` and ``ETHTOOL_A_LINKSTATE_EXT_SUBSTATE``,
+or only ``ETHTOOL_A_LINKSTATE_EXT_STATE``, or none of them.
+
``LINKSTATE_GET`` allows dump requests (kernel returns reply messages for all
devices supporting the request).


+Link extended states:
+
+ ============================ =============================================
+ ``Autoneg failure`` Failure during auto negotiation mechanism
+
+ ``Link training failure`` Failure during link training
+
+ ``Link logical mismatch`` Logical mismatch in physical coding sublayer
+ or forward error correction sublayer
+
+ ``Bad signal integrity`` Signal integrity issues
+
+ ``No cable`` No cable connected
+
+ ``Cable issue`` Failure is related to cable,
+ e.g., unsupported cable
+
+ ``EEPROM issue`` Failure is related to EEPROM, e.g., failure
+ during reading or parsing the data
+
+ ``Calibration failure`` Failure during calibration algorithm
+
+ ``Power budget exceeded`` The hardware is not able to provide the
+ power required from cable or module
+
+ ``Overheat`` The module is overheated
+ ============================ =============================================
+
+Many of the substates are obvious, or terms that someone working in the
+particular area will be familiar with. The following table summarizes some
+that are not:
+
+Link extended substates:
+
+ ============================ =============================================
+ ``Unsupported rate`` The system attempted to operate the cable at
+ a rate that is not formally supported, which
+ led to signal integrity issues
+ ============================ =============================================
+
DEBUG_GET
=========

--
2.20.1