qcacmn: Fix target_if/spectral documentation

The kernel-doc script identified documentation issues in the
target_if/spectral folder, so fix them.

Change-Id: I0bb7d3632fd602450713d8521861d246ea5f33df
CRs-Fixed: 3417470

target_if/spectral/target_if_spectral.c

@@ -33,7 +33,7 @@
 #include <wlan_reg_services_api.h>
 #include <wlan_dfs_ucfg_api.h>
 
-/**
+/*
  * @spectral_ops - Spectral function table, holds the Spectral functions that
  * depend on whether the architecture is Direct Attach or Offload. This is used
  * to populate the actual Spectral function table present in the Spectral
@@ -624,7 +624,7 @@ static inline bool is_spectral_arch_beryllium(uint32_t target_tpe)
 	return false;
 }
 
-/**
+/*
  * List of supported sscan BWs. Make sure to maintain the array elements in the
  * same order of BWs as that of struct spectral_supported_bws bitmap.
  */
@@ -1001,8 +1001,7 @@ target_if_log_read_spectral_enabled(
 }
 
 /**
- * target_if_log_read_spectral_enabled() - Helper function to log spectral
- * parameters after reading cache
+ * target_if_log_read_spectral_params() - log spectral parameters
  * @function_name: Function name
  * @pparam: Spectral parameters
  *
@@ -3057,7 +3056,7 @@ target_if_spectral_detach_simulation(struct target_if_spectral *spectral)
 
 /**
  * target_if_spectral_detach() - De-initialize target_if Spectral
- * @pdev: Pointer to pdev object
+ * @spectral: Pointer to Spectral target_if internal private data
  *
  * Function to detach target_if spectral
  *
@@ -3887,14 +3886,14 @@ fail:
 }
 
 /**
- * target_if_calculate_center_freq() - Helper routine to
- * check whether given frequency is center frequency of a
- * WLAN channel
- *
- * @spectral: Pointer to Spectral object
+ * target_if_is_center_freq_of_any_chan() - Check for center frequency
+ * @pdev: Pointer to pdev object
  * @chan_freq: Center frequency of a WLAN channel
  * @is_valid: Indicates whether given frequency is valid
  *
+ * Helper routine to check whether given frequency is center frequency
+ * of a WLAN channel
+ *
  * Return: QDF_STATUS
  */
 static QDF_STATUS
@@ -3947,15 +3946,15 @@ target_if_is_center_freq_of_any_chan(struct wlan_objmgr_pdev *pdev,
 }
 
 /**
- * target_if_calculate_center_freq() - Helper routine to
- * find the center frequency of the agile span from a
- * WLAN channel center frequency
- *
+ * target_if_calculate_center_freq() - find center frequency of agile span
  * @spectral: Pointer to Spectral object
  * @ch_width: Channel width array
  * @chan_freq: Center frequency of a WLAN channel
  * @center_freq: Pointer to center frequency
  *
+ * Helper routine to find the center frequency of the agile span from
+ * a WLAN channel center frequency
+ *
  * Return: QDF_STATUS
  */
 static QDF_STATUS
@@ -4012,14 +4011,14 @@ target_if_calculate_center_freq(struct target_if_spectral *spectral,
 }
 
 /**
- * target_if_validate_center_freq() - Helper routine to
- * validate user provided agile center frequency
- *
+ * target_if_validate_center_freq() - validate agile center frequency
  * @spectral: Pointer to Spectral object
  * @ch_width: Channel width array
  * @center_freq: User provided agile span center frequency
  * @is_valid: Indicates whether agile span center frequency is valid
  *
+ * Helper routine to validate user provided agile center frequency
+ *
  * Return: QDF_STATUS
  */
 static QDF_STATUS
