With this series applied there are no kernel-doc issues in ath10k
(ath11k and ath12k have already been previously fixed).
---
Jeff Johnson (5):
wifi: ath10k: add missing wmi_10_4_feature_mask documentation
wifi: ath10k: correctly document enum wmi_tlv_tx_pause_id
wifi: ath10k: fix htt_q_state_conf & htt_q_state kernel-doc
wifi: ath10k: Fix htt_data_tx_completion kernel-doc warning
wifi: ath10k: Fix enum ath10k_fw_crash_dump_type kernel-doc
drivers/net/wireless/ath/ath10k/coredump.h | 8 ++++++--
drivers/net/wireless/ath/ath10k/htt.h | 12 ++++++++----
drivers/net/wireless/ath/ath10k/wmi-tlv.h | 4 ++--
drivers/net/wireless/ath/ath10k/wmi.h | 7 +++++--
4 files changed, 21 insertions(+), 10 deletions(-)
---
base-commit: c1938548bbeed6fcce8fa6e4de9f694994efcc42
change-id: 20240116-ath10k-kerneldoc-61d36e4b1c04
Currently kernel-doc reports the following issues:
drivers/net/wireless/ath/ath10k/wmi.h:3033: warning: Enum value 'WMI_10_4_EXT_PEER_TID_CONFIGS_SUPPORT' not described in enum 'wmi_10_4_feature_mask'
drivers/net/wireless/ath/ath10k/wmi.h:3033: warning: Enum value 'WMI_10_4_REPORT_AIRTIME' not described in enum 'wmi_10_4_feature_mask'
Update the kernel-doc for enum wmi_10_4_feature_mask to add the
missing documentation.
No functional changes, compile tested only.
Signed-off-by: Jeff Johnson <[email protected]>
---
drivers/net/wireless/ath/ath10k/wmi.h | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/drivers/net/wireless/ath/ath10k/wmi.h b/drivers/net/wireless/ath/ath10k/wmi.h
index b64b6e214bae..2379501225a4 100644
--- a/drivers/net/wireless/ath/ath10k/wmi.h
+++ b/drivers/net/wireless/ath/ath10k/wmi.h
@@ -3,7 +3,7 @@
* Copyright (c) 2005-2011 Atheros Communications Inc.
* Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
* Copyright (c) 2018-2019, The Linux Foundation. All rights reserved.
- * Copyright (c) 2021-2023 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021-2024 Qualcomm Innovation Center, Inc. All rights reserved.
*/
#ifndef _WMI_H_
@@ -3008,8 +3008,11 @@ enum wmi_coex_version {
* @WMI_10_4_TDLS_UAPSD_SLEEP_STA: TDLS sleep sta support enable/disable
* @WMI_10_4_TDLS_CONN_TRACKER_IN_HOST_MODE: TDLS connection tracker in host
* enable/disable
- * @WMI_10_4_TDLS_EXPLICIT_MODE_ONLY:Explicit TDLS mode enable/disable
+ * @WMI_10_4_TDLS_EXPLICIT_MODE_ONLY: Explicit TDLS mode enable/disable
* @WMI_10_4_TX_DATA_ACK_RSSI: Enable DATA ACK RSSI if firmware is capable
+ * @WMI_10_4_EXT_PEER_TID_CONFIGS_SUPPORT: Firmware supports Extended Peer
+ * TID configuration for QoS related settings
+ * @WMI_10_4_REPORT_AIRTIME: Firmware supports transmit airtime reporting
*/
enum wmi_10_4_feature_mask {
WMI_10_4_LTEU_SUPPORT = BIT(0),
--
2.42.0
Currently kernel-doc reports:
drivers/net/wireless/ath/ath10k/htt.h:911: warning: Cannot understand * @brief target -> host TX completion indication message definition
on line 911 - I thought it was a doc line
This is because even though struct htt_data_tx_completion uses the
kernel-doc marker "/**", it doesn't actual use kernel-doc syntax for
the documentation. Rather than try to update this legacy driver
documentation to use kernel-doc style, just replace the comment
marker.
No functional changes, compile tested only.
Signed-off-by: Jeff Johnson <[email protected]>
---
drivers/net/wireless/ath/ath10k/htt.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/drivers/net/wireless/ath/ath10k/htt.h b/drivers/net/wireless/ath/ath10k/htt.h
index eb0ce2f49315..603f6de62b0a 100644
--- a/drivers/net/wireless/ath/ath10k/htt.h
+++ b/drivers/net/wireless/ath/ath10k/htt.h
@@ -906,7 +906,7 @@ struct htt_data_tx_completion_ext {
__le16 msdus_rssi[];
} __packed;
-/**
+/*
* @brief target -> host TX completion indication message definition
*
* @details
--
2.42.0
Currently kernel-doc reports the issue:
drivers/net/wireless/ath/ath10k/wmi-tlv.h:2363: warning: cannot understand function prototype: 'enum wmi_tlv_tx_pause_id '
Update the enum wmi_tlv_tx_pause_id documentation to fix this issue.
No functional changes, compile tested only.
Signed-off-by: Jeff Johnson <[email protected]>
---
drivers/net/wireless/ath/ath10k/wmi-tlv.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/net/wireless/ath/ath10k/wmi-tlv.h b/drivers/net/wireless/ath/ath10k/wmi-tlv.h
index 83a8f07a687f..8a2f87d0a3a3 100644
--- a/drivers/net/wireless/ath/ath10k/wmi-tlv.h
+++ b/drivers/net/wireless/ath/ath10k/wmi-tlv.h
@@ -3,7 +3,7 @@
* Copyright (c) 2005-2011 Atheros Communications Inc.
* Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
* Copyright (c) 2018-2019, The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022, 2024 Qualcomm Innovation Center, Inc. All rights reserved.
*/
#ifndef _WMI_TLV_H
#define _WMI_TLV_H
@@ -2343,7 +2343,7 @@ struct wmi_tlv_adaptive_qcs {
} __packed;
/**
- * wmi_tlv_tx_pause_id - firmware tx queue pause reason types
+ * enum wmi_tlv_tx_pause_id - firmware tx queue pause reason types
*
* @WMI_TLV_TX_PAUSE_ID_MCC: used for by multi-channel firmware scheduler.
* Only vdev_map is valid.
--
2.42.0
Currently kernel-doc reports:
drivers/net/wireless/ath/ath10k/htt.h:1488: warning: cannot understand function prototype: 'struct htt_q_state_conf '
drivers/net/wireless/ath/ath10k/htt.h:1542: warning: cannot understand function prototype: 'struct htt_q_state '
Update the kernel-doc for these two structs to resolve the warnings.
No functional changes, compile tested only.
Signed-off-by: Jeff Johnson <[email protected]>
---
drivers/net/wireless/ath/ath10k/htt.h | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/drivers/net/wireless/ath/ath10k/htt.h b/drivers/net/wireless/ath/ath10k/htt.h
index 4a9270e2a4c8..eb0ce2f49315 100644
--- a/drivers/net/wireless/ath/ath10k/htt.h
+++ b/drivers/net/wireless/ath/ath10k/htt.h
@@ -3,7 +3,7 @@
* Copyright (c) 2005-2011 Atheros Communications Inc.
* Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
* Copyright (c) 2018, The Linux Foundation. All rights reserved.
- * Copyright (c) 2021, 2023 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021, 2023-2024 Qualcomm Innovation Center, Inc. All rights reserved.
*/
#ifndef _HTT_H_
@@ -1474,15 +1474,19 @@ enum htt_q_depth_type {
#define HTT_TX_Q_STATE_ENTRY_MULTIPLIER 0
/**
- * htt_q_state_conf - part of htt_frag_desc_bank_cfg for host q state config
+ * struct htt_q_state_conf - part of htt_frag_desc_bank_cfg for host q state config
*
* Defines host q state format and behavior. See htt_q_state.
*
+ * @paddr: Queue physical address
+ * @num_peers: Number of supported peers
+ * @num_tids: Number of supported TIDs
* @record_size: Defines the size of each host q entry in bytes. In practice
* however firmware (at least 10.4.3-00191) ignores this host
* configuration value and uses hardcoded value of 1.
* @record_multiplier: This is valid only when q depth type is MSDUs. It
* defines the exponent for the power of 2 multiplication.
+ * @pad: struct padding for 32-bit alignment
*/
struct htt_q_state_conf {
__le32 paddr;
@@ -1518,7 +1522,7 @@ struct htt_frag_desc_bank_cfg64 {
#define HTT_TX_Q_STATE_ENTRY_EXP_LSB 6
/**
- * htt_q_state - shared between host and firmware via DMA
+ * struct htt_q_state - shared between host and firmware via DMA
*
* This structure is used for the host to expose it's software queue state to
* firmware so that its rate control can schedule fetch requests for optimized
--
2.42.0
The kernel-doc script currently reports:
drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_REGISTERS' not described in enum 'ath10k_fw_crash_dump_type'
drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_CE_DATA' not described in enum 'ath10k_fw_crash_dump_type'
drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_RAM_DATA' not described in enum 'ath10k_fw_crash_dump_type'
drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_MAX' not described in enum 'ath10k_fw_crash_dump_type'
drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Excess enum value 'ATH10K_FW_CRASH_DUMP_REGDUMP' description in 'ath10k_fw_crash_dump_type'
Fix these issues with the enum ath10k_fw_crash_dump_type kernel-doc.
No functional changes, compile tested only.
Signed-off-by: Jeff Johnson <[email protected]>
---
drivers/net/wireless/ath/ath10k/coredump.h | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/drivers/net/wireless/ath/ath10k/coredump.h b/drivers/net/wireless/ath/ath10k/coredump.h
index e5ef0352e319..8d274e0f374b 100644
--- a/drivers/net/wireless/ath/ath10k/coredump.h
+++ b/drivers/net/wireless/ath/ath10k/coredump.h
@@ -1,7 +1,7 @@
/* SPDX-License-Identifier: ISC */
/*
* Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022, 2024 Qualcomm Innovation Center, Inc. All rights reserved.
*/
#ifndef _COREDUMP_H_
@@ -13,7 +13,11 @@
/**
* enum ath10k_fw_crash_dump_type - types of data in the dump file
- * @ATH10K_FW_CRASH_DUMP_REGDUMP: Register crash dump in binary format
+ * @ATH10K_FW_CRASH_DUMP_REGISTERS: Register crash dump in binary format
+ * @ATH10K_FW_CRASH_DUMP_CE_DATA: Copy Engine crash dump data
+ * @ATH10K_FW_CRASH_DUMP_RAM_DATA: RAM crash dump data, contains multiple
+ * struct ath10k_dump_ram_data_hdr
+ * @ATH10K_FW_CRASH_DUMP_MAX: Maximum enumeration
*/
enum ath10k_fw_crash_dump_type {
ATH10K_FW_CRASH_DUMP_REGISTERS = 0,
--
2.42.0
On 1/18/24 08:12, Jeff Johnson wrote:
> Currently kernel-doc reports the issue:
> drivers/net/wireless/ath/ath10k/wmi-tlv.h:2363: warning: cannot understand function prototype: 'enum wmi_tlv_tx_pause_id '
>
> Update the enum wmi_tlv_tx_pause_id documentation to fix this issue.
>
> No functional changes, compile tested only.
>
> Signed-off-by: Jeff Johnson <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Thanks.
> ---
> drivers/net/wireless/ath/ath10k/wmi-tlv.h | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/net/wireless/ath/ath10k/wmi-tlv.h b/drivers/net/wireless/ath/ath10k/wmi-tlv.h
> index 83a8f07a687f..8a2f87d0a3a3 100644
> --- a/drivers/net/wireless/ath/ath10k/wmi-tlv.h
> +++ b/drivers/net/wireless/ath/ath10k/wmi-tlv.h
> @@ -3,7 +3,7 @@
> * Copyright (c) 2005-2011 Atheros Communications Inc.
> * Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
> * Copyright (c) 2018-2019, The Linux Foundation. All rights reserved.
> - * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
> + * Copyright (c) 2022, 2024 Qualcomm Innovation Center, Inc. All rights reserved.
> */
> #ifndef _WMI_TLV_H
> #define _WMI_TLV_H
> @@ -2343,7 +2343,7 @@ struct wmi_tlv_adaptive_qcs {
> } __packed;
>
> /**
> - * wmi_tlv_tx_pause_id - firmware tx queue pause reason types
> + * enum wmi_tlv_tx_pause_id - firmware tx queue pause reason types
> *
> * @WMI_TLV_TX_PAUSE_ID_MCC: used for by multi-channel firmware scheduler.
> * Only vdev_map is valid.
>
--
#Randy
On 1/18/24 08:12, Jeff Johnson wrote:
> Currently kernel-doc reports:
> drivers/net/wireless/ath/ath10k/htt.h:1488: warning: cannot understand function prototype: 'struct htt_q_state_conf '
> drivers/net/wireless/ath/ath10k/htt.h:1542: warning: cannot understand function prototype: 'struct htt_q_state '
>
> Update the kernel-doc for these two structs to resolve the warnings.
>
> No functional changes, compile tested only.
>
> Signed-off-by: Jeff Johnson <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
> ---
> drivers/net/wireless/ath/ath10k/htt.h | 10 +++++++---
> 1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/drivers/net/wireless/ath/ath10k/htt.h b/drivers/net/wireless/ath/ath10k/htt.h
> index 4a9270e2a4c8..eb0ce2f49315 100644
> --- a/drivers/net/wireless/ath/ath10k/htt.h
> +++ b/drivers/net/wireless/ath/ath10k/htt.h
> @@ -3,7 +3,7 @@
> * Copyright (c) 2005-2011 Atheros Communications Inc.
> * Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
> * Copyright (c) 2018, The Linux Foundation. All rights reserved.
> - * Copyright (c) 2021, 2023 Qualcomm Innovation Center, Inc. All rights reserved.
> + * Copyright (c) 2021, 2023-2024 Qualcomm Innovation Center, Inc. All rights reserved.
> */
>
> #ifndef _HTT_H_
> @@ -1474,15 +1474,19 @@ enum htt_q_depth_type {
> #define HTT_TX_Q_STATE_ENTRY_MULTIPLIER 0
>
> /**
> - * htt_q_state_conf - part of htt_frag_desc_bank_cfg for host q state config
> + * struct htt_q_state_conf - part of htt_frag_desc_bank_cfg for host q state config
> *
> * Defines host q state format and behavior. See htt_q_state.
> *
> + * @paddr: Queue physical address
> + * @num_peers: Number of supported peers
> + * @num_tids: Number of supported TIDs
> * @record_size: Defines the size of each host q entry in bytes. In practice
> * however firmware (at least 10.4.3-00191) ignores this host
> * configuration value and uses hardcoded value of 1.
> * @record_multiplier: This is valid only when q depth type is MSDUs. It
> * defines the exponent for the power of 2 multiplication.
> + * @pad: struct padding for 32-bit alignment
> */
> struct htt_q_state_conf {
> __le32 paddr;
> @@ -1518,7 +1522,7 @@ struct htt_frag_desc_bank_cfg64 {
> #define HTT_TX_Q_STATE_ENTRY_EXP_LSB 6
>
> /**
> - * htt_q_state - shared between host and firmware via DMA
> + * struct htt_q_state - shared between host and firmware via DMA
> *
> * This structure is used for the host to expose it's software queue state to
its
fwiw.
> * firmware so that its rate control can schedule fetch requests for optimized
>
--
#Randy
On 1/18/24 08:12, Jeff Johnson wrote:
> Currently kernel-doc reports:
> drivers/net/wireless/ath/ath10k/htt.h:911: warning: Cannot understand * @brief target -> host TX completion indication message definition
> on line 911 - I thought it was a doc line
>
> This is because even though struct htt_data_tx_completion uses the
> kernel-doc marker "/**", it doesn't actual use kernel-doc syntax for
> the documentation. Rather than try to update this legacy driver
> documentation to use kernel-doc style, just replace the comment
> marker.
>
> No functional changes, compile tested only.
>
> Signed-off-by: Jeff Johnson <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Thanks.
> ---
> drivers/net/wireless/ath/ath10k/htt.h | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/net/wireless/ath/ath10k/htt.h b/drivers/net/wireless/ath/ath10k/htt.h
> index eb0ce2f49315..603f6de62b0a 100644
> --- a/drivers/net/wireless/ath/ath10k/htt.h
> +++ b/drivers/net/wireless/ath/ath10k/htt.h
> @@ -906,7 +906,7 @@ struct htt_data_tx_completion_ext {
> __le16 msdus_rssi[];
> } __packed;
>
> -/**
> +/*
> * @brief target -> host TX completion indication message definition
> *
> * @details
>
--
#Randy
On 1/18/24 08:12, Jeff Johnson wrote:
> The kernel-doc script currently reports:
> drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_REGISTERS' not described in enum 'ath10k_fw_crash_dump_type'
> drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_CE_DATA' not described in enum 'ath10k_fw_crash_dump_type'
> drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_RAM_DATA' not described in enum 'ath10k_fw_crash_dump_type'
> drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Enum value 'ATH10K_FW_CRASH_DUMP_MAX' not described in enum 'ath10k_fw_crash_dump_type'
> drivers/net/wireless/ath/ath10k/coredump.h:27: warning: Excess enum value 'ATH10K_FW_CRASH_DUMP_REGDUMP' description in 'ath10k_fw_crash_dump_type'
>
> Fix these issues with the enum ath10k_fw_crash_dump_type kernel-doc.
>
> No functional changes, compile tested only.
>
> Signed-off-by: Jeff Johnson <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Thanks.
> ---
> drivers/net/wireless/ath/ath10k/coredump.h | 8 ++++++--
> 1 file changed, 6 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/net/wireless/ath/ath10k/coredump.h b/drivers/net/wireless/ath/ath10k/coredump.h
> index e5ef0352e319..8d274e0f374b 100644
> --- a/drivers/net/wireless/ath/ath10k/coredump.h
> +++ b/drivers/net/wireless/ath/ath10k/coredump.h
> @@ -1,7 +1,7 @@
> /* SPDX-License-Identifier: ISC */
> /*
> * Copyright (c) 2011-2017 Qualcomm Atheros, Inc.
> - * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
> + * Copyright (c) 2022, 2024 Qualcomm Innovation Center, Inc. All rights reserved.
> */
>
> #ifndef _COREDUMP_H_
> @@ -13,7 +13,11 @@
>
> /**
> * enum ath10k_fw_crash_dump_type - types of data in the dump file
> - * @ATH10K_FW_CRASH_DUMP_REGDUMP: Register crash dump in binary format
> + * @ATH10K_FW_CRASH_DUMP_REGISTERS: Register crash dump in binary format
> + * @ATH10K_FW_CRASH_DUMP_CE_DATA: Copy Engine crash dump data
> + * @ATH10K_FW_CRASH_DUMP_RAM_DATA: RAM crash dump data, contains multiple
> + * struct ath10k_dump_ram_data_hdr
> + * @ATH10K_FW_CRASH_DUMP_MAX: Maximum enumeration
> */
> enum ath10k_fw_crash_dump_type {
> ATH10K_FW_CRASH_DUMP_REGISTERS = 0,
>
--
#Randy
Jeff Johnson <[email protected]> wrote:
> Currently kernel-doc reports the following issues:
> drivers/net/wireless/ath/ath10k/wmi.h:3033: warning: Enum value 'WMI_10_4_EXT_PEER_TID_CONFIGS_SUPPORT' not described in enum 'wmi_10_4_feature_mask'
> drivers/net/wireless/ath/ath10k/wmi.h:3033: warning: Enum value 'WMI_10_4_REPORT_AIRTIME' not described in enum 'wmi_10_4_feature_mask'
>
> Update the kernel-doc for enum wmi_10_4_feature_mask to add the
> missing documentation.
>
> No functional changes, compile tested only.
>
> Signed-off-by: Jeff Johnson <[email protected]>
> Signed-off-by: Kalle Valo <[email protected]>
5 patches applied to ath-next branch of ath.git, thanks.
1779487e72e0 wifi: ath10k: add missing wmi_10_4_feature_mask documentation
5f813b0447fe wifi: ath10k: correctly document enum wmi_tlv_tx_pause_id
75dd17fdef11 wifi: ath10k: fix htt_q_state_conf & htt_q_state kernel-doc
c80cc5cfefba wifi: ath10k: Fix htt_data_tx_completion kernel-doc warning
f020c3029932 wifi: ath10k: Fix enum ath10k_fw_crash_dump_type kernel-doc
--
https://patchwork.kernel.org/project/linux-wireless/patch/[email protected]/
https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches