Fix kernel-doc warnings at linux-next

As we're currently discussing about making kernel-doc issues fatal when CONFIG_WERROR is enable, let's fix all 60 kernel-doc warnings inside linux-next:

arch/x86/include/uapi/asm/sgx.h:19: warning: Enum value 'SGX_PAGE_MEASURE' not described in enum 'sgx_page_flags' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rdi' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rsi' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rdx' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rsp' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'r8' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'r9' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:124: warning: Function parameter or member 'reserved' not described in 'sgx_enclave_run' drivers/devfreq/devfreq.c:707: warning: Function parameter or member 'val' not described in 'qos_min_notifier_call' drivers/devfreq/devfreq.c:707: warning: Function parameter or member 'ptr' not described in 'qos_min_notifier_call' drivers/devfreq/devfreq.c:717: warning: Function parameter or member 'val' not described in 'qos_max_notifier_call' drivers/devfreq/devfreq.c:717: warning: Function parameter or member 'ptr' not described in 'qos_max_notifier_call' drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:5095: warning: expecting prototype for amdgpu_device_gpu_recover_imp(). Prototype was for amdgpu_device_gpu_recover() instead drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'dmub_outbox_params' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'num_of_edps' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'disable_hpd_irq' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'dmub_aux_transfer_done' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'delayed_hpd_wq' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/include/amd_shared.h:224: warning: Enum value 'PP_GFX_DCS_MASK' not described in enum 'PP_FEATURE_MASK' drivers/gpu/drm/scheduler/sched_main.c:999: warning: Function parameter or member 'dev' not described in 'drm_sched_init' drivers/usb/dwc3/core.h:1328: warning: Function parameter or member 'async_callbacks' not described in 'dwc3' drivers/usb/dwc3/gadget.c:675: warning: Function parameter or member 'mult' not described in 'dwc3_gadget_calc_tx_fifo_size'
fs/attr.c:36: warning: Function parameter or member 'ia_vfsuid' not described in 'chown_ok'
fs/attr.c:36: warning: Excess function parameter 'uid' description in 'chown_ok'
fs/attr.c:63: warning: Function parameter or member 'ia_vfsgid' not described in 'chgrp_ok'
fs/attr.c:63: warning: Excess function parameter 'gid' description in 'chgrp_ok'
fs/namei.c:649: warning: Function parameter or member 'mnt' not described in 'path_connected'
fs/namei.c:649: warning: Function parameter or member 'dentry' not described in 'path_connected'
fs/namei.c:1089: warning: Function parameter or member 'inode' not described in 'may_follow_link'
include/drm/gpu_scheduler.h:463: warning: Function parameter or member 'dev' not described in 'drm_gpu_scheduler' include/linux/dcache.h:309: warning: expecting prototype for dget, dget_dlock(). Prototype was for dget_dlock() instead include/linux/fscache.h:270: warning: Function parameter or member 'cookie' not described in 'fscache_use_cookie' include/linux/fscache.h:270: warning: Excess function parameter 'object' description in 'fscache_use_cookie'
include/linux/fscache.h:287: warning: Function parameter or member 'cookie' not described in 'fscache_unuse_cookie' include/linux/fscache.h:287: warning: Excess function parameter 'object' description in 'fscache_unuse_cookie'
include/linux/genalloc.h:54: warning: Function parameter or member 'start_addr' not described in 'genpool_algo_t' include/linux/kfence.h:221: warning: Function parameter or member 'slab' not described in '__kfence_obj_info' include/linux/regulator/driver.h:434: warning: Function parameter or member 'n_ramp_values' not described in 'regulator_desc' include/linux/textsearch.h:51: warning: Function parameter or member 'list' not described in 'ts_ops' include/linux/usb/typec_altmode.h:132: warning: Function parameter or member 'altmode' not described in 'typec_altmode_get_orientation' include/net/cfg80211.h:391: warning: Function parameter or member 'bw' not described in 'ieee80211_eht_mcs_nss_supp' include/net/cfg80211.h:437: warning: Function parameter or member 'eht_cap' not described in 'ieee80211_sband_iftype_data' include/net/cfg80211.h:507: warning: Function parameter or member 's1g' not described in 'ieee80211_sta_s1g_cap' include/net/cfg80211.h:1390: warning: Function parameter or member 'counter_offset_beacon' not described in 'cfg80211_color_change_settings' include/net/cfg80211.h:1390: warning: Function parameter or member 'counter_offset_presp' not described in 'cfg80211_color_change_settings' include/net/cfg80211.h:1430: warning: Enum value 'STATION_PARAM_APPLY_STA_TXPOWER' not described in enum 'station_parameters_apply_mask' include/net/cfg80211.h:2195: warning: Function parameter or member 'dot11MeshConnectedToAuthServer' not described in 'mesh_config' include/net/cfg80211.h:2341: warning: Function parameter or member 'short_ssid' not described in 'cfg80211_scan_6ghz_params' include/net/cfg80211.h:3328: warning: Function parameter or member 'kck_len' not described in 'cfg80211_gtk_rekey_data' include/net/cfg80211.h:3698: warning: Function parameter or member 'ftm' not described in 'cfg80211_pmsr_result' include/net/cfg80211.h:3828: warning: Function parameter or member 'global_mcast_stypes' not described in 'mgmt_frame_regs' include/net/cfg80211.h:4977: warning: Function parameter or member 'ftm' not described in 'cfg80211_pmsr_capabilities' include/net/cfg80211.h:5742: warning: Function parameter or member 'u' not described in 'wireless_dev'
include/net/cfg80211.h:5742: warning: Function parameter or member 'links' not described in 'wireless_dev'
include/net/cfg80211.h:5742: warning: Function parameter or member 'valid_links' not described in 'wireless_dev' include/net/cfg80211.h:6076: warning: Function parameter or member 'is_amsdu' not described in 'ieee80211_data_to_8023_exthdr' include/net/cfg80211.h:6949: warning: Function parameter or member 'sig_dbm' not described in 'cfg80211_notify_new_peer_candidate' include/net/mac80211.h:6250: warning: Function parameter or member 'vif' not described in 'ieee80211_channel_switch_disconnect' mm/memory.c:1729: warning: Function parameter or member 'mt' not described in 'unmap_vmas'
net/mac80211/sta_info.h:569: warning: Function parameter or member 'cur_max_bandwidth' not described in 'link_sta_info'

