qcacmn: Fix spectral documentation

The kernel-doc script identified a number of kernel-doc issues in the
spectral folder, so fix them.

Change-Id: Ibe12245209afd57b73996fbea2901443d0d9363c
CRs-Fixed: 3376641

spectral/core/spectral_cmn_api_i.h

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2017-2019 The Linux Foundation. All rights reserved.
+ * Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  *
  * Permission to use, copy, modify, and/or distribute this software for
@@ -118,12 +119,12 @@ int spectral_control_ol(
 /**
  * spectral_get_spectral_ctx_from_pdev() - API to get spectral context object
  *                                         from pdev
- * @pdev : Reference to pdev global object
+ * @pdev: Reference to pdev global object
  *
  * This API used to get spectral context object from global pdev reference.
  * Null check should be done before invoking this inline function.
  *
- * Return : Reference to spectral_context object
+ * Return: Reference to spectral_context object
  */
 static inline struct spectral_context *
 spectral_get_spectral_ctx_from_pdev(struct wlan_objmgr_pdev *pdev)
@@ -142,14 +143,14 @@ spectral_get_spectral_ctx_from_pdev(struct wlan_objmgr_pdev *pdev)
 }
 
 /**
- * spectral_get_spectral_ctx_from_pscoc() - API to get spectral context object
+ * spectral_get_spectral_ctx_from_psoc() - API to get spectral context object
  *                                         from psoc
- * @psoc : Reference to psoc global object
+ * @psoc: Reference to psoc global object
  *
  * This API used to get spectral context object from global psoc reference.
  * Null check should be done before invoking this inline function.
  *
- * Return : Reference to spectral_context object
+ * Return: Reference to spectral_context object
  */
 static inline struct spectral_context *
 spectral_get_spectral_ctx_from_psoc(struct wlan_objmgr_psoc *psoc)
@@ -168,12 +169,12 @@ spectral_get_spectral_ctx_from_psoc(struct wlan_objmgr_psoc *psoc)
 /**
  * spectral_get_spectral_ctx_from_vdev() - API to get spectral context object
  *                                         from vdev
- * @vdev : Reference to vdev global object
+ * @vdev: Reference to vdev global object
  *
  * This API used to get spectral context object from global vdev reference.
  * Null check should be done before invoking this inline function.
  *
- * Return : Reference to spectral_context object
+ * Return: Reference to spectral_context object
  */
 static inline struct spectral_context *
 spectral_get_spectral_ctx_from_vdev(struct wlan_objmgr_vdev *vdev)

spectral/core/spectral_common.c

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2011,2017-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  *
  * Permission to use, copy, modify, and/or distribute this software for
@@ -491,7 +491,7 @@ bad:
 
 /**
  * spectral_ctx_deinit() - De-initialize function pointers from spectral context
- * @sc - Reference to spectral_context object
+ * @sc: Reference to spectral_context object
  *
  * Return: None
  */

spectral/core/spectral_defs_i.h

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2017-2020 The Linux Foundation. All rights reserved.
+ * Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  *
  * Permission to use, copy, modify, and/or distribute this software for
@@ -100,9 +101,10 @@ struct spectral_tgt_ops;
  * struct spectral_context - spectral global context
  * @psoc_obj:               Reference to psoc global object
  * @psoc_target_handle: Reference to psoc target_if object
- * @spectral_legacy_cbacks: Spectral legacy callbacks
+ * @legacy_cbacks: Spectral legacy callbacks
  *
  * Call back functions to invoke independent of OL/DA
+ * @sptrlc_spectral_control:
  * @sptrlc_ucfg_phyerr_config:     ucfg handler for phyerr
  * @sptrlc_pdev_spectral_init: Init pdev Spectral
  * @sptrlc_pdev_spectral_deinit: Deinit pdev Spectral
@@ -119,7 +121,7 @@ struct spectral_tgt_ops;
  * @sptrlc_get_spectral_capinfo:   Get spectral capability info
  * @sptrlc_get_spectral_diagstats: Get spectral diag status
  * @sptrlc_register_spectral_wmi_ops: Register Spectral WMI operations
- * @ptrlc_register_spectral_tgt_ops: Register Spectral target operations
+ * @sptrlc_register_spectral_tgt_ops: Register Spectral target operations
  * @sptrlc_register_netlink_cb: Register Netlink callbacks
  * @sptrlc_use_nl_bcast: Check whether to use Netlink broadcast/unicast
  * @sptrlc_deregister_netlink_cb: De-register Netlink callbacks

spectral/dispatcher/inc/spectral_ioctl.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2011, 2017-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  * Permission to use, copy, modify, and/or distribute this software for
  * any purpose with or without fee is hereby granted, provided that the