@@ -4782,7 +4781,6 @@ target_if_set_spectral_config(struct wlan_objmgr_pdev *pdev,
 /**
  * target_if_get_fft_bin_count() - Get fft bin count for a given fft length
  * @fft_len: FFT length
- * @pdev: Pointer to pdev object
  *
  * API to get fft bin count for a given fft length
  *
@@ -5445,8 +5443,8 @@ target_if_is_aspectral_prohibited_by_adfs(struct wlan_objmgr_psoc *psoc,
 
 /**
  * target_if_get_curr_band() - Get current operating band of pdev
- *
  * @pdev: pointer to pdev object
+ * @vdev_id: id of vdev
  *
  * API to get current operating band of a given pdev.
  *

target_if/spectral/target_if_spectral.h

@@ -139,7 +139,7 @@
 #define TLV_TAG_ADC_REPORT_GEN2                  0xFA
 #define TLV_TAG_SEARCH_FFT_REPORT_GEN2           0xFB
 
-/**
+/*
  * The Maximum number of detector information to be filled in the SAMP msg
  * is 3, only for 165MHz case. For all other cases this value will be 1.
  */
@@ -294,7 +294,7 @@ struct spectral_phyerr_fft_gen2 {
  * @pfft: Pointer to FFT info in Phyerr event
  * @acs_stats: Pointer to ACS stats struct
  * @tsf64: 64 bit TSF value
- * @seg_d : Segment ID
+ * @seg_id: Segment ID
  */
 struct spectral_process_phyerr_info_gen2 {
 	struct target_if_spectral_rfqual_info *p_rfqual;
@@ -445,7 +445,7 @@ struct spectral_search_fft_info_gen3 {
 };
 
 /**
- * struct spectral_phyerr_sfftreport_gen3 - fft info in phyerr event
+ * struct spectral_phyerr_fft_report_gen3 - fft info in phyerr event
  * @fft_timestamp:  Timestamp at which fft report was generated
  * @fft_hdr_lts:    length, tag, signature fields
  * @hdr_a:          Header[0:31]
@@ -496,7 +496,7 @@ struct sscan_report_fields_gen3 {
  * @sscan_timestamp:  Timestamp at which fft report was generated
  * @sscan_hdr_lts:    length, tag, signature fields
  * @hdr_a:          Header[0:31]
- * @resv:           Header[32:63]
+ * @res1:           Header[32:63]
  * @hdr_b:          Header[64:95]
  * @hdr_c:          Header[96:127]
  */
@@ -526,7 +526,7 @@ struct spectral_sscan_summary_report_padding_gen3_v2 {
 
 #ifdef DIRECT_BUF_RX_ENABLE
 /**
- * struct Spectral_report - spectral report
+ * struct spectral_report - spectral report
  * @data: Report buffer
  * @noisefloor: Noise floor values
  * @reset_delay: Time taken for warm reset in us
@@ -561,13 +561,13 @@ enum spectral_gen {
 
 /**
  * enum spectral_fftbin_size_war - spectral fft bin size war
- * @SPECTRAL_FFTBIN_SIZE_NO_WAR : No WAR applicable for Spectral FFT bin size
- * @SPECTRAL_FFTBIN_SIZE_2BYTE_TO_1BYTE : Spectral FFT bin size: Retain only
- *                                        least significant byte from 2 byte
- *                                        FFT bin transferred by HW
- * @SPECTRAL_FFTBIN_SIZE_4BYTE_TO_1BYTE : Spectral FFT bin size: Retain only
- *                                        least significant byte from 4 byte
- *                                        FFT bin transferred by HW
+ * @SPECTRAL_FFTBIN_SIZE_NO_WAR: No WAR applicable for Spectral FFT bin size
+ * @SPECTRAL_FFTBIN_SIZE_WAR_2BYTE_TO_1BYTE: Spectral FFT bin size: Retain only
+ *                                           least significant byte from 2 byte
+ *                                           FFT bin transferred by HW
+ * @SPECTRAL_FFTBIN_SIZE_WAR_4BYTE_TO_1BYTE: Spectral FFT bin size: Retain only
+ *                                           least significant byte from 4 byte
+ *                                           FFT bin transferred by HW
  */
 enum spectral_fftbin_size_war {
 	SPECTRAL_FFTBIN_SIZE_NO_WAR = 0,
@@ -659,7 +659,7 @@ struct spectral_param_min_max {
 };
 
 /**
- * struct spectral_timestamp_swar - Spectral time stamp WAR related parameters
+ * struct spectral_timestamp_war - Spectral time stamp WAR related parameters
  * @timestamp_war_offset: Offset to be added to correct timestamp
  * @target_reset_count: Number of times target exercised the reset routine
  * @last_fft_timestamp: last fft report timestamp
@@ -832,7 +832,7 @@ struct target_if_spectral_ops {
  * @early_ext_phy_errors: Early secondary channel phyerrors
  * @bwinfo_errors:        Bandwidth info errors
  * @datalen_discards:     Invalid data length errors, seen in gen1 chipsets
- * @rssi_discards bw:     Indicates reports dropped due to RSSI threshold
+ * @rssi_discards:        Indicates reports dropped due to RSSI threshold
  * @last_reset_tstamp:    Last reset time stamp
  */
 struct target_if_spectral_stats {
@@ -1087,7 +1087,7 @@ struct per_session_dest_det_info {
  * @dest_det_info: Struct containing per-session detector information
  * @num_dest_det_info: Number of destination detectors to which information
  * of this detector is to be filled
- * @spectral_msg_buf_type: Spectral message buffer type
+ * @buf_type: Spectral message buffer type
  * @send_to_upper_layers: Indicates whether to send SAMP msg to upper layers
  * @det_map_valid: Indicates whether detector map is valid or not
  */
@@ -1146,6 +1146,15 @@ struct sscan_detector_list {
 
 /**
  * struct spectral_supported_bws - Supported sscan bandwidths
+ * @supports_sscan_bw_5: 5 MHz bandwidth supported
+ * @supports_sscan_bw_10: 10 MHz bandwidth supported
+ * @supports_sscan_bw_20: 20 MHz bandwidth supported
+ * @supports_sscan_bw_40: 40 MHz bandwidth supported
+ * @supports_sscan_bw_80: 80 MHz bandwidth supported
+ * @supports_sscan_bw_160: 160 MHz bandwidth supported
+ * @supports_sscan_bw_80_80: 80+80 MHz bandwidth supported
+ * @supports_sscan_bw_320: 320 MHz bandwidth supported
+ * @reserved: reserved for future use
  * @bandwidths: bitmap of supported sscan bandwidths. Make sure to maintain this
  * bitmap in the increasing order of bandwidths.
  */
@@ -1177,7 +1186,7 @@ int get_supported_sscan_bw_pos(enum phy_ch_width sscan_bw);
 
 /**
  * struct target_if_spectral - main spectral structure
- * @pdev: Pointer to pdev
+ * @pdev_obj: Pointer to pdev
  * @spectral_ops: Target if internal Spectral low level operations table
  * @capability: Spectral capabilities structure
  * @properties: Spectral parameter properties per mode
@@ -1212,7 +1221,11 @@ int get_supported_sscan_bw_pos(enum phy_ch_width sscan_bw);
  * @spectral_dc_index: At which index DC is present
  * @send_single_packet: Deprecated
  * @spectral_sent_msg: Indicates whether we send report to upper layers
+ * @classify_scan:
+ * @classify_timer:
  * @params: Spectral parameters
+ * @params_valid:
+ * @classifier_params:
  * @last_capture_time: Indicates timestamp of previous report
  * @num_spectral_data: Number of Spectral samples received in current session
  * @total_spectral_data: Total number of Spectral samples received
@@ -1234,7 +1247,6 @@ int get_supported_sscan_bw_pos(enum phy_ch_width sscan_bw);
  * @noise_pwr_reports_lock: Lock used for Noise power report processing
  * @noise_pwr_chain_ctl: Noise power report - control channel
  * @noise_pwr_chain_ext: Noise power report - extension channel
- * @chaninfo: Channel statistics
  * @tsf64: Latest TSF Value
  * @param_info: Offload architecture Spectral parameter cache information
  * @ch_width: Indicates Channel Width 20/40/80/160 MHz for each Spectral mode
@@ -1263,6 +1275,7 @@ int get_supported_sscan_bw_pos(enum phy_ch_width sscan_bw);
  * @send_phy_data: Send data to the application layer for a particular msg type
  * @len_adj_swar: Spectral fft bin length adjustment SWAR related info
  * @timestamp_war: Spectral time stamp WAR related info
+ * @state_160mhz_delivery: Delivery state for each spectral scan mode
  * @dbr_ring_debug: Whether Spectral DBR ring debug is enabled
  * @dbr_buff_debug: Whether Spectral DBR buffer debug is enabled
  * @direct_dma_support: Whether Direct-DMA is supported on the current radio
@@ -1447,6 +1460,8 @@ struct target_if_psoc_spectral {
  * @max_mag: maximum magnitude
  * @max_index: index of max magnitude
  * @noise_floor: current noise floor
+ * @agc_total_gain: AGC total gain on primary channel
+ * @gainchange: Indicates a gainchange occurred during the spectral scan
  * @pri80ind: Indication from hardware that the sample was received on the
  *            primary 80 MHz segment. If this is set when smode =
  *            SPECTRAL_SCAN_MODE_AGILE, it indicates that Spectral was carried
@@ -1488,8 +1503,8 @@ struct target_if_samp_msg_params {
  * @chain_ctl_rssi: RSSI for control channel, for all antennas
  * @chain_ext_rssi: RSSI for extension channel, for all antennas
  * @bwinfo:  bandwidth info
- * @data_len:  length of FFT data (except for secondary 80 segment)
- * @data_len_sec80:  length of FFT data for secondary 80 segment
+ * @datalen:  length of FFT data (except for secondary 80 segment)
+ * @datalen_sec80:  length of FFT data for secondary 80 segment
  * @tstamp:  timestamp
  * @last_tstamp:  last time stamp
  * @max_mag:  maximum magnitude (except for secondary 80 segment)
@@ -1526,6 +1541,12 @@ struct target_if_samp_msg_params {
  * @interf_list: List of interference sources
  * @classifier_params:  classifier parameters
  * @sc:  classifier parameters
+ * @agc_total_gain: AGC total gain on primary channel
+ * @agc_total_gain_sec80: AGC total gain on secondary channel
+ * @gainchange: Indicates a gainchange occurred during the spectral scan
+ * @gainchange_sec80: Indicates a gainchange occurred in the secondary
+ * channel during the spectral scan
+ * @smode: spectral scan mode
  * @pri80ind: Indication from hardware that the sample was received on the
  * primary 80 MHz segment. If this is set when smode =
  * SPECTRAL_SCAN_MODE_AGILE, it indicates that Spectral was carried out on
@@ -1685,17 +1706,16 @@ QDF_STATUS target_if_spectral_fill_samp_msg(
 #endif
 
 /**
- * target_if_spectral_process_phyerr_gen3() - Process phyerror event for gen3
+ * target_if_spectral_process_report_gen3() - Process spectral report for gen3
  * @pdev:    Pointer to pdev object
- * @payload: Pointer to spectral report
+ * @buf: Pointer to spectral report
  *
  * Process phyerror event for gen3
  *
  * Return: Success/Failure
  */
-int target_if_spectral_process_report_gen3(
-	struct wlan_objmgr_pdev *pdev,
-	void *buf);
+int target_if_spectral_process_report_gen3(struct wlan_objmgr_pdev *pdev,
+					   void *buf);
 
 /**
  * target_if_process_phyerr_gen2() - Process PHY Error for gen2
@@ -1822,7 +1842,7 @@ int target_if_spectral_dump_phyerr_data_gen2(
 
 /**
  * target_if_dbg_print_samp_msg() - Print contents of SAMP Message
- * @p: Pointer to SAMP message
+ * @pmsg: Pointer to SAMP message
  *
  * Print contents of SAMP Message
  *
@@ -1874,13 +1894,12 @@ struct target_if_psoc_spectral *get_target_if_spectral_handle_from_psoc(
 }
 
 /**
- * target_if_vdev_get_chan_freq() - Get the operating channel frequency of a
- * given vdev
- * @pdev: Pointer to vdev
+ * target_if_vdev_get_chan_freq() - Get vdev operating channel frequency
+ * @vdev: Pointer to vdev
  *
  * Get the operating channel frequency of a given vdev
  *
- * Return: Operating channel frequency of a vdev
+ * Return: Operating channel frequency of a vdev in MHz
  */
 static inline
 int16_t target_if_vdev_get_chan_freq(struct wlan_objmgr_vdev *vdev)
@@ -1934,9 +1953,8 @@ int16_t target_if_vdev_get_chan_freq_seg2(struct wlan_objmgr_vdev *vdev)
 }
 
 /**
- * target_if_vdev_get_ch_width() - Get the operating channel bandwidth of a
- * given vdev
- * @pdev: Pointer to vdev
+ * target_if_vdev_get_ch_width() - Get vdev operating channel bandwidth
+ * @vdev: Pointer to vdev
  *
  * Get the operating channel bandwidth of a given vdev
  *
@@ -1983,11 +2001,12 @@ enum phy_ch_width target_if_vdev_get_ch_width(struct wlan_objmgr_vdev *vdev)
 /**
  * target_if_vdev_get_sec20chan_freq_mhz() - Get the frequency of secondary
  * 20 MHz channel for a given vdev
- * @pdev: Pointer to vdev
+ * @vdev: Pointer to vdev
+ * @sec20chan_freq: Location to return secondary 20 MHz channel
  *
- * Get the frequency of secondary 20Mhz channel for a given vdev
+ * Get the frequency of secondary 20 MHz channel for a given vdev
  *
- * Return: Frequency of secondary 20Mhz channel for a given vdev
+ * Return: 0 if 20 MHz channel was returned, negative errno otherwise
  */
 static inline
 int target_if_vdev_get_sec20chan_freq_mhz(
@@ -2139,7 +2158,7 @@ void target_if_spectral_set_rxchainmask(struct wlan_objmgr_pdev *pdev,
  * @datalen: Length of data
  * @p_rfqual: Pointer to RF Quality information
  * @p_chaninfo: Pointer to channel information
- * @tsf: TSF time instance at which the Spectral sample was received
+ * @tsf64: TSF time instance at which the Spectral sample was received
  * @acs_stats: ACS stats
  *
  * Process Spectral PHY error by extracting necessary information from the data
@@ -2257,6 +2276,7 @@ init_160mhz_delivery_state_machine(struct target_if_spectral *spectral)
 /**
  * reset_160mhz_delivery_state_machine() - Reset 160MHz Spectral state machine
  * @spectral: Pointer to Spectral
+ * @smode: Spectral scan mode
  *
  * Reset 160MHz Spectral state machine
  *
@@ -2857,7 +2877,7 @@ void target_if_spectral_set_start_end_freq(uint32_t cfreq,
 
 #ifdef DIRECT_BUF_RX_ENABLE
 /**
- * target_if_consume_sfft_report_gen3() -  Process fft report for gen3
+ * target_if_consume_spectral_report_gen3() -  Process fft report for gen3
  * @spectral: Pointer to spectral object
  * @report: Pointer to spectral report
  *
@@ -2899,6 +2919,7 @@ target_if_spectral_finite_scan_update(struct target_if_spectral *spectral,
  * target_if_spectral_is_finite_scan() - Check Spectral scan is finite/infinite
  * @spectral: Pointer to Spectral target_if internal private data
  * @smode: Spectral scan mode
+ * @finite_spectral_scan: location to store result
  *
  * API to check whether Spectral scan is finite/infinite for the give mode.
  * A non zero scan count indicates that scan is finite. Scan count of 0

target_if/spectral/target_if_spectral_sim.c

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2015,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
  * any purpose with or without fee is hereby granted, provided that the
@@ -452,7 +452,7 @@ target_if_populate_reportset_static(
 /**
  * target_if_depopulate_reportset() - Free all the instances of
  * struct spectralsim_reportset
- * @report: head pointer to struct spectralsim_reportset linked list
+ * @reportset: head pointer to struct spectralsim_reportset linked list
  *
  * Free all the instances of struct spectralsim_reportset
  *
@@ -554,10 +554,12 @@ target_if_depopulate_simdata(
 	SPECTRAL_SIM_REPORTSET_DEPOPLFREE_LIST(simctx->bw80_80_headreportset);
 }
 
-/**
+/*
  * target_if_spectral_sim_phyerrdelivery_handler() - Phyerr delivery handler
  *
  * Return: none
+ *
+ * NB: kernel-doc script doesn't parse OS_TIMER_FUNC
  */
 static
 OS_TIMER_FUNC(target_if_spectral_sim_phyerrdelivery_handler)

target_if/spectral/target_if_spectral_sim.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2015,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
  * any purpose with or without fee is hereby granted, provided that the
@@ -26,7 +26,7 @@
 /**
  * target_if_spectral_sim_attach() - Initialize Spectral Simulation
  * functionality
- * @spectral - pointer to spectral internal data structure
+ * @spectral: pointer to spectral internal data structure
  *
  * Setup data structures to be used for serving out data corresponding to
  * various bandwidths and configurations.
@@ -38,7 +38,7 @@ int target_if_spectral_sim_attach(struct target_if_spectral *spectral);
 /**
  * target_if_spectral_sim_detach() - De-initialize Spectral Simulation
  * functionality
- * @spectral - pointer to spectral internal data structure
+ * @spectral: pointer to spectral internal data structure
  *
  * Free up data structures used for serving out data corresponding to various
  * bandwidths and configurations.
@@ -50,7 +50,7 @@ void target_if_spectral_sim_detach(struct target_if_spectral *spectral);
 /**
  * target_if_spectral_sops_sim_is_active() - Check if Spectral(simulated) is
  * active
- * @arg - pointer to spectral internal data structure
+ * @arg: pointer to spectral internal data structure
  *
  * Check if Spectral (simulated) is active
  *
@@ -61,7 +61,7 @@ uint32_t target_if_spectral_sops_sim_is_active(void *arg);
 /**
  * target_if_spectral_sops_sim_is_enabled() - Check if Spectral(simulated) is
  * enabled
- * @arg - pointer to spectral internal data structure
+ * @arg: pointer to spectral internal data structure
  *
  * Check if Spectral(simulated) is enabled
  *
@@ -71,7 +71,7 @@ uint32_t target_if_spectral_sops_sim_is_enabled(void *arg);
 
 /**
  * target_if_spectral_sops_sim_start_scan() - Start Spectral simulation
- * @arg - pointer to spectral internal data structure
+ * @arg: pointer to spectral internal data structure
  *
  * Start Spectral simulation
  *
@@ -81,7 +81,7 @@ uint32_t target_if_spectral_sops_sim_start_scan(void *arg);
 
 /**
  * target_if_spectral_sops_sim_stop_scan() - Stop Spectral simulation
- * @arg - pointer to spectral internal data structure
+ * @arg: pointer to spectral internal data structure
  *
  * Stop Spectral simulation
  *
@@ -111,8 +111,8 @@ uint32_t target_if_spectral_sops_sim_configure_params(
 /**
  * target_if_spectral_sops_sim_get_params() - Get Spectral parameters configured
  * into simulation
- * arg - pointer to ath_spectral structure
- * params - pointer to struct spectral_config structure which should be
+ * @arg: pointer to ath_spectral structure
+ * @params: pointer to struct spectral_config structure which should be
  *          populated with Spectral configuration
  *
  * Get Spectral parameters configured into simulation