[net] ethtool: reformat kerneldoc for struct ethtool_link_settings
Commit Message
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>
---
include/uapi/linux/ethtool.h | 27 +++++++++++++++------------
1 file changed, 15 insertions(+), 12 deletions(-)
Comments
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;
Hello:
This patch was applied to netdev/net-next.git (main)
by David S. Miller <davem@davemloft.net>:
On Tue, 19 Dec 2023 16:53:46 -0700 you 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'
>
> [...]
Here is the summary with links:
- [net] ethtool: reformat kerneldoc for struct ethtool_link_settings
https://git.kernel.org/netdev/net-next/c/d0c3891db2d2
You are awesome, thank you!
@@ -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;