Re: [PATCH net] ethtool: reformat kerneldoc for struct ethtool_link_settings

[Randy Dunlap <rdunlap@infradead.org>]

On 12/19/23 15:53, Jonathan Corbet wrote:
> The kernel doc comments for struct ethtool_link_settings includes
> documentation for three fields that were never present there, leading to
> these docs-build warnings:
> 
>   ./include/uapi/linux/ethtool.h:2207: warning: Excess struct member 'supported' description in 'ethtool_link_settings'
>   ./include/uapi/linux/ethtool.h:2207: warning: Excess struct member 'advertising' description in 'ethtool_link_settings'
>   ./include/uapi/linux/ethtool.h:2207: warning: Excess struct member 'lp_advertising' description in 'ethtool_link_settings'
> 
> Remove the entries to make the warnings go away.  There was some
> information there on how data in >link_mode_masks is formatted; move that
> to the body of the comment to preserve it.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  include/uapi/linux/ethtool.h | 27 +++++++++++++++------------
>  1 file changed, 15 insertions(+), 12 deletions(-)
> 
> diff --git a/include/uapi/linux/ethtool.h b/include/uapi/linux/ethtool.h
> index f7fba0dc87e5..50253287c321 100644
> --- a/include/uapi/linux/ethtool.h
> +++ b/include/uapi/linux/ethtool.h
> @@ -2128,18 +2128,6 @@ enum ethtool_reset_flags {
>   *	refused. For drivers: ignore this field (use kernel's
>   *	__ETHTOOL_LINK_MODE_MASK_NBITS instead), any change to it will
>   *	be overwritten by kernel.
> - * @supported: Bitmap with each bit meaning given by
> - *	%ethtool_link_mode_bit_indices for the link modes, physical
> - *	connectors and other link features for which the interface
> - *	supports autonegotiation or auto-detection.  Read-only.
> - * @advertising: Bitmap with each bit meaning given by
> - *	%ethtool_link_mode_bit_indices for the link modes, physical
> - *	connectors and other link features that are advertised through
> - *	autonegotiation or enabled for auto-detection.
> - * @lp_advertising: Bitmap with each bit meaning given by
> - *	%ethtool_link_mode_bit_indices for the link modes, and other
> - *	link features that the link partner advertised through
> - *	autonegotiation; 0 if unknown or not applicable.  Read-only.
>   * @transceiver: Used to distinguish different possible PHY types,
>   *	reported consistently by PHYLIB.  Read-only.
>   * @master_slave_cfg: Master/slave port mode.
> @@ -2181,6 +2169,21 @@ enum ethtool_reset_flags {
>   * %set_link_ksettings() should validate all fields other than @cmd
>   * and @link_mode_masks_nwords that are not described as read-only or
>   * deprecated, and must ignore all fields described as read-only.
> + *
> + * @link_mode_masks is divided into three bitfields, each of length
> + * @link_mode_masks_nwords:
> + * - supported: Bitmap with each bit meaning given by
> + *	%ethtool_link_mode_bit_indices for the link modes, physical
> + *	connectors and other link features for which the interface
> + *	supports autonegotiation or auto-detection.  Read-only.
> + * - advertising: Bitmap with each bit meaning given by
> + *	%ethtool_link_mode_bit_indices for the link modes, physical
> + *	connectors and other link features that are advertised through
> + *	autonegotiation or enabled for auto-detection.
> + * - lp_advertising: Bitmap with each bit meaning given by
> + *	%ethtool_link_mode_bit_indices for the link modes, and other
> + *	link features that the link partner advertised through
> + *	autonegotiation; 0 if unknown or not applicable.  Read-only.
>   */
>  struct ethtool_link_settings {
>  	__u32	cmd;

-- 
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html