| Message ID | 87zfy5g35h.fsf@meer.lwn.net (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | d0c3891db2d279b2f5ff8fd174e0b09e75dea039 |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net] ethtool: reformat kerneldoc for struct ethtool_link_settings | expand |
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!
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;
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(-)