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

[Florian Fainelli <f.fainelli@gmail.com>]

On 6/7/2020 7:59 AM, Amit Cohen wrote:
> Add link extended state attributes.
> 
> Signed-off-by: Amit Cohen <amitc@mellanox.com>
> Reviewed-by: Petr Machata <petrm@mellanox.com>
> Reviewed-by: Jiri Pirko <jiri@mellanox.com>

If you need to resubmit, I would swap the order of patches #4 and #5
such that the documentation comes first.

[snip]

>  
> +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:

Not sure this comment is helping that much, how about documenting each
of the sub-states currently defined, even if this is just paraphrasing
their own name? Being able to quickly go to the documentation rather
than looking at the header is appreciable.

Thank you!

> +
> +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

Do you have examples? Would you consider a 4-pair copper cable for
Gigabit that has a damaged pair and would downshift somehow fall in that
category?
-- 
Florian