Mauro Carvalho Chehab (22):
net: cfg80211: fix kernel-doc warnings all over the file
net: mac80211: add a missing comma at kernel-doc markup
net: mac80211: sta_info: fix a missing kernel-doc struct element x86/sgx: fix kernel-doc markups
fscache: fix kernel-doc documentation
fs: attr: update vfs uid/gid parameters at kernel-doc
fs: namei: address some kernel-doc issues
devfreq: shut up kernel-doc warnings
drm: amdgpu: amdgpu_dm: fix kernel-doc markups
drm: amdgpu: amdgpu_device.c: fix a kernel-doc markup
drm: amd: amd_shared.h: Add missing doc for PP_GFX_DCS_MASK
drm: gpu_scheduler: fix a kernel-doc warning
drm: scheduler: add a missing kernel-doc parameter
kfence: fix a kernel-doc parameter
mm: document maple tree pointer at unmap_vmas() at memory.c
genalloc: add a description for start_addr parameter
textsearch: document list inside struct ts_ops
regulator: fix a kernel-doc warning
dcache: fix a kernel-doc warning
usb: typec_altmode: add a missing "@" at a kernel-doc parameter
usb: dwc3: document async_callbacks field
usb: dwc3: gadget: fix a kernel-doc warning

 arch/x86/include/uapi/asm/sgx.h               | 10 +++++--
 drivers/devfreq/devfreq.c                     |  4 +++
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c    |  2 +-
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |  7 +++++
 drivers/gpu/drm/amd/include/amd_shared.h      |  1 +
 drivers/gpu/drm/scheduler/sched_main.c        |  1 +
 drivers/usb/dwc3/core.h                       |  2 ++
 drivers/usb/dwc3/gadget.c                     |  1 +
 fs/attr.c                                     |  4 +--
 fs/namei.c                                    |  3 ++
 include/drm/gpu_scheduler.h                   |  1 +
 include/linux/dcache.h                        |  2 +-
 include/linux/fscache.h                       |  4 +--
 include/linux/genalloc.h                      |  1 +
 include/linux/kfence.h                        |  1 +
 include/linux/regulator/driver.h              |  1 +
 include/linux/textsearch.h                    |  1 +
 include/linux/usb/typec_altmode.h             |  2 +-
 include/net/cfg80211.h                        | 28 ++++++++++++++-----
 include/net/mac80211.h                        |  2 +-
 mm/memory.c                                   |  2 ++
 net/mac80211/sta_info.h                       |  2 ++
 22 files changed, 65 insertions(+), 17 deletions(-)

2.36.1

There are currently 17 kernel-doc warnings on this file:
include/net/cfg80211.h:391: warning: Function parameter or member 'bw' not described in 'ieee80211_eht_mcs_nss_supp' include/net/cfg80211.h:437: warning: Function parameter or member 'eht_cap' not described in 'ieee80211_sband_iftype_data' include/net/cfg80211.h:507: warning: Function parameter or member 's1g' not described in 'ieee80211_sta_s1g_cap' include/net/cfg80211.h:1390: warning: Function parameter or member 'counter_offset_beacon' not described in 'cfg80211_color_change_settings' include/net/cfg80211.h:1390: warning: Function parameter or member 'counter_offset_presp' not described in 'cfg80211_color_change_settings' include/net/cfg80211.h:1430: warning: Enum value 'STATION_PARAM_APPLY_STA_TXPOWER' not described in enum 'station_parameters_apply_mask' include/net/cfg80211.h:2195: warning: Function parameter or member 'dot11MeshConnectedToAuthServer' not described in 'mesh_config' include/net/cfg80211.h:2341: warning: Function parameter or member 'short_ssid' not described in 'cfg80211_scan_6ghz_params' include/net/cfg80211.h:3328: warning: Function parameter or member 'kck_len' not described in 'cfg80211_gtk_rekey_data' include/net/cfg80211.h:3698: warning: Function parameter or member 'ftm' not described in 'cfg80211_pmsr_result' include/net/cfg80211.h:3828: warning: Function parameter or member 'global_mcast_stypes' not described in 'mgmt_frame_regs' include/net/cfg80211.h:4977: warning: Function parameter or member 'ftm' not described in 'cfg80211_pmsr_capabilities' include/net/cfg80211.h:5742: warning: Function parameter or member 'u' not described in 'wireless_dev' include/net/cfg80211.h:5742: warning: Function parameter or member 'links' not described in 'wireless_dev' include/net/cfg80211.h:5742: warning: Function parameter or member 'valid_links' not described in 'wireless_dev' include/net/cfg80211.h:6076: warning: Function parameter or member 'is_amsdu' not described in 'ieee80211_data_to_8023_exthdr' include/net/cfg80211.h:6949: warning: Function parameter or member 'sig_dbm' not described in 'cfg80211_notify_new_peer_candidate'

