qcacmn: Fix umac/mlo_mgr documentation

The kernel-doc script identified some documentation issues in
umac/mlo_mgr, so fix most of them. However some issues are due to
kernel-doc being unable to parse the qdf_bitmap() macro, so disable
kernel-doc in those cases.

Change-Id: I1c32ffae58aedbbafa2ab4c9e4faa33c426ea7b5
CRs-Fixed: 3380021

umac/mlo_mgr/inc/wlan_mlo_mgr_ap.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 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 above
@@ -435,13 +435,13 @@ uint16_t wlan_mlme_get_aid_count(struct wlan_objmgr_vdev *vdev);
  * This function allocates MLO peer ID
  *
  * Return: mlo_peer_id on success,
-	 MLO_INVALID_PEER_ID on failure
+ *	 MLO_INVALID_PEER_ID on failure
  */
 uint16_t mlo_ap_ml_peerid_alloc(void);
 
 /**
  * mlo_ap_ml_peerid_free() - public API to free MLO peer id
- * @ml_peer_id: ML peer id
+ * @mlo_peer_id: ML peer id
  *
  * This function frees MLO peer ID
  *
@@ -467,7 +467,7 @@ void mlo_peer_assign_primary_umac(
  * mlo_peer_allocate_primary_umac() - Allocate Primary UMAC
  * @ml_dev: MLO DEV context
  * @ml_peer: MLO peer object
- * @link_vdev: link vdev array
+ * @link_vdevs: link vdev array
  *
  * This function allocates primary UMAC for a MLO peer
  *

umac/mlo_mgr/inc/wlan_mlo_mgr_cmn.h

@@ -175,7 +175,7 @@ QDF_STATUS mlo_mlme_validate_conn_req(struct wlan_objmgr_vdev *vdev,
 				      void *ext_data);
 
 /**
- * mlo_mlme_ext_create_link_vdev() - Create link vdev for ML STA
+ * mlo_mlme_create_link_vdev() - Create link vdev for ML STA
  * @vdev: Object manager vdev
  * @ext_data: Data object to be passed to callback
  *
@@ -252,7 +252,7 @@ void mlo_mlme_peer_deauth(struct wlan_objmgr_peer *peer, uint8_t is_disassoc);
 #ifdef UMAC_MLO_AUTH_DEFER
 /**
  * mlo_mlme_peer_process_auth() - Process deferred auth request
- * @auth_params: deferred auth params
+ * @auth_param: deferred auth params
  *
  * Return: void
  */
@@ -266,7 +266,7 @@ mlo_mlme_peer_process_auth(struct mlpeer_auth_params *auth_param)
 
 /**
  * mlo_get_link_vdev_ix() - Get index of link VDEV in MLD
- * @ml_dev: ML device context
+ * @mldev: ML device context
  * @vdev: VDEV object
  *
  * Return: link index
@@ -371,7 +371,7 @@ struct hw_link_id_iterator {
 };
 
 /**
- * wlan_objmgr_get_pdev_by_hw_link_id() - Get pdev object from hw_link_id
+ * wlan_mlo_get_pdev_by_hw_link_id() - Get pdev object from hw_link_id
  * @hw_link_id: HW link id of the pdev
  * @ml_grp_id: MLO Group id which it belongs to
  * @refdbgid: dbgid of module used for taking reference to pdev object
@@ -449,8 +449,10 @@ mlo_process_link_set_active_resp(struct wlan_objmgr_psoc *psoc,
  */
 QDF_STATUS mlo_ser_set_link_req(struct mlo_link_set_active_req *req);
 
-/*
- * API to have operation on ml vdevs
+/**
+ * typedef mlo_vdev_ops_handler() - API to have operation on ml vdevs
+ * @vdev: vdev object
+ * @arg: operation-specific argument
  */
 typedef void (*mlo_vdev_ops_handler)(struct wlan_objmgr_vdev *vdev,
 				     void *arg);

umac/mlo_mgr/inc/wlan_mlo_mgr_peer.h

