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
2023-02-25 13:03:24 -08:00
commit abbb3f3b9d
--- a/target_if/spectral/target_if_spectral.c
+++ b/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.
 *
--- a/target_if/spectral/target_if_spectral.h
+++ b/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
--- a/target_if/spectral/target_if_spectral_sim.c
+++ b/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)
--- a/target_if/spectral/target_if_spectral_sim.h
+++ b/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