Address them, in order to build a better documentation from this header.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/net/cfg80211.h | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

index 996782c44838..c7e641071eff 100644
@@ -374,6 +374,7 @@ struct ieee80211_sta_he_cap {
  * and NSS Set field"
  *
  * @only_20mhz: MCS/NSS support for 20 MHz-only STA.
+ * @bw: MCS/NSS support for 80, 160 and 320 MHz
  * @bw._80: MCS/NSS support for BW <= 80 MHz
  * @bw._160: MCS/NSS support for BW = 160 MHz
  * @bw._320: MCS/NSS support for BW = 320 MHz

@@ -420,6 +421,7 @@ struct ieee80211_sta_eht_cap {
  * @he_cap: holds the HE capabilities
  * @he_6ghz_capa: HE 6 GHz capabilities, must be filled in for a
  *	6 GHz band channel (and 0 may be valid value).
+ * @eht_cap: STA's EHT capabilities
  * @vendor_elems: vendor element(s) to advertise
  * @vendor_elems.data: vendor element(s) data
  * @vendor_elems.len: vendor element(s) length

@@ -495,7 +497,7 @@ struct ieee80211_edmg {
  * This structure describes most essential parameters needed
  * to describe 802.11ah S1G capabilities for a STA.
  *
- * @s1g_supported: is STA an S1G STA
+ * @s1g: is STA an S1G STA
  * @cap: S1G capabilities information
  * @nss_mcs: Supported NSS MCS set
  */

@@ -1373,8 +1375,8 @@ struct cfg80211_csa_settings {
  * Used for bss color change
  *
  * @beacon_color_change: beacon data while performing the color countdown
- * @counter_offsets_beacon: offsets of the counters within the beacon (tail)
- * @counter_offsets_presp: offsets of the counters within the probe response
+ * @counter_offset_beacon: offsets of the counters within the beacon (tail)
+ * @counter_offset_presp: offsets of the counters within the probe response
  * @beacon_next: beacon data to be used after the color change
  * @count: number of beacons until the color change
  * @color: the color used after the change

@@ -1417,6 +1419,7 @@ struct iface_combination_params {
  * @STATION_PARAM_APPLY_UAPSD: apply new uAPSD parameters (uapsd_queues, max_sp)
  * @STATION_PARAM_APPLY_CAPABILITY: apply new capability
  * @STATION_PARAM_APPLY_PLINK_STATE: apply new plink state
+ * @STATION_PARAM_APPLY_STA_TXPOWER: apply tx power for STA
  *
  * Not all station parameters have in-band "no change" signalling,
  * for those that don't these flags will are used.

@@ -2149,6 +2152,9 @@ struct bss_parameters {
  * @plink_timeout: If no tx activity is seen from a STA we've established
  *	peering with for longer than this time (in seconds), then remove it
  *	from the STA's list of peers.  Default is 30 minutes.
+ * @dot11MeshConnectedToAuthServer: if set to true then this mesh STA
+ *	will advertise that it is connected to a authentication server
+ *	in the mesh formation field.
  * @dot11MeshConnectedToMeshGate: if set to true, advertise that this STA is
  *      connected to a mesh gate in mesh formation info.  If false, the
  *      value in mesh formation is determined by the presence of root paths

@@ -2321,12 +2327,12 @@ struct cfg80211_scan_info {
 /**
  * struct cfg80211_scan_6ghz_params - relevant for 6 GHz only
  *
- * @short_bssid: short ssid to scan for
+ * @short_ssid: short ssid to scan for
  * @bssid: bssid to scan for
  * @channel_idx: idx of the channel in the channel array in the scan request
  *	 which the above info relvant to
  * @unsolicited_probe: the AP transmits unsolicited probe response every 20 TU
- * @short_ssid_valid: short_ssid is valid and can be used
+ * @short_ssid_valid: @short_ssid is valid and can be used
  * @psc_no_listen: when set, and the channel is a PSC channel, no need to wait
  *       20 TUs before starting to send probe requests.
  */

@@ -3317,7 +3323,7 @@ struct cfg80211_wowlan_wakeup {
  * @kck: key confirmation key (@kck_len bytes)
  * @replay_ctr: replay counter (NL80211_REPLAY_CTR_LEN bytes)
  * @kek_len: length of kek
- * @kck_len length of kck
+ * @kck_len: length of kck
  * @akm: akm (oui, id)
  */
 struct cfg80211_gtk_rekey_data {

@@ -3679,6 +3685,7 @@ struct cfg80211_pmsr_ftm_result {
  * @type: type of the measurement reported, note that we only support reporting
  *	one type at a time, but you can report multiple results separately and
  *	they're all aggregated for userspace.
+ * @ftm: FTM result
  */
 struct cfg80211_pmsr_result {
 	u64 host_time, ap_tsf;

@@ -3817,7 +3824,7 @@ struct cfg80211_update_owe_info {
  *	for the entire device
  * @interface_stypes: bitmap of management frame subtypes registered
  *	for the given interface
- * @global_mcast_rx: mcast RX is needed globally for these subtypes
+ * @global_mcast_stypes: mcast RX is needed globally for these subtypes
  * @interface_mcast_stypes: mcast RX is needed on this interface
  *	for these subtypes
  */

@@ -4940,6 +4947,7 @@ struct wiphy_iftype_ext_capab {
  * @max_peers: maximum number of peers in a single measurement
  * @report_ap_tsf: can report assoc AP's TSF for radio resource measurement
  * @randomize_mac_addr: can randomize MAC address for measurement
+ * @ftm: FTM measurement data
  * @ftm.supported: FTM measurement is supported
  * @ftm.asap: ASAP-mode is supported
  * @ftm.non_asap: non-ASAP-mode is supported

@@ -5563,6 +5571,7 @@ static inline void wiphy_unlock(struct wiphy *wiphy)
  * @netdev: (private) Used to reference back to the netdev, may be %NULL
  * @identifier: (private) Identifier used in nl80211 to identify this
  *	wireless device if it has no netdev
+ * @u: union containing data specific to @iftype
  * @connected_addr: (private) BSSID or AP MLD address if connected
  * @connected: indicates if connected or not (STA mode)
  * @current_bss: (private) Used by the internal configuration code

@@ -5624,6 +5633,9 @@ static inline void wiphy_unlock(struct wiphy *wiphy)
  * @pmsr_free_wk: (private) peer measurements cleanup work
  * @unprot_beacon_reported: (private) timestamp of last
  *	unprotected beacon report
+ * @links: array of %IEEE80211_MLD_MAX_NUM_LINKS elements containing @addr
+ *	@ap and @client for each link
+ * @valid_links: bitmap describing what elements of @links are valid
  */
 struct wireless_dev {
 	struct wiphy *wiphy;

@@ -6068,6 +6080,7 @@ unsigned int ieee80211_get_mesh_hdrlen(struct ieee80211s_hdr *meshhdr);
  * @addr: the device MAC address
  * @iftype: the virtual interface type
  * @data_offset: offset of payload after the 802.11 header
+ * @is_amsdu: true if the 802.11 header is A-MSDU
  * Return: 0 on success. Non-zero on error.
  */
 int ieee80211_data_to_8023_exthdr(struct sk_buff *skb, struct ethhdr *ehdr,

@@ -6937,6 +6950,7 @@ void cfg80211_ibss_joined(struct net_device *dev, const u8 *bssid,
  * @macaddr: the MAC address of the new candidate
  * @ie: information elements advertised by the peer candidate
  * @ie_len: length of the information elements buffer
+ * @sig_dbm: signal level in dBm
  * @gfp: allocation flags
  *
  * This function notifies cfg80211 that the mesh peer candidate has been

2.36.1

The lack of the comma makes it to not parse the function parameter:
include/net/mac80211.h:6250: warning: Function parameter or member 'vif' not described in 'ieee80211_channel_switch_disconnect'

Fix it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/net/mac80211.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 27f24ac0426d..c0557142343f 100644
@@ -6238,7 +6238,7 @@ void ieee80211_chswitch_done(struct ieee80211_vif *vif, bool success);
 
 /**
  * ieee80211_channel_switch_disconnect - disconnect due to channel switch error
- * @vif &struct ieee80211_vif pointer from the add_interface callback.
+ * @vif: &struct ieee80211_vif pointer from the add_interface callback.
  * @block_tx: if %true, do not send deauth frame.
  *
  * Instruct mac80211 to disconnect due to a channel switch error. The channel

2.36.1

nit: s/comma/colon/

struct link_sta_info has now a cur_max_bandwidth data:

net/mac80211/sta_info.h:569: warning: Function parameter or member 'cur_max_bandwidth' not described in 'link_sta_info'

Copy the meaning from struct sta_info, documenting it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 net/mac80211/sta_info.h | 2 ++
 1 file changed, 2 insertions(+)

index 218430790660..4e0b969891de 100644
@@ -517,6 +517,8 @@ struct ieee80211_fragment_cache {
  * @status_stats.last_ack_signal: last ACK signal
  * @status_stats.ack_signal_filled: last ACK signal validity
  * @status_stats.avg_ack_signal: average ACK signal
+ * @cur_max_bandwidth: maximum bandwidth to use for TX to the station,
+ *	taken from HT/VHT capabilities or VHT operating mode notification
  * @pub: public (driver visible) link STA data
  * TODO Move other link params from sta_info as required for MLD operation
  */

2.36.1

There are a couple typos there, violating kernel-doc syntax.

Also, on a function typedef, the register snapshots aren't documented.

This should fix those warnings:

arch/x86/include/uapi/asm/sgx.h:19: warning: Enum value 'SGX_PAGE_MEASURE' not described in enum 'sgx_page_flags' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rdi' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rsi' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rdx' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'rsp' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'r8' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:97: warning: Function parameter or member 'r9' not described in 'sgx_enclave_user_handler_t' arch/x86/include/uapi/asm/sgx.h:124: warning: Function parameter or member 'reserved' not described in 'sgx_enclave_run'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 arch/x86/include/uapi/asm/sgx.h | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

index f4b81587e90b..e0e6a3ebc941 100644
@@ -10,7 +10,7 @@
 
 /**
  * enum sgx_page_flags - page control flags
- * %SGX_PAGE_MEASURE:	Measure the page contents with a sequence of
+ * @SGX_PAGE_MEASURE:	Measure the page contents with a sequence of
  *			ENCLS[EEXTEND] operations.
  */
 enum sgx_page_flags {

@@ -81,6 +81,12 @@ struct sgx_enclave_run;
 /**
  * typedef sgx_enclave_user_handler_t - Exit handler function accepted by
  *					__vdso_sgx_enter_enclave()
+ * @rdi:	snapshot of DI register at enclave exit
+ * @rsi:	snapshot of SI register at enclave exit
+ * @rdx:	snapshot of DX register at enclave exit
+ * @rsp:	snapshot of SP register at enclave exit
+ * @r8:		snapshot of R8 register at enclave exit
+ * @r9:		snapshot of R9 register at enclave exit
  * @run:	The run instance given by the caller
  *
  * The register parameters contain the snapshot of their values at enclave

@@ -104,7 +110,7 @@ typedef int (*sgx_enclave_user_handler_t)(long rdi, long rsi, long rdx,
  * @exception_addr:		The address that triggered the exception
  * @user_handler:		User provided callback run on exception
  * @user_data:			Data passed to the user handler
- * @reserved			Reserved for future extensions
+ * @reserved:			Reserved for future extensions
  *
  * If @user_handler is provided, the handler will be invoked on all return paths
  * of the normal flow.  The user handler may transfer control, e.g. via a

2.36.1

I guess this also needs:

Other than that,

BR, Jarkko

The 'DX register' really is different than RDX.

These should all have the full register names, like:

snapshot of RSP register at enclave exit

With that fixed:

The prototype of two functions use "cookie" for the object parameter.

Update kernel-doc tags accordingly, fixing those warnings:

include/linux/fscache.h:270: warning: Function parameter or member 'cookie' not described in 'fscache_use_cookie' include/linux/fscache.h:270: warning: Excess function parameter 'object' description in 'fscache_use_cookie' include/linux/fscache.h:287: warning: Function parameter or member 'cookie' not described in 'fscache_unuse_cookie' include/linux/fscache.h:287: warning: Excess function parameter 'object' description in 'fscache_unuse_cookie'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/fscache.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 2f82ea31d4c1..e13184c4b198 100644
@@ -257,7 +257,7 @@ struct fscache_cookie *fscache_acquire_cookie(struct fscache_volume *volume,
 
 /**
  * fscache_use_cookie - Request usage of cookie attached to an object
- * @object: Object description
+ * @cookie: Object description
  * @will_modify: If cache is expected to be modified locally
  *
  * Request usage of the cookie attached to an object.  The caller should tell

@@ -273,7 +273,7 @@ static inline void fscache_use_cookie(struct fscache_cookie *cookie,
 
 /**
  * fscache_unuse_cookie - Cease usage of cookie attached to an object
- * @object: Object description
+ * @cookie: Object description
  * @aux_data: Updated auxiliary data (or NULL)
  * @object_size: Revised size of the object (or NULL)
  *

2.36.1

The vfs uid/gid parameters have a different name at the function prototype causing kernel-doc warnings. Update them for the parameters to match, fixing those warnings:

fs/attr.c:36: warning: Function parameter or member 'ia_vfsuid' not described in 'chown_ok' fs/attr.c:36: warning: Excess function parameter 'uid' description in 'chown_ok' fs/attr.c:63: warning: Function parameter or member 'ia_vfsgid' not described in 'chgrp_ok' fs/attr.c:63: warning: Excess function parameter 'gid' description in 'chgrp_ok'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 fs/attr.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 1ba7ddef537f..b5b8835ddf15 100644
@@ -22,7 +22,7 @@
  * chown_ok - verify permissions to chown inode
  * @mnt_userns:	user namespace of the mount @inode was found from
  * @inode:	inode to check permissions on
- * @uid:	uid to chown @inode to
+ * @ia_vfsuid:	uid to chown @inode to
  *
  * If the inode has been found through an idmapped mount the user namespace of
  * the vfsmount must be passed through @mnt_userns. This function will then

@@ -49,7 +49,7 @@ static bool chown_ok(struct user_namespace *mnt_userns,
  * chgrp_ok - verify permissions to chgrp inode
  * @mnt_userns:	user namespace of the mount @inode was found from
  * @inode:	inode to check permissions on
- * @gid:	gid to chown @inode to
+ * @ia_vfsgid:	gid to chown @inode to
  *
  * If the inode has been found through an idmapped mount the user namespace of
  * the vfsmount must be passed through @mnt_userns. This function will then

2.36.1

This is already fixed in my tree and in -next as
81a1807d80dd26cdf8a357cf55f556ade90c7fda

So you can drop this.

Thanks!
Christian

There are couple of symbols missing documentation:

fs/namei.c:649: warning: Function parameter or member 'mnt' not described in 'path_connected' fs/namei.c:649: warning: Function parameter or member 'dentry' not described in 'path_connected' fs/namei.c:1089: warning: Function parameter or member 'inode' not described in 'may_follow_link'

Document them.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 fs/namei.c | 3 +++
 1 file changed, 3 insertions(+)

index 1f28d3f463c3..a8079d6250bc 100644
@@ -640,6 +640,8 @@ static bool nd_alloc_stack(struct nameidata *nd)
 
 /**
  * path_connected - Verify that a dentry is below mnt.mnt_root
+ * @mnt: pointer to vfs mount
+ * @dentry:  pointer to dentry to verify
  *
  * Rename can sometimes move a file or directory outside of a bind
  * mount, path_connected allows those cases to be detected.

@@ -1072,6 +1074,7 @@ fs_initcall(init_fs_namei_sysctls);
 /**
  * may_follow_link - Check symlink following for unsafe situations
  * @nd: nameidata pathwalk data
+ * @inode: inode to check
  *
  * In the case of the sysctl_protected_symlinks sysctl being enabled,
  * CAP_DAC_OVERRIDE needs to be specifically ignored if the symlink is

2.36.1

There are 4 warnings there:
drivers/devfreq/devfreq.c:707: warning: Function parameter or member 'val' not described in 'qos_min_notifier_call' drivers/devfreq/devfreq.c:707: warning: Function parameter or member 'ptr' not described in 'qos_min_notifier_call' drivers/devfreq/devfreq.c:717: warning: Function parameter or member 'val' not described in 'qos_max_notifier_call' drivers/devfreq/devfreq.c:717: warning: Function parameter or member 'ptr' not described in 'qos_max_notifier_call'

It turns that neither val nor ptr are actually used on those function, so document as such.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/devfreq/devfreq.c | 4 ++++
 1 file changed, 4 insertions(+)

index 01474daf4548..3020855d8400 100644
@@ -700,6 +700,8 @@ static int qos_notifier_call(struct devfreq *devfreq)
 /**
  * qos_min_notifier_call() - Callback for QoS min_freq changes.
  * @nb:		Should be devfreq->nb_min
+ * @val:	not used
+ * @ptr:	not used
  */
 static int qos_min_notifier_call(struct notifier_block *nb,
 					 unsigned long val, void *ptr)

@@ -710,6 +712,8 @@ static int qos_min_notifier_call(struct notifier_block *nb,
 /**
  * qos_max_notifier_call() - Callback for QoS max_freq changes.
  * @nb:		Should be devfreq->nb_max
+ * @val:	not used
+ * @ptr:	not used
  */
 static int qos_max_notifier_call(struct notifier_block *nb,
 					 unsigned long val, void *ptr)

2.36.1

There are 4 undocumented fields at struct amdgpu_display_manager.

Add documentation for them, fixing those warnings:

drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'dmub_outbox_params' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'num_of_edps' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'disable_hpd_irq' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'dmub_aux_transfer_done' not described in 'amdgpu_display_manager' drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h:544: warning: Function parameter or member 'delayed_hpd_wq' not described in 'amdgpu_display_manager'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 7 +++++++
 1 file changed, 7 insertions(+)

index 547fc1547977..73755b304299 100644
@@ -242,6 +242,13 @@ struct hpd_rx_irq_offload_work {
  * @force_timing_sync: set via debugfs. When set, indicates that all connected
  *		       displays will be forced to synchronize.
  * @dmcub_trace_event_en: enable dmcub trace events
+ * @dmub_outbox_params: DMUB Outbox parameters
+ * @num_of_edps: number of backlight eDPs
+ * @disable_hpd_irq: disables all HPD and HPD RX interrupt handling in the
+ *		     driver when true
+ * @dmub_aux_transfer_done: struct completion used to indicate when DMUB
+ * 			    transfers are done
+ * @delayed_hpd_wq: work queue used to delay DMUB HPD work
  */
 struct amdgpu_display_manager {
 

2.36.1

Applied. Thanks!

The function was renamed without renaming also kernel-doc markup:
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:5095: warning: expecting prototype for amdgpu_device_gpu_recover_imp(). Prototype was for amdgpu_device_gpu_recover() instead

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 9d6418bb963e..6d74767591e7 100644
@@ -5079,7 +5079,7 @@ static inline void amdggpu_device_stop_pedning_resets(struct amdgpu_device *adev
 
 
 /**
- * amdgpu_device_gpu_recover_imp - reset the asic and recover scheduler
+ * amdgpu_device_gpu_recover - reset the asic and recover scheduler
  *
  * @adev: amdgpu_device pointer
  * @job: which job trigger hang

2.36.1

I actually sent out the same patch a few days ago, however, the code has since changed with Andrey's recent GPU reset series and the patch is no longer applicable.

Thanks,

Alex

This symbol is missing documentation:

drivers/gpu/drm/amd/include/amd_shared.h:224: warning: Enum value 'PP_GFX_DCS_MASK' not described in enum 'PP_FEATURE_MASK'

Document it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/gpu/drm/amd/include/amd_shared.h | 1 +
 1 file changed, 1 insertion(+)

index bcdf7453a403..2e02a6fc1717 100644
@@ -193,6 +193,7 @@ enum amd_powergating_state {
  * @PP_ACG_MASK: Adaptive clock generator.
  * @PP_STUTTER_MODE: Stutter mode.
  * @PP_AVFS_MASK: Adaptive voltage and frequency scaling.
+ * @PP_GFX_DCS_MASK: GFX Async DCS.
  *
  * To override these settings on boot, append amdgpu.ppfeaturemask=<mask> to
  * the kernel's command line parameters. This is usually done through a system's

2.36.1

Applied. Thanks!

The dev field was not documented:

include/drm/gpu_scheduler.h:463: warning: Function parameter or member 'dev' not described in 'drm_gpu_scheduler'

Document it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/drm/gpu_scheduler.h | 1 +
 1 file changed, 1 insertion(+)

index addb135eeea6..c7c487e0c40e 100644
@@ -435,6 +435,7 @@ struct drm_sched_backend_ops {
  * @_score: score used when the driver doesn't provide one
  * @ready: marks if the underlying HW is ready to work
  * @free_guilty: A hit to time out handler to free the guilty job.
+ * @dev: pointer to struct device.
  *
  * One scheduler is implemented for each hardware ring.
  */

2.36.1

Generally in the drm tree we use / rather than : in the patch titles. E.g.,

drm/scheduler: fix a kernel-doc warning

With that fixed:

Add a description for struct device at drm_sched_init(), in order to solve this warning:

drivers/gpu/drm/scheduler/sched_main.c:999: warning: Function parameter or member 'dev' not described in 'drm_sched_init'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/gpu/drm/scheduler/sched_main.c | 1 +
 1 file changed, 1 insertion(+)

index 76fd2904c7c6..b45bd8473e9e 100644
@@ -987,6 +987,7 @@ static int drm_sched_main(void *param)
  *		used
  * @score: optional score atomic shared with other schedulers
  * @name: name used for debugging
+ * @dev: pointer to struct device
  *
  * Return 0 on success, otherwise error code.
  */

2.36.1

Generally in the drm tree we use / rather than : in the patch titles. E.g.,

drm/scheduler: add a missing kernel-doc parameter

With that fixed:

The kernel-doc markup is missing the slab pointer description:

include/linux/kfence.h:221: warning: Function parameter or member 'slab' not described in '__kfence_obj_info'

Document it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/kfence.h | 1 +
 1 file changed, 1 insertion(+)

index 726857a4b680..9c242f4e9fab 100644
@@ -210,6 +210,7 @@ struct kmem_obj_info;
  * __kfence_obj_info() - fill kmem_obj_info struct
  * @kpp: kmem_obj_info to be filled
  * @object: the object
+ * @slab: pointer to slab
  *
  * Return:
  * * false - not a KFENCE object

2.36.1

Thank you.

A maple tree pointer parameter was added at unmap_vmas() without description:

mm/memory.c:1729: warning: Function parameter or member 'mt' not described in 'unmap_vmas'

Document it it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 mm/memory.c | 2 ++
 1 file changed, 2 insertions(+)

index e3d3596068f2..771b61444507 100644
@@ -1707,6 +1707,8 @@ static void unmap_single_vma(struct mmu_gather *tlb,
 /**
  * unmap_vmas - unmap a range of memory covered by a list of vma's
  * @tlb: address of the caller's struct mmu_gather
+ * @mt: maple tree pointer. A maple tree is a RCU-safe range based B-tree
+ *	designed to use modern processor cache efficiently
  * @vma: the starting vma
  * @start_addr: virtual address at which to start unmapping
  * @end_addr: virtual address at which to end unmapping

2.36.1

Copy the same description as found at lib/genalloc.c, fixing this warning:

include/linux/genalloc.h:54: warning: Function parameter or member 'start_addr' not described in 'genpool_algo_t'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/genalloc.h | 1 +
 1 file changed, 1 insertion(+)

index 0bd581003cd5..2a67a54e5018 100644
@@ -44,6 +44,7 @@ struct gen_pool;
  * @nr: The number of zeroed bits we're looking for
  * @data: optional additional data used by the callback
  * @pool: the pool being allocated from
+ * @start_addr: virtual starting address of memory chunk to add to pool
  */
 typedef unsigned long (*genpool_algo_t)(unsigned long *map,
 			unsigned long size,

2.36.1

The list field of struct ts_ops is not documented:

include/linux/textsearch.h:51: warning: Function parameter or member 'list' not described in 'ts_ops'

Add a documentation for it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/textsearch.h | 1 +
 1 file changed, 1 insertion(+)

index 6673e4d4ac2e..29de95657ff1 100644
@@ -35,6 +35,7 @@ struct ts_state
  * @get_pattern: return head of pattern
  * @get_pattern_len: return length of pattern
  * @owner: module reference to algorithm
+ * @list: pointer to ts_ops list
  */
 struct ts_ops
 {

2.36.1

document n_ramp_values field at struct regulator_desc, in order to solve this warning:

include/linux/regulator/driver.h:434: warning: Function parameter or member 'n_ramp_values' not described in 'regulator_desc'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/regulator/driver.h | 1 +
 1 file changed, 1 insertion(+)

index 0228caaa6741..f9a7461e72b8 100644
@@ -348,6 +348,7 @@ enum regulator_type {
  * @ramp_delay_table:	Table for mapping the regulator ramp-rate values. Values
  *			should be given in units of V/S (uV/uS). See the
  *			regulator_set_ramp_delay_regmap().
+ * @n_ramp_values:	number of elements at @ramp_delay_table.
  *
  * @enable_time: Time taken for initial enable of regulator (in uS).
  * @off_on_delay: guard time (in uS), before re-enabling a regulator

2.36.1

This is patch 18 of a series for which I don't have a cover letter or anything. What's the story with dependencies here?

Em Tue, 28 Jun 2022 11:35:00 +0100
Mark Brown <[email protected]> escreveu:

There are no dependnecies. Each patch in this series is independent, touching different files.

Regards,
Mauro

OK. In cases like this it really does generally help to send the patches indepdently (or perhaps split per subsystem), it avoids confusion.

The name of the function is wrong:
include/linux/dcache.h:309: warning: expecting prototype for dget, dget_dlock(). Prototype was for dget_dlock() instead

Fix it.

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/dcache.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index f5bba51480b2..ce0b36f728fa 100644
@@ -297,7 +297,7 @@ extern char *dentry_path(const struct dentry *, char *, int);
 /* Allocation counts.. */
 
 /**
- *	dget, dget_dlock -	get a reference to a dentry
+ *	dget_dlock -	get a reference to a dentry
  *	@dentry: dentry to get a reference to
  *
  *	Given a dentry or %NULL pointer increment the reference count

2.36.1

Without that, the parameter is not properly parsed:
include/linux/usb/typec_altmode.h:132: warning: Function parameter or member 'altmode' not described in 'typec_altmode_get_orientation'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 include/linux/usb/typec_altmode.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 65933cbe9129..350d49012659 100644
@@ -124,7 +124,7 @@ struct typec_altmode *typec_match_altmode(struct typec_altmode **altmodes,
 
 /**
  * typec_altmode_get_orientation - Get cable plug orientation
- * altmode: Handle to the alternate mode
+ * @altmode: Handle to the alternate mode
  */
 static inline enum typec_orientation
 typec_altmode_get_orientation(struct typec_altmode *altmode)

2.36.1

Avoid a kernel-doc warning by documenting it:
drivers/usb/dwc3/core.h:1328: warning: Function parameter or member 'async_callbacks' not described in 'dwc3'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/usb/dwc3/core.h | 2 ++
 1 file changed, 2 insertions(+)

index 722808d8c0af..4fe4287dc934 100644
@@ -1087,6 +1087,8 @@ struct dwc3_scratchpad_array {
  * @dis_u1_entry_quirk: set if link entering into U1 state needs to be disabled.
  * @dis_u2_entry_quirk: set if link entering into U2 state needs to be disabled.
  * @dis_rxdet_inp3_quirk: set if we disable Rx.Detect in P3
+ * @async_callbacks: if set, indicate that async callbacks will be used.
+ *
  * @dis_u2_freeclk_exists_quirk : set if we clear u2_freeclk_exists
  *			in GUSB2PHYCFG, specify that USB2 PHY doesn't
  *			provide a free-running PHY clock.

2.36.1

The multiplier parameter of dwc3_gadget_calc_tx_fifo_size() was not documented:

drivers/usb/dwc3/gadget.c:675: warning: Function parameter or member 'mult' not described in 'dwc3_gadget_calc_tx_fifo_size'

---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH 00/22] at: https://lore.kernel.org/all/[email protected]/

 drivers/usb/dwc3/gadget.c | 1 +
 1 file changed, 1 insertion(+)

index 8716bece1072..a944c7a6c83a 100644
@@ -657,6 +657,7 @@ static int dwc3_gadget_set_ep_config(struct dwc3_ep *dep, unsigned int action)
 /**
  * dwc3_gadget_calc_tx_fifo_size - calculates the txfifo size value
  * @dwc: pointer to the DWC3 context
+ * @mult: multiplier to be used when calculating the fifo_size
  *
  * Calculates the size value based on the equation below:
  *

2.36.1

Applied to

https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator.git for-next

Thanks!

[18/22] regulator: fix a kernel-doc warning

        commit: 0e584d46218e3b9dc12a98e18e81a0cd3e0d5419

All being well this means that it will be integrated into the linux-next tree (usually sometime in the next 24 hours) and sent to Linus during the next merge window (or sooner if it is a bug fix), however if problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing and review of the tree, please engage with people reporting problems and send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they should be sent as incremental updates against current git, existing patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying to this mail.

Thanks,
Mark

To be fair, besides triggering error on kernel-doc warnings, Sphinx warnings should also be errors on CONFIG_WERROR.

An old man doll... just what I always wanted! - Clara