include/net/cfg80211.h includes a number of kerneldoc entries for struct
members that do not exist, leading to these warnings:
./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
Remove and/or repair each entry to address the warnings and ensure a proper
docs build for the affected structures.
Signed-off-by: Jonathan Corbet <[email protected]>
---
include/net/cfg80211.h | 11 ++++-------
1 file changed, 4 insertions(+), 7 deletions(-)
diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index b137a33a1b68..81c46c8e2a68 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -3180,8 +3180,8 @@ struct cfg80211_ibss_params {
*
* @behaviour: requested BSS selection behaviour.
* @param: parameters for requestion behaviour.
- * @band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
- * @adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
+ * @param.band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
+ * @param.adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
*/
struct cfg80211_bss_selection {
enum nl80211_bss_select_attr behaviour;
@@ -6013,7 +6013,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
* wireless device if it has no netdev
* @u: union containing data specific to @iftype
* @connected: indicates if connected or not (STA mode)
- * @bssid: (private) Used by the internal configuration code
* @wext: (private) Used by the internal wireless extensions compat code
* @wext.ibss: (private) IBSS data part of wext handling
* @wext.connect: (private) connection handling data
@@ -6033,8 +6032,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
* @mgmt_registrations: list of registrations for management frames
* @mgmt_registrations_need_update: mgmt registrations were updated,
* need to propagate the update to the driver
- * @beacon_interval: beacon interval used on this device for transmitting
- * beacons, 0 when not valid
* @address: The address for this device, valid only if @netdev is %NULL
* @is_running: true if this is a non-netdev device that has been started, e.g.
* the P2P Device.
@@ -7270,8 +7267,6 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
/**
* struct cfg80211_rx_assoc_resp_data - association response data
- * @bss: the BSS that association was requested with, ownership of the pointer
- * moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
* @buf: (Re)Association Response frame (header + body)
* @len: length of the frame data
* @uapsd_queues: bitmap of queues configured for uapsd. Same format
@@ -7281,6 +7276,8 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
* @ap_mld_addr: AP MLD address (in case of MLO)
* @links: per-link information indexed by link ID, use links[0] for
* non-MLO connections
+ * @links.bss: the BSS that association was requested with, ownership of the
+ * pointer moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
* @links.status: Set this (along with a BSS pointer) for links that
* were rejected by the AP.
*/
--
2.43.0
On 12/19/2023 4:01 PM, Jonathan Corbet wrote:
> include/net/cfg80211.h includes a number of kerneldoc entries for struct
> members that do not exist, leading to these warnings:
>
> ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
> ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
> ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
> ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
> ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>
> Remove and/or repair each entry to address the warnings and ensure a proper
> docs build for the affected structures.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> include/net/cfg80211.h | 11 ++++-------
> 1 file changed, 4 insertions(+), 7 deletions(-)
>
> diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
> index b137a33a1b68..81c46c8e2a68 100644
> --- a/include/net/cfg80211.h
> +++ b/include/net/cfg80211.h
> @@ -3180,8 +3180,8 @@ struct cfg80211_ibss_params {
> *
> * @behaviour: requested BSS selection behaviour.
> * @param: parameters for requestion behaviour.
> - * @band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
> - * @adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
> + * @param.band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
> + * @param.adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
> */
> struct cfg80211_bss_selection {
> enum nl80211_bss_select_attr behaviour;
> @@ -6013,7 +6013,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
> * wireless device if it has no netdev
> * @u: union containing data specific to @iftype
> * @connected: indicates if connected or not (STA mode)
> - * @bssid: (private) Used by the internal configuration code
> * @wext: (private) Used by the internal wireless extensions compat code
> * @wext.ibss: (private) IBSS data part of wext handling
> * @wext.connect: (private) connection handling data
> @@ -6033,8 +6032,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
> * @mgmt_registrations: list of registrations for management frames
> * @mgmt_registrations_need_update: mgmt registrations were updated,
> * need to propagate the update to the driver
> - * @beacon_interval: beacon interval used on this device for transmitting
> - * beacons, 0 when not valid
> * @address: The address for this device, valid only if @netdev is %NULL
> * @is_running: true if this is a non-netdev device that has been started, e.g.
> * the P2P Device.
> @@ -7270,8 +7267,6 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
>
> /**
> * struct cfg80211_rx_assoc_resp_data - association response data
> - * @bss: the BSS that association was requested with, ownership of the pointer
> - * moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
> * @buf: (Re)Association Response frame (header + body)
> * @len: length of the frame data
> * @uapsd_queues: bitmap of queues configured for uapsd. Same format
> @@ -7281,6 +7276,8 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
> * @ap_mld_addr: AP MLD address (in case of MLO)
> * @links: per-link information indexed by link ID, use links[0] for
> * non-MLO connections
also missing the following?
* @links.addr: MLO per-link MAC address
> + * @links.bss: the BSS that association was requested with, ownership of the
> + * pointer moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
> * @links.status: Set this (along with a BSS pointer) for links that
> * were rejected by the AP.
> */
On 12/19/23 16:01, Jonathan Corbet wrote:
> include/net/cfg80211.h includes a number of kerneldoc entries for struct
> members that do not exist, leading to these warnings:
>
> ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
> ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
> ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
> ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
> ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>
> Remove and/or repair each entry to address the warnings and ensure a proper
> docs build for the affected structures.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
> ---
> include/net/cfg80211.h | 11 ++++-------
> 1 file changed, 4 insertions(+), 7 deletions(-)
>
> diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
> index b137a33a1b68..81c46c8e2a68 100644
> --- a/include/net/cfg80211.h
> +++ b/include/net/cfg80211.h
> @@ -3180,8 +3180,8 @@ struct cfg80211_ibss_params {
> *
> * @behaviour: requested BSS selection behaviour.
> * @param: parameters for requestion behaviour.
> - * @band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
> - * @adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
> + * @param.band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
> + * @param.adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
> */
> struct cfg80211_bss_selection {
> enum nl80211_bss_select_attr behaviour;
> @@ -6013,7 +6013,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
> * wireless device if it has no netdev
> * @u: union containing data specific to @iftype
> * @connected: indicates if connected or not (STA mode)
> - * @bssid: (private) Used by the internal configuration code
> * @wext: (private) Used by the internal wireless extensions compat code
> * @wext.ibss: (private) IBSS data part of wext handling
> * @wext.connect: (private) connection handling data
> @@ -6033,8 +6032,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
> * @mgmt_registrations: list of registrations for management frames
> * @mgmt_registrations_need_update: mgmt registrations were updated,
> * need to propagate the update to the driver
> - * @beacon_interval: beacon interval used on this device for transmitting
> - * beacons, 0 when not valid
> * @address: The address for this device, valid only if @netdev is %NULL
> * @is_running: true if this is a non-netdev device that has been started, e.g.
> * the P2P Device.
> @@ -7270,8 +7267,6 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
>
> /**
> * struct cfg80211_rx_assoc_resp_data - association response data
> - * @bss: the BSS that association was requested with, ownership of the pointer
> - * moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
> * @buf: (Re)Association Response frame (header + body)
> * @len: length of the frame data
> * @uapsd_queues: bitmap of queues configured for uapsd. Same format
> @@ -7281,6 +7276,8 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
> * @ap_mld_addr: AP MLD address (in case of MLO)
> * @links: per-link information indexed by link ID, use links[0] for
> * non-MLO connections
> + * @links.bss: the BSS that association was requested with, ownership of the
> + * pointer moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
> * @links.status: Set this (along with a BSS pointer) for links that
> * were rejected by the AP.
> */
--
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html
On 12/19/23 17:00, Jeff Johnson wrote:
> On 12/19/2023 4:01 PM, Jonathan Corbet wrote:
>> include/net/cfg80211.h includes a number of kerneldoc entries for struct
>> members that do not exist, leading to these warnings:
>>
>> ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
>> ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
>> ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
>> ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
>> ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>>
>> Remove and/or repair each entry to address the warnings and ensure a proper
>> docs build for the affected structures.
>>
>> Signed-off-by: Jonathan Corbet <[email protected]>
>> ---
>> include/net/cfg80211.h | 11 ++++-------
>> 1 file changed, 4 insertions(+), 7 deletions(-)
>>
>> diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
>> index b137a33a1b68..81c46c8e2a68 100644
>> --- a/include/net/cfg80211.h
>> +++ b/include/net/cfg80211.h
>> @@ -3180,8 +3180,8 @@ struct cfg80211_ibss_params {
>> *
>> * @behaviour: requested BSS selection behaviour.
>> * @param: parameters for requestion behaviour.
>> - * @band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
>> - * @adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
>> + * @param.band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
>> + * @param.adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
>> */
>> struct cfg80211_bss_selection {
>> enum nl80211_bss_select_attr behaviour;
>> @@ -6013,7 +6013,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
>> * wireless device if it has no netdev
>> * @u: union containing data specific to @iftype
>> * @connected: indicates if connected or not (STA mode)
>> - * @bssid: (private) Used by the internal configuration code
>> * @wext: (private) Used by the internal wireless extensions compat code
>> * @wext.ibss: (private) IBSS data part of wext handling
>> * @wext.connect: (private) connection handling data
>> @@ -6033,8 +6032,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
>> * @mgmt_registrations: list of registrations for management frames
>> * @mgmt_registrations_need_update: mgmt registrations were updated,
>> * need to propagate the update to the driver
>> - * @beacon_interval: beacon interval used on this device for transmitting
>> - * beacons, 0 when not valid
>> * @address: The address for this device, valid only if @netdev is %NULL
>> * @is_running: true if this is a non-netdev device that has been started, e.g.
>> * the P2P Device.
>> @@ -7270,8 +7267,6 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
>>
>> /**
>> * struct cfg80211_rx_assoc_resp_data - association response data
>> - * @bss: the BSS that association was requested with, ownership of the pointer
>> - * moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
>> * @buf: (Re)Association Response frame (header + body)
>> * @len: length of the frame data
>> * @uapsd_queues: bitmap of queues configured for uapsd. Same format
>> @@ -7281,6 +7276,8 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
>> * @ap_mld_addr: AP MLD address (in case of MLO)
>> * @links: per-link information indexed by link ID, use links[0] for
>> * non-MLO connections
>
> also missing the following?
> * @links.addr: MLO per-link MAC address
Yes, that should also be fixed at some point.
What Jon is trying to do here is address a boatload of new kernel-doc warnings of the
"Excess struct member" variety.
>
>> + * @links.bss: the BSS that association was requested with, ownership of the
>> + * pointer moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
>> * @links.status: Set this (along with a BSS pointer) for links that
>> * were rejected by the AP.
>> */
>
>
Thanks.
--
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html
Jonathan Corbet <[email protected]> writes:
> include/net/cfg80211.h includes a number of kerneldoc entries for struct
> members that do not exist, leading to these warnings:
>
> ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
> ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
> ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
> ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
> ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>
> Remove and/or repair each entry to address the warnings and ensure a proper
> docs build for the affected structures.
>
> Signed-off-by: Jonathan Corbet <[email protected]>
I try to periodically check for kerneldoc warnings in wireless trees but
I have never seen these. Am I missing something or did you do something
special (enable new warnings etc.)?
--
https://patchwork.kernel.org/project/linux-wireless/list/
https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches
On 12/19/23 22:35, Kalle Valo wrote:
> Jonathan Corbet <[email protected]> writes:
>
>> include/net/cfg80211.h includes a number of kerneldoc entries for struct
>> members that do not exist, leading to these warnings:
>>
>> ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
>> ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
>> ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
>> ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
>> ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>>
>> Remove and/or repair each entry to address the warnings and ensure a proper
>> docs build for the affected structures.
>>
>> Signed-off-by: Jonathan Corbet <[email protected]>
>
> I try to periodically check for kerneldoc warnings in wireless trees but
> I have never seen these. Am I missing something or did you do something
> special (enable new warnings etc.)?
There are new patches from both Kees Cook and me to report Excess kernel-doc
descriptions, so now there are a bunch of kernel-doc warnings that we are working
to fix quickly. :(
--
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html
Randy Dunlap <[email protected]> writes:
> On 12/19/23 22:35, Kalle Valo wrote:
>> Jonathan Corbet <[email protected]> writes:
>>
>>> include/net/cfg80211.h includes a number of kerneldoc entries for struct
>>> members that do not exist, leading to these warnings:
>>>
>>> ./include/net/cfg80211.h:3192: warning: Excess struct member
>>> 'band_pref' description in 'cfg80211_bss_selection'
>>> ./include/net/cfg80211.h:3192: warning: Excess struct member
>>> 'adjust' description in 'cfg80211_bss_selection'
>>> ./include/net/cfg80211.h:6181: warning: Excess struct member
>>> 'bssid' description in 'wireless_dev'
>>> ./include/net/cfg80211.h:6181: warning: Excess struct member
>>> 'beacon_interval' description in 'wireless_dev'
>>> ./include/net/cfg80211.h:7299: warning: Excess struct member
>>> 'bss' description in 'cfg80211_rx_assoc_resp_data'
>>>
>>> Remove and/or repair each entry to address the warnings and ensure a proper
>>> docs build for the affected structures.
>>>
>>> Signed-off-by: Jonathan Corbet <[email protected]>
>>
>> I try to periodically check for kerneldoc warnings in wireless trees but
>> I have never seen these. Am I missing something or did you do something
>> special (enable new warnings etc.)?
>
> There are new patches from both Kees Cook and me to report Excess kernel-doc
> descriptions, so now there are a bunch of kernel-doc warnings that we are working
> to fix quickly. :(
Got it, thanks. Good to know that I wasn't missing anything.
--
https://patchwork.kernel.org/project/linux-wireless/list/
https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches