qcacmn: Fix umac/wifi_pos documentation

The kernel-doc script identified some documentation issues in the
umac/wifi_pos folder, so fix them.

Change-Id: I261ecd11e8e15bac021214c2d9e0774f316d7ac7
CRs-Fixed: 3430355

umac/wifi_pos/inc/wifi_pos_api.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2012-2020 The Linux Foundation. All rights reserved.
- * Copyright (c) 2021-2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021-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
@@ -119,10 +119,10 @@ struct wifi_pos_ch_info {
 };
 
 /**
- * typedef wifi_pos_ch_info_rsp - Channel information
+ * struct wifi_pos_ch_info_rsp - Channel information
  * @chan_id: channel id
  * @reserved0: reserved for padding and future use
- * @mhz: primary 20 MHz channel frequency in mhz
+ * @mhz: primary 20 MHz channel frequency in Mhz
  * @band_center_freq1: Center frequency 1 in MHz
  * @band_center_freq2: Center frequency 2 in MHz, valid only for 11ac
  *      VHT 80+80 mode
@@ -131,7 +131,7 @@ struct wifi_pos_ch_info {
  *      max power, reg power and reg class id
  * @reg_info_2: regulatory information field 2 which contains antennamax
  */
-struct qdf_packed wifi_pos_ch_info_rsp {
+struct wifi_pos_ch_info_rsp {
 	uint32_t chan_id;
 	uint32_t reserved0;
 	uint32_t mhz;
@@ -140,7 +140,7 @@ struct qdf_packed wifi_pos_ch_info_rsp {
 	uint32_t info;
 	uint32_t reg_info_1;
 	uint32_t reg_info_2;
-};
+} qdf_packed;
 
 /**
  * struct wifi_pos_peer_status_info - Status information for a given peer
@@ -151,14 +151,14 @@ struct qdf_packed wifi_pos_ch_info_rsp {
  * @reserved0: reserved0
  * @peer_chan_info: channel info on which peer is connected
  */
-struct qdf_packed wifi_pos_peer_status_info {
+struct wifi_pos_peer_status_info {
 	uint8_t peer_mac_addr[ETH_ALEN];
 	uint8_t peer_status;
 	uint8_t vdev_id;
 	uint32_t peer_capability;
 	uint32_t reserved0;
 	struct wifi_pos_ch_info_rsp peer_chan_info;
-};
+} qdf_packed;
 
 /**
  * struct wifi_pos_req_msg - wifi pos request struct

umac/wifi_pos/inc/wifi_pos_pasn_api.h

@@ -1,5 +1,5 @@
 /*
- * 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 above
@@ -29,7 +29,7 @@
 #if defined(WIFI_POS_CONVERGED) && defined(WLAN_FEATURE_RTT_11AZ_SUPPORT)
 /**
  * wifi_pos_set_peer_ltf_keyseed_required() - Set LTF keyseed required
- * for the peer
+ *                                            for the peer
  * @peer:  Peer object
  * @value: Value to set
  *
@@ -40,7 +40,7 @@ wifi_pos_set_peer_ltf_keyseed_required(struct wlan_objmgr_peer *peer,
 				       bool value);
 /**
  * wifi_pos_is_ltf_keyseed_required_for_peer() - Is LTF keyseed required for
- * the given peer
+ *                                               the given peer
  * @peer: Peer object
  *
  * Return: true or false
@@ -63,7 +63,7 @@ QDF_STATUS wifi_pos_handle_ranging_peer_create(struct wlan_objmgr_psoc *psoc,
 
 /**
  * wifi_pos_set_11az_failed_peers() - Update the 11az failed peers to the
- * context
+ *                                    context
  * @vdev: Objmgr vdev pointer
  * @mac_addr: mac address
  */
@@ -72,19 +72,19 @@ void wifi_pos_set_11az_failed_peers(struct wlan_objmgr_vdev *vdev,
 
 /**
  * wifi_pos_add_peer_to_list() - Add the peer mac to the secure/unsecure
- * peer list in the 11az context
+ *                               peer list in the 11az context
  * @vdev: Pointer to vdev object
  * @req: PASN peer create request pointer
  * @is_peer_create_required: True if we need to send peer create command to
- * firmware
+ *                           firmware
  */
 void wifi_pos_add_peer_to_list(struct wlan_objmgr_vdev *vdev,
 			       struct wlan_pasn_request *req,
 			       bool is_peer_create_required);
 
 /**
- * wifi_pos_handle_ranging_peer_create_rsp  - Ranging peer create response
- * handler
+ * wifi_pos_handle_ranging_peer_create_rsp() - Ranging peer create response
+ *                                             handler
  * @psoc: Pointer to PSOC object
  * @vdev_id: vdev id
  * @peer_mac: Peer mac address
@@ -101,8 +101,8 @@ wifi_pos_handle_ranging_peer_create_rsp(struct wlan_objmgr_psoc *psoc,
 /**
  * wifi_pos_handle_ranging_peer_delete() - Handle ranging PASN peer delete
  * @psoc: Pointer to PSOC object
+ * @req: PASN request
  * @vdev_id: vdev id
- * @peer_data: PASN peer data
  * @total_entries: Total number of peers
  *
  * Return: QDF_STATUS
@@ -114,9 +114,9 @@ wifi_pos_handle_ranging_peer_delete(struct wlan_objmgr_psoc *psoc,
 				    uint8_t total_entries);
 
 /**
- * wifi_pos_send_pasn_auth_status  - Send PASN auth status to firmware
+ * wifi_pos_send_pasn_auth_status() - Send PASN auth status to firmware
  * @psoc: Pointer to PSOC object
- * @data: pointer  to auth status data
+ * @data: pointer to auth status data
  *
  * Return: QDF_STATUS
  */
@@ -125,7 +125,7 @@ wifi_pos_send_pasn_auth_status(struct wlan_objmgr_psoc *psoc,
 			       struct wlan_pasn_auth_status *data);
 
 /**
- * wifi_pos_send_pasn_peer_deauth  - Send PASN peer deauth
+ * wifi_pos_send_pasn_peer_deauth() - Send PASN peer deauth
  * @psoc: Pointer to PSOC object
  * @peer_mac: Peer mac address
  *
@@ -155,8 +155,9 @@ void wifi_pos_update_pasn_peer_count(struct wlan_objmgr_vdev *vdev,
 				     bool is_increment);
 
 /**
- * wifi_pos_cleanup_pasn_peers  - Delete all PASN peer objects for
- * given vdev
+ * wifi_pos_cleanup_pasn_peers() - Delete all PASN peer objects for
+ *                                 given vdev
+ * @psoc: Pointer to psoc object
  * @vdev: Pointer to vdev object
  *
  * Return: QDF_STATUS
@@ -167,9 +168,8 @@ wifi_pos_cleanup_pasn_peers(struct wlan_objmgr_psoc *psoc,
 
 /**
  * wifi_pos_vdev_delete_all_ranging_peers() - Delete all ranging peers
- * associated with given vdev id
- * @psoc: Psoc pointer
- * @vdev_id: vdev id
+ *                                            associated with given vdev
+ * @vdev: Vdev object pointer
  *
  * Return: QDF_STATUS
  */
@@ -178,7 +178,7 @@ wifi_pos_vdev_delete_all_ranging_peers(struct wlan_objmgr_vdev *vdev);
 
 /**
  * wifi_pos_vdev_delete_all_ranging_peers_rsp() - Delete all vdev peers response
- * handler
+ *                                                handler
  * @psoc: Psoc pointer
  * @vdev_id: vdev id
  *
@@ -189,8 +189,9 @@ wifi_pos_vdev_delete_all_ranging_peers_rsp(struct wlan_objmgr_psoc *psoc,
 					   uint8_t vdev_id);
 
 /**
- * wifi_pos_is_delete_all_peer_in_progress() - Check if delete all
- * pasn peers command is already in progress for a given vdev
+ * wifi_pos_is_delete_all_peer_in_progress() - Check if delete all pasn peers
+ *                                             command is already in progress
+ *                                             for a given vdev
  * @vdev: Vdev object pointer
  *
  * Return: True if delete all pasn peer is in progress
@@ -199,7 +200,7 @@ bool wifi_pos_is_delete_all_peer_in_progress(struct wlan_objmgr_vdev *vdev);
 
 /**
  * wifi_pos_set_delete_all_peer_in_progress() - API to set/unset delete all
- * ranging peers is in progress
+ *                                              ranging peers is in progress
  * @vdev: Pointer to vdev object
  * @flag: value to indicate set or unset the flag
  *

umac/wifi_pos/inc/wifi_pos_utils_i.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2012-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2021-2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021-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
@@ -76,10 +76,10 @@ struct wifi_pos_req_msg;
  * @vdev_id: vdev id
  *
  */
-struct qdf_packed app_reg_rsp_vdev_info {
+struct app_reg_rsp_vdev_info {
 	uint8_t dev_mode;
 	uint8_t vdev_id;
-};
+} qdf_packed;
 
 /**
  * struct wifi_app_reg_rsp - app registration response struct
@@ -87,10 +87,10 @@ struct qdf_packed app_reg_rsp_vdev_info {
  * @vdevs: array indicating all active vdev's information
  *
  */
-struct qdf_packed wifi_app_reg_rsp {
+struct wifi_app_reg_rsp {
 	uint8_t num_inf;
 	struct app_reg_rsp_vdev_info vdevs[1];
-};
+} qdf_packed;
 
 /**
  * struct oem_data_req - data request to be sent to firmware
@@ -129,12 +129,12 @@ struct oem_data_rsp {
  * @dest_mac: Mac address of the sta in the request.
  * @reserved: Reserved in error report.
  */
-struct qdf_packed wifi_pos_err_rpt {
+struct wifi_pos_err_rpt {
 	uint32_t tag_len;
 	uint32_t info;
 	uint8_t  dest_mac[QDF_MAC_ADDR_SIZE + 2];
 	uint32_t reserved;
-};
+} qdf_packed;
 
 #define OEM_MSG_RSP_HEAD_TAG_ID 33
 #define OEM_MEAS_RSP_HEAD_TAG_ID 41
@@ -148,7 +148,7 @@ struct qdf_packed wifi_pos_err_rpt {
  * @time_left: time left in the measurement req.
  * @err_rpt: Error report data.
  */
-struct qdf_packed wifi_pos_err_msg_report {
+struct wifi_pos_err_msg_report {
 	uint32_t msg_tag_len;
 	uint32_t msg_subtype;
 	uint32_t req_id;
@@ -156,7 +156,7 @@ struct qdf_packed wifi_pos_err_msg_report {
 	uint32_t pdev_id;
 	uint32_t time_left;
 	struct wifi_pos_err_rpt err_rpt;
-};
+} qdf_packed;
 
 /**
  * struct wifi_pos_dma_rings_cap - capabilities requested by firmware.
@@ -191,6 +191,7 @@ struct wifi_pos_dma_buf_info {
  * struct wifi_pos_dma_rings_cfg - DMA ring parameters to be programmed to FW.
  * @pdev_id: pdev_id of ring
  * @num_ptr: depth of ring
+ * @ring_alloc_size: size of the ring allocation
  * @base_paddr_unaligned: base physical addr unaligned
  * @base_vaddr_unaligned: base virtual addr unaligned
  * @base_paddr_aligned: base physical addr aligned
@@ -386,7 +387,7 @@ void wifi_pos_set_psoc(struct wlan_objmgr_psoc *psoc);
 struct wlan_objmgr_psoc *wifi_pos_get_psoc(void);
 
 /**
- * wifi_pos_get_psoc: API to clear global PSOC object
+ * wifi_pos_clear_psoc: API to clear global PSOC object
  *
  * Return: none.
  */

umac/wifi_pos/inc/wifi_pos_utils_pub.h

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2020-2021, 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 above
@@ -38,12 +39,17 @@
 #define WIFI_POS_RSP_V2_NL  0x00000002
 
 /**
- * enum wifi_pos_cmd_ids
+ * enum wifi_pos_cmd_ids - Wi-Fi Positioning command IDs
+ * @WIFI_POS_CMD_INVALID: invalid command
  * @WIFI_POS_CMD_REGISTRATION: app registration
+ * @WIFI_POS_CMD_SET_CAPS: set userspace capabilities
  * @WIFI_POS_CMD_GET_CAPS: get driver capabilities
  * @WIFI_POS_CMD_GET_CH_INFO: get channel info
  * @WIFI_POS_CMD_OEM_DATA: oem data req/rsp
- * @WIFI_POS_CMD_MAX: Max cld80211 vendor sub cmds
+ * @WIFI_POS_CMD_ERROR: error notification
+ * @WIFI_POS_PEER_STATUS_IND: peer status indication
+ * @WIFI_POS_CMD__AFTER_LAST: internal use
+ * @WIFI_POS_CMD_MAX: Max Wi-Fi Positioning command ID
  */
 
 enum wifi_pos_cmd_ids {
@@ -69,15 +75,15 @@ enum wifi_pos_cmd_ids {
  * @patch: Version ID patch number
  * @build: Version ID build number
  */
-struct qdf_packed wifi_pos_driver_version {
+struct wifi_pos_driver_version {
 	uint8_t major;
 	uint8_t minor;
 	uint8_t patch;
 	uint8_t build;
-};
+} qdf_packed;
 
 /**
- * struct wifi_pos_channel_power
+ * struct wifi_pos_channel_power - Wi-Fi Positioning channel/power info
  * @ch_power: channel_power structure object
  * @band_center_freq1: Center frequency1
  * @phy_mode: Phymode
@@ -91,14 +97,14 @@ struct wifi_pos_channel_power {
 };
 
 /**
- * struct wifi_pos_channel_list
- * @valid_channels: no of valid channels
+ * struct wifi_pos_channel_list - Wi-Fi Positioning channel list
+ * @num_channels: no of valid channels
  * @chan_info: channel info
  */
-struct qdf_packed wifi_pos_channel_list {
+struct wifi_pos_channel_list {
 	uint16_t num_channels;
 	struct wifi_pos_channel_power chan_info[NUM_CHANNELS];
-};
+} qdf_packed;
 
 /**
  * struct wifi_pos_driver_caps - OEM Data Capabilities
@@ -110,11 +116,11 @@ struct qdf_packed wifi_pos_channel_list {
  * @allowed_dwell_time_max: Channel dwell time - allowed maximum
  * @curr_dwell_time_min: Channel dwell time - current minimim
  * @curr_dwell_time_max: Channel dwell time - current maximum
- * @supported_bands: Supported bands, 2.4G or 5G Hz
+ * @supported_bands: Supported bands, 2.4 GHz or 5 GHz
  * @num_channels: Num of channels IDs to follow
  * @channel_list: List of channel IDs
  */
-struct qdf_packed wifi_pos_driver_caps {
+struct wifi_pos_driver_caps {
 	uint8_t oem_target_signature[OEM_TARGET_SIGNATURE_LEN];
 	uint32_t oem_target_type;
 	uint32_t oem_fw_version;
@@ -126,11 +132,11 @@ struct qdf_packed wifi_pos_driver_caps {
 	uint16_t supported_bands;
 	uint16_t num_channels;
 	uint8_t channel_list[OEM_CAP_MAX_NUM_CHANNELS];
-};
+} qdf_packed;
 
 /**
  * struct wifi_pos_user_defined_caps - OEM capability to be exchanged between
- * host and userspace
+ *                                     host and userspace
  * @ftm_rr: FTM range report capability bit
  * @lci_capability: LCI capability bit
  * @reserved1: reserved
@@ -148,8 +154,8 @@ struct wifi_pos_user_defined_caps {
  * @driver_cap: target capabilities
  * @user_defined_cap: capabilities set by userspace via set request
  */
-struct qdf_packed wifi_pos_oem_get_cap_rsp {
+struct wifi_pos_oem_get_cap_rsp {
 	struct wifi_pos_driver_caps driver_cap;
 	struct wifi_pos_user_defined_caps user_defined_cap;
-};
+} qdf_packed;
 #endif

umac/wifi_pos/src/wifi_pos_main.c

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2012-2021 The Linux Foundation. All rights reserved.
- * Copyright (c) 2021-2022 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021-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
@@ -74,7 +74,7 @@ struct regulatory_channel;
 static uint32_t vdev_idx;
 
 /**
- * wifi_pos_get_tlv_support: indicates if firmware supports TLV wifi pos msg
+ * wifi_pos_get_tlv_support() - indicates if firmware supports TLV wifi pos msg
  * @psoc: psoc object
  *
  * Return: status of operation
@@ -117,7 +117,7 @@ wifi_pos_prepare_reg_resp(uint32_t *rsp_len,
 }
 
 /**
- * wifi_pos_get_host_pdev_id: Get host pdev_id
+ * wifi_pos_get_host_pdev_id() - Get host pdev_id
  * @psoc: Pointer to psoc object
  * @tgt_pdev_id: target_pdev_id
  * @host_pdev_id: host pdev_id
@@ -456,8 +456,8 @@ static void wifi_update_channel_bw_info(struct wlan_objmgr_psoc *psoc,
 }
 
 /**
- * wifi_pos_get_valid_channels: Get the list of valid channels from the
- * given channel list
+ * wifi_pos_get_valid_channels() - Get the list of valid channels from the
+ *                                 given channel list
  * @chan_freqs: Channel frequencies to be validated
  * @num_ch: NUmber of channels in the channel list to be validated
  * @valid_channel_list: Pointer to valid channel list
@@ -887,8 +887,9 @@ app_reg_failed:
 }
 
 /**
- * wifi_pos_tlv_callback: wifi pos msg handler registered for TLV type req
- * @wmi_msg: wmi type request msg
+ * wifi_pos_tlv_callback() - wifi pos msg handler registered for TLV type req
+ * @psoc: psoc object
+ * @req: wifi positioning request msg
  *
  * Return: status of operation
  */
@@ -915,9 +916,10 @@ static QDF_STATUS wifi_pos_tlv_callback(struct wlan_objmgr_psoc *psoc,
 }
 
 /**
- * wifi_pos_non_tlv_callback: wifi pos msg handler registered for non-TLV
- * type req
- * @wmi_msg: wmi type request msg
+ * wifi_pos_non_tlv_callback() - wifi pos msg handler registered for non-TLV
+ *                               type req
+ * @psoc: psoc object
+ * @req: wifi positioning request msg
  *
  * Return: status of operation
  */

umac/wifi_pos/src/wifi_pos_ucfg.c

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2017-2018, 2020 The Linux Foundation. All rights reserved.
- * Copyright (c) 2021 Qualcomm Innovation Center, Inc. All rights reserved.
+ * Copyright (c) 2021, 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
@@ -18,7 +18,7 @@
  */
 
 /**
- * This file defines the important dispatcher APIs pertinent to
+ * DOC: This file defines the important dispatcher APIs pertinent to
  * wifi positioning.
  */
 #include <wlan_lmac_if_def.h>