@@ -84,7 +84,7 @@ void mlo_peer_setup_failed_notify(struct wlan_objmgr_vdev *vdev);
  * mlo_peer_disconnect_notify - Notify MLO manager that peer has disconnected
  * and to clean up by deleting partner peers
  *
- * @vdev: pointer to vdev
+ * @peer: pointer to peer context
  *
  * Return: none
  */
@@ -184,7 +184,7 @@ bool wlan_mlo_peer_is_assoc_peer(struct wlan_mlo_peer_context *ml_peer,
 
 /**
  * wlan_mlo_partner_peer_assoc_post() - Notify partner peer assoc
- * @peer: Link peer
+ * @assoc_peer: Link peer
  *
  * This function notifies link peers to send peer assoc command to FW
  *
@@ -220,7 +220,7 @@ void wlan_mlo_partner_peer_create_failed_notify(
 
 /**
  * wlan_mlo_partner_peer_disconnect_notify() - Notify peer disconnect
- * @peer: Link peer
+ * @src_peer: Link peer
  *
  * This function notifies about disconnect is being initilated on link peer
  *
@@ -314,7 +314,7 @@ QDF_STATUS wlan_mlo_link_peer_delete(struct wlan_objmgr_peer *peer);
 
 /**
  * mlo_peer_get_link_peer_assoc_req_buf() - API to get link assoc req buffer
- * @peer: Object manager peer
+ * @ml_peer: Object manager peer
  * @link_ix: link id of vdev
  *
  * Return: assoc req buffer
@@ -384,8 +384,8 @@ uint8_t wlan_mlo_peer_get_primary_peer_link_id(struct wlan_objmgr_peer *peer);
 void wlan_mlo_peer_get_partner_links_info(struct wlan_objmgr_peer *peer,
 					  struct mlo_partner_info *ml_links);
 
-/**
- ** APIs to operations on ML peer object
+/*
+ * APIs to operations on ML peer object
  */
 typedef QDF_STATUS (*wlan_mlo_op_handler)(struct wlan_mlo_dev_context *ml_dev,
 				    void *ml_peer,
@@ -437,7 +437,7 @@ struct wlan_mlo_peer_context *wlan_mlo_get_mlpeer_by_mld_mac(
 /**
  * wlan_mlo_get_mlpeer_by_aid() - find ML peer by AID
  * @ml_dev: MLO DEV object
- * @aid:  AID
+ * @assoc_id:  AID
  *
  * API to get ML peer using AID
  *

umac/mlo_mgr/inc/wlan_mlo_mgr_public_structs.h

@@ -76,7 +76,7 @@ struct wlan_t2lm_context;
 #endif
 
 /**
- * enum MLO_LINK_STATE – MLO link state enums
+ * enum MLO_LINK_STATE - MLO link state enums
  * @MLO_LINK_SETUP_INIT: MLO link SETUP exchange not yet done
  * @MLO_LINK_SETUP_DONE: MLO link SETUP exchange started
  * @MLO_LINK_READY: MLO link SETUP done and READY sent
@@ -92,7 +92,7 @@ enum MLO_LINK_STATE {
 };
 
 /**
- * enum MLO_SOC_LIST – MLO SOC LIST
+ * enum MLO_SOC_LIST - MLO SOC LIST
  * @WLAN_MLO_GROUP_DEFAULT_SOC_LIST:  All MLO SoCs that are part of this MLO
  *                                    group, (inclusive of both setup sequence
  *                                    completed, not yet completed)
@@ -104,6 +104,14 @@ enum MLO_SOC_LIST {
 	WLAN_MLO_GROUP_CURRENT_SOC_LIST,
 };
 
+/*
+ * Maximum number of MLO LINKS across the system,
+ * this is not the MLO links within and AP-MLD.
+ */
+
+#define MAX_MLO_LINKS 7
+#define MAX_MLO_CHIPS 5
+
 /**
  * struct mlo_setup_info: MLO setup status per link
  * @ml_grp_id: Unique id for ML grouping of Pdevs/links
@@ -112,23 +120,15 @@ enum MLO_SOC_LIST {
  * @tot_links: Total links in ML group
  * @num_links: Number of links probed in ML group
  * @pdev_list: current pdev pointers belonging to this group
- * @soc_list: current psoc pointers belonging to this group
+ * @curr_soc_list: current psoc pointers belonging to this group
  * @soc_list: Actual psoc pointers part of this group
  * @soc_id_list: list of soc ids part of this mlo group
- * @state[MAX_MLO_LINKS]: MLO link state
+ * @state: MLO link state
  * @valid_link_bitmap: valid MLO link bitmap
  * @state_lock: lock to protect access to link state
- * @qdf_event_t: event for teardown completion
+ * @event: event for teardown completion
  * @dp_handle: pointer to DP ML context
  */
-
-/*
- * Maximum number of MLO LINKS across the system,
- * this is not the MLO links within and AP-MLD.
- */
-
-#define MAX_MLO_LINKS 7
-#define MAX_MLO_CHIPS 5
 struct mlo_setup_info {
 	uint8_t ml_grp_id;
 	uint8_t tot_socs;
@@ -160,20 +160,24 @@ struct mlo_state_params {
 
 #endif
 
-/**
+/*
  * struct mlo_mgr_context - MLO manager context
  * @ml_dev_list_lock: ML DEV list lock
  * @aid_lock: AID global lock
  * @ml_peerid_lock: ML peer ID global lock
- * @context: Array of MLO device context
+ * @ml_dev_list: Array of MLO device context
  * @mlo_peer_id_bmap: bitmap to allocate MLO Peer ID
  * @max_mlo_peer_id: Max MLO Peer ID
  * @last_mlo_peer_id: Previously allocated ML peer ID
- * @setup_info: MLO setup_info of all groups
+ * @setup_info: Pointer to MLO setup_info of all groups
+ * @total_grp: Total number of MLO groups
  * @mlme_ops: MLO MLME callback function pointers
  * @msgq_ctx: Context switch mgr
  * @mlo_is_force_primary_umac: Force Primary UMAC enable
  * @mlo_forced_primary_umac_id: Force Primary UMAC ID
+ *
+ * NB: not using kernel-doc format since the kernel-doc script doesn't
+ *     handle the qdf_bitmap() macro
  */
 struct mlo_mgr_context {
 #ifdef WLAN_MLO_USE_SPINLOCK
@@ -199,12 +203,15 @@ struct mlo_mgr_context {
 	uint8_t mlo_forced_primary_umac_id;
 };
 
-/**
- * struct wlan_ml_vdev_aid_mgr – ML AID manager
+/*
+ * struct wlan_ml_vdev_aid_mgr - ML AID manager
  * @aid_bitmap: AID bitmap array
  * @start_aid: start of AID index
  * @max_aid: Max allowed AID
- * @aid_mgr[]:  Array of link vdev aid mgr
+ * @aid_mgr:  Array of link vdev aid mgr
+ *
+ * NB: not using kernel-doc format since the kernel-doc script doesn't
+ *     handle the qdf_bitmap() macro
  */
 struct wlan_ml_vdev_aid_mgr {
 	qdf_bitmap(aid_bitmap, WLAN_UMAC_MAX_AID);
@@ -226,7 +233,7 @@ struct wlan_mlo_key_mgmt {
 };
 
 /**
- * struct mlo_sta_csa _params - CSA request parameters in mlo mgr
+ * struct mlo_sta_csa_params - CSA request parameters in mlo mgr
  * @csa_param: csa parameters
  * @link_id: the link index of AP which triggers CSA
  * @mlo_csa_synced: Before vdev is up, csa information is only saved but not
@@ -248,7 +255,7 @@ struct mlo_sta_csa_params {
 };
 
 /**
- * mlo_sta_cu_params - critical update parameters in mlo mgr
+ * struct mlo_sta_cu_params - critical update parameters in mlo mgr
  * @vdev_id: vdev id
  * @bpcc: bss parameter change count
  * @initialized: flag about the parameter is valid or not
@@ -271,20 +278,25 @@ struct mlo_sta_quiet_status {
 	bool valid_status;
 };
 
-/**
+/*
  * struct wlan_mlo_sta - MLO sta additional info
  * @wlan_connect_req_links: list of vdevs selected for connection with the MLAP
  * @wlan_connected_links: list of vdevs associated with this MLO connection
- * @connect req: connect params
+ * @key_mgmt:
+ * @connect_req: connect params
  * @copied_conn_req: original connect req
  * @copied_conn_req_lock: lock for the original connect request
  * @assoc_rsp: Raw assoc response frame
+ * @mlo_quiet_status:
  * @mlo_csa_param: CSA request parameters for mlo sta
  * @mlo_cu_param: critical update parameters for mlo sta
  * @disconn_req: disconnect req params
  * @copied_reassoc_rsp: Reassoc response copied from assoc link roam handling
  *                      to re-use while link connect in case of deferred/need
  *                      basis link connect (e.g. MLO OWE roaming).
+ *
+ * NB: not using kernel-doc format since the kernel-doc script doesn't
+ *     handle the qdf_bitmap() macro
  */
 struct wlan_mlo_sta {
 	qdf_bitmap(wlan_connect_req_links, WLAN_UMAC_MLO_MAX_VDEVS);
@@ -307,12 +319,15 @@ struct wlan_mlo_sta {
 #endif
 };
 
-/**
+/*
  * struct wlan_mlo_ap - MLO AP related info
  * @num_ml_vdevs: number of vdevs to form MLD
  * @ml_aid_mgr: ML AID mgr
  * @mlo_ap_lock: lock to sync VDEV SM event
  * @mlo_vdev_quiet_bmap: Bitmap of vdevs for which quiet ie needs to enabled
+ *
+ * NB: not using kernel-doc format since the kernel-doc script doesn't
+ *     handle the qdf_bitmap() macro
  */
 struct wlan_mlo_ap {
 	uint8_t num_ml_vdevs;
@@ -346,7 +361,7 @@ struct wlan_mlo_peer_list {
  * @mld_addr: MLO device MAC address
  * @wlan_vdev_list: list of vdevs associated with this MLO connection
  * @wlan_vdev_count: number of elements in the vdev list
- * @mlo_peer: list peers in this MLO connection
+ * @mlo_peer_list: list peers in this MLO connection
  * @wlan_max_mlo_peer_count: peer count across the links of specific MLO
  * @mlo_dev_lock: lock to access struct
  * @tsf_recalculation_lock: Lock to protect TSF (re)calculation
@@ -379,7 +394,7 @@ struct wlan_mlo_dev_context {
 };
 
 /**
- * struct wlan_mlo_link_peer_entry – Link peer entry
+ * struct wlan_mlo_link_peer_entry - Link peer entry
  * @link_peer: Object manager peer
  * @link_addr: MAC address of link peer
  * @link_ix: Link index
@@ -397,7 +412,7 @@ struct wlan_mlo_link_peer_entry {
 };
 
 /**
- * enum mlo_peer_state – MLO peer state
+ * enum mlo_peer_state - MLO peer state
  * @ML_PEER_CREATED:     Initial state
  * @ML_PEER_ASSOC_DONE:  ASSOC sent on assoc link
  * @ML_PEER_DISCONN_INITIATED: Disconnect initiated on one of the links
@@ -428,7 +443,7 @@ struct mlnawds_config {
  * @vdev_id:  VDEV ID
  * @psoc_id:  PSOC ID
  * @link_addr: MAC address
- * @mldmacaddr: MLD MAC address
+ * @mldaddr: MLD MAC address
  * @algo:  Auth algorithm
  * @seq: Auth sequence number
  * @status_code: Auth status
@@ -514,6 +529,7 @@ struct wlan_mlo_mld_cap {
  * @mlo_ie: MLO IE struct
  * @mlo_peer_lock: lock to access peer structure
  * @assoc_id: Assoc ID derived by MLO manager
+ * @primary_umac_psoc_id:
  * @ref_cnt: Reference counter to avoid use after free
  * @ml_dev: MLO dev context
  * @mlpeer_state: MLO peer state
@@ -567,7 +583,7 @@ struct wlan_mlo_peer_context {
 };
 
 /**
- * struct mlo_link_info – ML link info
+ * struct mlo_link_info - ML link info
  * @link_addr: link mac address
  * @link_id: link index
  * @chan_freq: Operating channel frequency
@@ -589,7 +605,7 @@ struct mlo_link_info {
 };
 
 /**
- * struct mlo_partner_info – mlo partner link info
+ * struct mlo_partner_info - mlo partner link info
  * @num_partner_links: no. of partner links
  * @partner_link_info: per partner link info
  * @t2lm_enable_val: enum wlan_t2lm_enable
@@ -603,8 +619,8 @@ struct mlo_partner_info {
 };
 
 /**
- * struct mlo_probereq_info – mlo probe req link info
- * mlid: MLID requested in the probe req
+ * struct mlo_probereq_info - mlo probe req link info
+ * @mlid: MLID requested in the probe req
  * @num_links: no. of link info in probe req
  * @link_id: target link id of APs
  * @is_mld_id_valid: Indicates if mld_id is valid for a given request
@@ -643,7 +659,7 @@ struct ml_rv_info {
 };
 
 /**
- * struct mlo_tgt_link_info – ML target link info
+ * struct mlo_tgt_link_info - ML target link info
  * @vdev_id: link peer vdev id
  * @hw_mld_link_id: HW link id
  */
@@ -653,7 +669,7 @@ struct mlo_tgt_link_info {
 };
 
 /**
- * struct mlo_tgt_partner_info – mlo target partner link info
+ * struct mlo_tgt_partner_info - mlo target partner link info
  * @num_partner_links: no. of partner links
  * @link_info: per partner link info
  */
@@ -676,6 +692,7 @@ struct mlo_tgt_partner_info {
  * @mlo_mlme_ext_clone_security_param: Callback to clone mlo security params
  * @mlo_mlme_ext_peer_process_auth: Callback to process pending auth
  * @mlo_mlme_ext_handle_sta_csa_param: Callback to handle sta csa param
+ * @mlo_mlme_ext_sta_op_class:
  */
 struct mlo_mlme_ext_ops {
 	QDF_STATUS (*mlo_mlme_ext_validate_conn_req)(
@@ -861,7 +878,7 @@ enum wlan_t2lm_status {
 /**
  * struct mlo_vdev_host_tid_to_link_map_resp - TID-to-link mapping response
  * @vdev_id: Vdev id
- * @wlan_t2lm_status: Target status for t2lm ie info
+ * @status: Target status for t2lm ie info
  * @mapping_switch_tsf: Mapping switch time in tsf for probe response frames
  */
 struct mlo_vdev_host_tid_to_link_map_resp {
@@ -905,7 +922,7 @@ struct mlo_link_removal_evt_params {
 	struct mlo_link_removal_tbtt_info tbtt_info;
 };
 
-/*
+/**
  * struct mgmt_rx_mlo_link_removal_info - Information, sent in MGMT Rx event, of
  * a link undergoing removal from its MLD
  * @vdev_id: Vdev ID of the link undergoing removal

umac/mlo_mgr/inc/wlan_mlo_mgr_setup.h

@@ -1,4 +1,4 @@
-/* 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 above
@@ -13,7 +13,7 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/*
+/**
  * DOC: contains MLO manager public file containing setup/teardown functionality
  */
 
@@ -61,7 +61,7 @@ void mlo_get_soc_list(struct wlan_objmgr_psoc **soc_list, uint8_t grp_id,
  * mlo_setup_update_soc_id_list() - API to update the list of SOCs ids
  *                                  participating in that MLO group
  * @grp_id: ID of the required mlo group
- * @soc_list: soc ids part of that MLO group
+ * @soc_id_list: soc ids part of that MLO group
  *
  * Return: None
  */
@@ -106,7 +106,7 @@ uint8_t mlo_setup_get_total_socs(uint8_t grp_id);
 
 /**
  * mlo_setup_update_num_links() - API to update num links in soc for mlo
- * @soc_id: soc object of SoC corresponding to num_link
+ * @psoc: soc object of SoC corresponding to num_link
  * @grp_id: ID of the required mlo group
  * @num_links: Number of links in that soc
  *

umac/mlo_mgr/inc/wlan_mlo_mgr_sta.h

@@ -41,7 +41,7 @@ QDF_STATUS mlo_connect(struct wlan_objmgr_vdev *vdev,
  * mlo_sta_link_connect_notify - Called by connection manager to notify the
  * STA link connect is complete
  * @vdev: pointer to vdev
- * @mlo_ie: MLO information element
+ * @rsp: MLO connect response
  *
  * Connection manager will notify the MLO manager when the link has started
  * and MLO manager will start the subsequent connections, if necessary
@@ -154,7 +154,7 @@ void ucfg_mlo_mld_clear_mlo_cap(struct wlan_objmgr_vdev *vdev);
 
 /**
  * ucfg_mlo_get_assoc_link_vdev - API to get assoc link vdev
- * @mlo_dev_ctx: mlo dev ctx
+ * @vdev: vdev object
  *
  * Return: MLD assoc link vdev
  */
@@ -163,7 +163,7 @@ ucfg_mlo_get_assoc_link_vdev(struct wlan_objmgr_vdev *vdev);
 
 /**
  * wlan_mlo_get_assoc_link_vdev - API to get assoc link vdev
- * @mlo_dev_ctx: mlo dev ctx
+ * @vdev: vdev object
  *
  * Return: MLD assoc link vdev
  */
@@ -179,10 +179,10 @@ wlan_mlo_get_assoc_link_vdev(struct wlan_objmgr_vdev *vdev);
  */
 void
 mlo_update_connected_links_bmap(struct wlan_mlo_dev_context *mlo_dev_ctx,
-				struct mlo_partner_info ml_parnter_info);
+				struct mlo_partner_info ml_partner_info);
 
 /**
- * mlo_clear_connected_links: clear connected links bitmap
+ * mlo_clear_connected_links_bmap() - clear connected links bitmap
  * @vdev: vdev object
  *
  * Return: none
@@ -230,7 +230,9 @@ void mlo_init_cu_bpcc(struct wlan_mlo_dev_context *mlo_dev_ctx,
 void mlo_clear_cu_bpcc(struct wlan_objmgr_vdev *vdev);
 
 /**
- * API to have operation on ml vdevs
+ * typedef mlo_vdev_op_handler() - API to have operation on ml vdevs
+ * @vdev: vdev object
+ * @arg: operation-specific argument
  */
 typedef void (*mlo_vdev_op_handler)(struct wlan_objmgr_vdev *vdev,
 				    void *arg);
@@ -273,7 +275,7 @@ void mlo_iterate_connected_vdev_list(struct wlan_objmgr_vdev *vdev,
  * call_handler_for_standalone_ap: Iterate on all standalone ML vdevs in
  * ML AP context and call handler only for standalone AP
  *
- * @vdev: vdev object
+ * @ap_dev_ctx: AP vdev context
  * @handler: the handler will be called for each object in ML list
  * @arg: argument to be passed to handler
  *
@@ -298,7 +300,7 @@ call_handler_for_standalone_ap(struct wlan_mlo_dev_context *ap_dev_ctx,
 	}
 }
 
-/*
+/**
  * mlo_iterate_ml_standalone_vdev_list: Iterate on all standalone ML vdevs in
  * ML link
  *
@@ -422,7 +424,7 @@ mlo_is_vdev_connect_req_link(struct wlan_objmgr_vdev *vdev)
 }
 
 /**
- * mlo_clear_connect_req_links: clear connect req links bitmap
+ * mlo_clear_connect_req_links_bmap() - clear connect req links bitmap
  * @vdev: vdev object
  *
  * Return: none