@@ -218,7 +218,7 @@ struct spectral_ioctl_params {
 };
 
 /**
- * spectral_cap_hw_gen: Definitions for the Spectral hardware generation.
+ * enum spectral_cap_hw_gen - Definitions for the Spectral hardware generation.
  * This corresponds to definitions in qca_wlan_vendor_spectral_scan_cap_hw_gen.
  * @SPECTRAL_CAP_HW_GEN_1: Generation 1
  * @SPECTRAL_CAP_HW_GEN_2: Generation 2
@@ -249,7 +249,7 @@ struct spectral_config_frequency {
  * struct spectral_config - spectral config parameters
  * @ss_fft_period:        Skip interval for FFT reports
  * @ss_period:            Spectral scan period
- * @ss_recapture          Set this to allow FFT recapture if scan period > 52us
+ * @ss_recapture:         Set this to allow FFT recapture if scan period > 52us
  * @ss_count:             # of reports to return from ss_active
  * @ss_short_report:      Set to report only 1 set of FFT results
  * @radar_bin_thresh_sel: Select threshold to classify strong bin for FFT
@@ -317,7 +317,7 @@ struct spectral_config_frequency {
  *                          applicable only for Agile Spectral scan request in
  *                          80+80 MHz mode. For 80+80 mode it represents  the
  *                          center frequency (in MHz) of the secondary 80 MHz
-*                           span of interest or center frequency (in MHz) of
+ *                          span of interest or center frequency (in MHz) of
  *                          any WLAN channel in the secondary 80 MHz span of
  *                          interest.
  * @ss_bandwidth: Spectral scan bandwidth
@@ -523,6 +523,8 @@ SPECTRAL_COMPILE_TIME_ASSERT(struct_size_4byte_assertion,
  * @max_magnitude: Indicates the maximum magnitude
  * @noise_floor: Indicates the current noise floor
  * @rssi: Indicates RSSI
+ * @agc_total_gain:
+ * @gainchange:
  * @pri80ind: Indication from hardware that the sample was received on the
  * primary 80 MHz segment. If this is set for smode = SPECTRAL_SCAN_MODE_AGILE,
  * it indicates that Spectral scan was carried out on pri80 instead of the
@@ -531,6 +533,7 @@ SPECTRAL_COMPILE_TIME_ASSERT(struct_size_4byte_assertion,
  * @is_sec80: Indicates whether the frequency span corresponds to pri80 or
  * sec80 (only applicable for 160/80p80 operating_bw for
  * smode SPECTRAL_SCAN_MODE_NORMAL)
+ * @padding_detector_info: padding bytes
  */
 struct samp_detector_info {
 	uint32_t start_frequency;
@@ -567,6 +570,7 @@ SPECTRAL_COMPILE_TIME_ASSERT(struct_size_4byte_assertion,
  * Spectral scan and interference detection is carried out.
  * @detector_info: Per-detector Spectral information
  * @num_detectors: Number of detectors per span
+ * @padding_span_info: padding bytes
  */
 struct samp_freq_span_info {
 	struct samp_detector_info detector_info[MAX_NUM_DETECTORS];
@@ -676,6 +680,10 @@ struct spectral_samp_msg {
  * @noise_floor_sec80:        Indicates the current noise floor for secondary 80
  *                            segment
  * @ch_width:                 Channel width 20/40/80/160 MHz
+ * @spectral_agc_total_gain:
+ * @spectral_agc_total_gain_sec80:
+ * @spectral_gainchange:
+ * @spectral_gainchange_sec80:
  * @spectral_mode:            Spectral scan mode
  * @spectral_pri80ind:        Indication from hardware that the sample was
  *                            received on the primary 80 MHz segment. If this
@@ -707,6 +715,7 @@ struct spectral_samp_msg {
  *                            via direct DMA framework.
  * @target_reset_count:       Indicates the number of times target went through
  *                            reset routine after spectral was enabled.
+ * @agile_ch_width:
  * @bin_pwr_count_5mhz:       Indicates the number of FFT bins in the extra
  *                            5 MHz for 165 MHz/ Restricted 80p80 mode
  * @bin_pwr_5mhz:             Contains FFT magnitudes corresponding to the extra

spectral/dispatcher/inc/wlan_spectral_public_structs.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2011,2017-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  *
  * Permission to use, copy, modify, and/or distribute this software for
@@ -140,6 +140,7 @@
  * @SPECTRAL_MSG_BUF_NEW: Allocate new buffer
  * @SPECTRAL_MSG_BUF_SAVED: Reuse last buffer, used for secondary segment report
  *                          in case of 160 MHz.
+ * @SPECTRAL_MSG_BUF_TYPE_MAX: Max enumeration
  */
 enum spectral_msg_buf_type {
 	SPECTRAL_MSG_BUF_NEW,
@@ -195,11 +196,11 @@ enum spectral_capability_type {
 
 /**
  * enum spectral_cp_error_code - Spectral control path response code
- * @SPECTRAL_SCAN_RESP_ERR_INVALID: Invalid error identifier
- * @SPECTRAL_SCAN_RESP_ERR_PARAM_UNSUPPORTED: parameter unsupported
- * @SPECTRAL_SCAN_RESP_ERR_MODE_UNSUPPORTED: mode unsupported
- * @SPECTRAL_SCAN_RESP_ERR_PARAM_INVALID_VALUE: invalid parameter value
- * @SPECTRAL_SCAN_RESP_ERR_PARAM_NOT_INITIALIZED: parameter uninitialized
+ * @SPECTRAL_SCAN_ERR_INVALID: Invalid error identifier
+ * @SPECTRAL_SCAN_ERR_PARAM_UNSUPPORTED: parameter unsupported
+ * @SPECTRAL_SCAN_ERR_MODE_UNSUPPORTED: mode unsupported
+ * @SPECTRAL_SCAN_ERR_PARAM_INVALID_VALUE: invalid parameter value
+ * @SPECTRAL_SCAN_ERR_PARAM_NOT_INITIALIZED: parameter uninitialized
  */
 enum spectral_cp_error_code {
 	SPECTRAL_SCAN_ERR_INVALID,
@@ -347,6 +348,8 @@ struct wlan_objmgr_pdev;
  * @send_nl_bcast:  Send data to the application using netlink broadcast
  * @send_nl_unicast:  Send data to the application using netlink unicast
  * @free_sbuff: Free the socket buffer for a particular message type
+ * @convert_to_nl_ch_width:
+ * @convert_to_phy_ch_width:
  */
 struct spectral_nl_cb {
 	void *(*get_sbuff)(struct wlan_objmgr_pdev *pdev,
@@ -451,6 +454,13 @@ struct spectral_scan_dma_debug_request {
  * @ss_mode: Spectral scan mode
  * @req_id: Request identifier
  * @vdev_id: VDEV id
+ * @config_req: Spectral scan config request
+ * @action_req: Spectral scan action request
+ * @caps_req: Spectral scan get caps request
+ * @diag_req: Spectral scan get diag request
+ * @chan_width_req:Spectral scan get chan width request
+ * @status_req: Spectral scan get status request
+ * @debug_req: Spectral scan debug request
  * @dma_debug_req: Spectral DMA debug request
  */
 struct spectral_cp_request {

spectral/dispatcher/inc/wlan_spectral_tgt_api.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2017-2020 The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  * Permission to use, copy, modify, and/or distribute this software for
  * any purpose with or without fee is hereby granted, provided that the
@@ -112,8 +112,8 @@ QDF_STATUS tgt_set_spectral_config(struct wlan_objmgr_pdev *pdev,
 /**
  * tgt_get_spectral_config() - Get spectral configuration
  * @pdev: Pointer to pdev object
- * @param: Pointer to spectral_config structure in which the configuration
- * should be returned
+ * @sptrl_config: Pointer to spectral_config structure in which the
+ *                configuration should be returned
  * @smode: Spectral scan mode
  *
  * Implementation for getting the current spectral configuration

spectral/dispatcher/inc/wlan_spectral_ucfg_api.h

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2017-2020 The Linux Foundation. All rights reserved.
+ * Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  *
  * Permission to use, copy, modify, and/or distribute this software for
@@ -63,7 +64,7 @@ QDF_STATUS ucfg_spectral_create_cp_req(struct spectral_cp_request *sscan_req,
 				       void *indata, u_int32_t insize);
 
 /**
- * ucfg_spectral_create_cp_req() - Extract response from Spectral CP request
+ * ucfg_spectral_extract_response() - Extract response from Spectral CP request
  * @sscan_req: Pointer to Spectral scan request
  * @outdata: pointer output data
  * @outsize: Size of output data

spectral/dispatcher/inc/wlan_spectral_utils_api.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2017-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
  *
  * Permission to use, copy, modify, and/or distribute this software for
  * any purpose with or without fee is hereby granted, provided that the
@@ -31,7 +31,7 @@ struct spectral_tgt_ops;
 /**
  * wlan_spectral_is_feature_disabled_pdev() - Check if spectral feature
  * is disabled for a given pdev
- * @pdev - pointer to pdev
+ * @pdev: pointer to pdev
  *
  * Return : true if spectral is disabled, else false.
  */
@@ -40,7 +40,7 @@ bool wlan_spectral_is_feature_disabled_pdev(struct wlan_objmgr_pdev *pdev);
 /**
  * wlan_spectral_is_feature_disabled_ini() - Check if spectral feature
  * is disabled in INI
- * @psoc - pointer to psoc
+ * @psoc: pointer to psoc
  *
  * Return : true if spectral is disabled, else false.
  */
@@ -49,7 +49,7 @@ bool wlan_spectral_is_feature_disabled_ini(struct wlan_objmgr_psoc *psoc);
 /**
  * wlan_spectral_is_feature_disabled_psoc() - Check if spectral feature
  * is disabled for a given psoc
- * @psoc - pointer to psoc
+ * @psoc: pointer to psoc
  *
  * Return : true if spectral is disabled, else false.
  */
@@ -58,8 +58,8 @@ bool wlan_spectral_is_feature_disabled_psoc(struct wlan_objmgr_psoc *psoc);
 /**
  * wlan_spectral_is_mode_disabled_pdev() - Check if a given spectral mode
  * is disabled for a given pdev
- * @pdev - pointer to pdev
- * @smode - spectral scan mode
+ * @pdev: pointer to pdev
+ * @smode: spectral scan mode
  *
  * Return : true if spectral mode is disabled, else false.
  */
@@ -103,8 +103,8 @@ wlan_lmac_if_sptrl_register_rx_ops(struct wlan_lmac_if_rx_ops *rx_ops);
 
 /**
  * wlan_register_spectral_wmi_ops() - Register Spectral WMI operations
- * @psoc - Pointer to psoc object
- * @wmi_ops - pointer to the structure holding the Spectral WMI
+ * @psoc: Pointer to psoc object
+ * @wmi_ops: pointer to the structure holding the Spectral WMI
  *            operations
  *
  * API to register Spectral WMI operations
@@ -117,8 +117,8 @@ wlan_register_spectral_wmi_ops(struct wlan_objmgr_psoc *psoc,
 
 /**
  * wlan_register_spectral_tgt_ops() - Register Spectral target operations
- * @psoc - Pointer to psoc object
- * @tgt_ops - pointer to the structure holding the Spectral target
+ * @psoc: Pointer to psoc object
+ * @tgt_ops: pointer to the structure holding the Spectral target
  *            operations
  *
  * API to register Spectral target operations
@@ -145,7 +145,7 @@ struct spectral_legacy_cbacks {
 };
 
 /**
- * spectral_vdev_get_chan_freq - Get vdev channel frequency
+ * spectral_vdev_get_chan_freq() - Get vdev channel frequency
  * @vdev:          vdev object
  *
  * Return: vdev operating frequency
@@ -153,7 +153,7 @@ struct spectral_legacy_cbacks {
 int16_t spectral_vdev_get_chan_freq(struct wlan_objmgr_vdev *vdev);
 
 /**
- * spectral_vdev_get_chan_freq_seg2 - Get vdev's secondary 80 center frequency
+ * spectral_vdev_get_chan_freq_seg2() - Get vdev's secondary 80 center frequency
  * @vdev: vdev object
  *
  * Return: vdev secondary 80 center frequency
@@ -161,7 +161,7 @@ int16_t spectral_vdev_get_chan_freq(struct wlan_objmgr_vdev *vdev);
 int16_t spectral_vdev_get_chan_freq_seg2(struct wlan_objmgr_vdev *vdev);
 
 /**
- * spectral_vdev_get_sec20chan_freq_mhz - Get vdev secondary channel frequency
+ * spectral_vdev_get_sec20chan_freq_mhz() - Get vdev secondary channel frequency
  * @vdev:   vdev object
  * @sec20chan_freq: secondary channel frequency
  *
@@ -173,8 +173,8 @@ int spectral_vdev_get_sec20chan_freq_mhz(struct wlan_objmgr_vdev *vdev,
 /**
  * spectral_register_legacy_cb() - Register spectral legacy callbacks
  * commands on spectral parameters
- * @psoc    - the physical device object
- * @legacy_cbacks - Reference to struct spectral_legacy_cbacks from which
+ * @psoc: the physical device object
+ * @legacy_cbacks: Reference to struct spectral_legacy_cbacks from which
  * function pointers need to be copied
  *
  * API to register spectral related legacy callbacks
@@ -188,7 +188,7 @@ QDF_STATUS spectral_register_legacy_cb(
 
 /**
  * spectral_vdev_get_ch_width() - Get the channel bandwidth
- * @vdev    - Pointer to vdev
+ * @vdev: Pointer to vdev
  *
  * API to get the channel bandwidth of a given vdev
  *