qcacmn: Fix dp/inc documentation

The kernel-doc script identified a large number of kernel-doc issues
in the dp/inc folder, so fix them.

Change-Id: I6213164d2209cc4de9684ae66281ee2999f82672
CRs-Fixed: 3375078

dp/inc/cdp_txrx_ctrl.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2016-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
@@ -18,8 +18,8 @@
  */
 
 /**
- * @file cdp_txrx_ctrl.h
- * @brief Define the host data path control API functions
+ * DOC: cdp_txrx_ctrl.h
+ * Define the host data path control API functions
  * called by the host control SW and the OS interface module
  */
 
@@ -67,16 +67,16 @@ cdp_mempools_attach(ol_txrx_soc_handle soc)
 
 #if defined(ATH_SUPPORT_NAC) || defined(ATH_SUPPORT_NAC_RSSI)
 /**
- * @brief update the neighbour peer addresses
- * @details
+ * cdp_update_filter_neighbour_peers() - update the neighbour peer addresses
+ * @soc: the pointer to soc object
+ * @vdev_id: id of the pointer to vdev
+ * @cmd: add/del entry into peer table
+ * @macaddr: the address of neighbour peer
+ *
  *  This defines interface function to update neighbour peers addresses
  *  which needs to be filtered
  *
- * @param soc - the pointer to soc object
- * @param vdev_id - id of the pointer to vdev
- * @param cmd - add/del entry into peer table
- * @param macaddr - the address of neighbour peer
- * @return - int
+ * Return: int
  */
 static inline int
 cdp_update_filter_neighbour_peers(ol_txrx_soc_handle soc,
@@ -98,15 +98,15 @@ cdp_update_filter_neighbour_peers(ol_txrx_soc_handle soc,
 #endif /* ATH_SUPPORT_NAC || ATH_SUPPORT_NAC_RSSI*/
 
 /**
- * @brief update the monitor buffer and status filter
- * @details
- *  This defines interface function to set/reset monitor filter
- *  in case of special vap (scan radio)
+ * cdp_update_mon_mac_filter() - update the monitor buffer and status filter
+ * @soc: the pointer to soc object
+ * @vdev_id: id of the pointer to vdev
+ * @cmd: add/del entry into peer table
  *
- * @param soc - the pointer to soc object
- * @param vdev_id - id of the pointer to vdev
- * @param cmd - add/del entry into peer table
- * @return - QDF_STATUS
+ * This defines interface function to set/reset monitor filter
+ * in case of special vap (scan radio)
+ *
+ * Return: QDF_STATUS
  */
 static inline QDF_STATUS
 cdp_update_mon_mac_filter(ol_txrx_soc_handle soc,
@@ -128,17 +128,18 @@ cdp_update_mon_mac_filter(ol_txrx_soc_handle soc,
 
 #ifdef WLAN_SUPPORT_MSCS
 /**
- * @brief record the MSCS data and send it to the Data path
- * @details
- *  This defines interface function to record the MSCS procedure
- *  based data parameters so that the data path layer can access it
+ * cdp_record_vdev_mscs_params() - record the MSCS data and send it to the
+ *                                 Data path
+ * @soc: the pointer to soc object
+ * @vdev_id: id of the pointer to vdev
+ * @macaddr: the address of neighbour peer
+ * @mscs_params: Structure having MSCS params obtained from handshake
+ * @active: Flag to set MSCS active/inactive
  *
- * @param soc - the pointer to soc object
- * @param vdev_id - id of the pointer to vdev
- * @param macaddr - the address of neighbour peer
- * @param mscs_params - Structure having MSCS params
- * obtained from handshake
- * @return - QDF_STATUS
+ * This defines interface function to record the MSCS procedure
+ * based data parameters so that the data path layer can access it
+ *
+ * Return: QDF_STATUS
  */
 static inline QDF_STATUS
 cdp_record_vdev_mscs_params(ol_txrx_soc_handle soc, uint8_t
@@ -160,14 +161,14 @@ cdp_record_vdev_mscs_params(ol_txrx_soc_handle soc, uint8_t
 #endif
 
 /**
- * @brief set the Reo Destination ring for the pdev
- * @details
- *  This will be used to configure the Reo Destination ring for this pdev.
+ * cdp_set_pdev_reo_dest() - set the Reo Destination ring for the pdev
+ * @soc: pointer to the soc
+ * @pdev_id: id of the data physical device object
+ * @val: the Reo destination ring index (1 to 4)
  *
- * @param soc - pointer to the soc
- * @param pdev_id - id of the data physical device object
- * @param val - the Reo destination ring index (1 to 4)
- * @return - QDF_STATUS
+ * This will be used to configure the Reo Destination ring for this pdev.
+ *
+ * Return: QDF_STATUS
  */
 static inline QDF_STATUS
 cdp_set_pdev_reo_dest(ol_txrx_soc_handle soc,
@@ -188,11 +189,11 @@ cdp_set_pdev_reo_dest(ol_txrx_soc_handle soc,
 }
 
 /**
- * @brief get the Reo Destination ring for the pdev
+ * cdp_get_pdev_reo_dest() - get the Reo Destination ring for the pdev
+ * @soc: pointer to the soc
+ * @pdev_id: id of physical device object
  *
- * @param soc - pointer to the soc
- * @param pdev_id - id of physical device object
- * @return - the Reo destination ring index (1 to 4), 0 if not supported.
+ * Return: the Reo destination ring index (1 to 4), 0 if not supported.
  */
 static inline enum cdp_host_reo_dest_ring
 cdp_get_pdev_reo_dest(ol_txrx_soc_handle soc, uint8_t pdev_id)
@@ -211,19 +212,19 @@ cdp_get_pdev_reo_dest(ol_txrx_soc_handle soc, uint8_t pdev_id)
 }
 
 /* Is this similar to ol_txrx_peer_state_update() in MCL */
+
 /**
- * @brief Update the authorize peer object at association time
- * @details
- *  For the host-based implementation of rate-control, it
- *  updates the peer/node-related parameters within rate-control
- *  context of the peer at association.
+ * cdp_peer_authorize() - Update the authorize peer object at association time
+ * @soc: pointer to the soc
+ * @vdev_id: id of the pointer to vdev
+ * @peer_mac: mac address of the node's object
+ * @authorize: either to authorize or unauthorize peer
  *
- * @param soc - pointer to the soc
- * @param vdev_id - id of the pointer to vdev
- * @param peer_mac - mac address of the node's object
- * @authorize - either to authorize or unauthorize peer
+ * For the host-based implementation of rate-control, it
+ * updates the peer/node-related parameters within rate-control
+ * context of the peer at association.
  *
- * @return QDF_STATUS
+ * Return: QDF_STATUS
  */
 static inline QDF_STATUS
 cdp_peer_authorize(ol_txrx_soc_handle soc, uint8_t vdev_id, uint8_t *peer_mac,
@@ -244,11 +245,10 @@ cdp_peer_authorize(ol_txrx_soc_handle soc, uint8_t vdev_id, uint8_t *peer_mac,
 }
 
 /**
- * cdp_peer_get_authorize Get per authorize status
- *
- * @soc - pointer to the soc
- * @vdev_id - id of the pointer to vdev
- * @peer_mac - mac address of the node's object
+ * cdp_peer_get_authorize() - Get per authorize status
+ * @soc: pointer to the soc
+ * @vdev_id: id of the pointer to vdev
+ * @peer_mac: mac address of the node's object
  *
  * Return: true is peer is authorized, false otherwise
  */
@@ -402,10 +402,9 @@ void cdp_vdev_reset_vdev_stats_id(ol_txrx_soc_handle soc,
 #ifdef VDEV_PEER_PROTOCOL_COUNT
 /**
  * cdp_set_vdev_peer_protocol_count() - set per-peer protocol count tracking
- *
- * @soc - pointer to the soc
- * @vdev - the data virtual device object
- * @enable - enable per-peer protocol count
+ * @soc: pointer to the soc
+ * @vdev_id: the data virtual device object
+ * @enable: enable per-peer protocol count
  *
  * Set per-peer protocol count feature enable
  *
@@ -431,14 +430,13 @@ void cdp_set_vdev_peer_protocol_count(ol_txrx_soc_handle soc, int8_t vdev_id,
 
 /**
  * cdp_set_vdev_peer_protocol_drop_mask() - set per-peer protocol drop mask
- *
- * @soc - pointer to the soc
- * @vdev - the data virtual device object
- * @drop_mask - drop_mask
+ * @soc: pointer to the soc
+ * @vdev_id: ID of the data virtual device object
+ * @drop_mask: drop_mask
  *
  * Set per-peer protocol drop_mask
  *
- * Return - void
+ * Return: void
  */
 static inline
 void cdp_set_vdev_peer_protocol_drop_mask(ol_txrx_soc_handle soc,
@@ -461,9 +459,8 @@ void cdp_set_vdev_peer_protocol_drop_mask(ol_txrx_soc_handle soc,
 /**
  * cdp_is_vdev_peer_protocol_count_enabled() - whether peer-protocol tracking
  *                                             enabled
- *
- * @soc - pointer to the soc
- * @vdev - the data virtual device object
+ * @soc: pointer to the soc
+ * @vdev_id: ID of the data virtual device object
  *
  * Get whether peer protocol count feature enabled or not
  *
@@ -489,9 +486,8 @@ int cdp_is_vdev_peer_protocol_count_enabled(ol_txrx_soc_handle soc,
 
 /**
  * cdp_get_peer_protocol_drop_mask() - get per-peer protocol count drop-mask
- *
- * @soc - pointer to the soc
- * @vdev - the data virtual device object
+ * @soc: pointer to the soc
+ * @vdev_id: ID of the data virtual device object
  *
  * Get peer-protocol-count drop-mask
  *
@@ -672,7 +668,7 @@ static inline QDF_STATUS cdp_txrx_get_pdev_param(ol_txrx_soc_handle soc,
 /**
  * cdp_txrx_peer_protocol_cnt() - set peer protocol count
  * @soc: opaque soc handle
- * @vdev: opaque vdev handle
+ * @vdev_id: vdev id
  * @nbuf: data packet
  * @is_egress: whether egress or ingress
  * @is_rx: whether tx or rx
@@ -706,7 +702,6 @@ cdp_txrx_peer_protocol_cnt(ol_txrx_soc_handle soc,
 
 /**
  * cdp_enable_peer_based_pktlog()- Set flag in peer structure
- *
  * @soc: pointer to the soc
  * @pdev_id: id of the data physical device object
  * @enable: enable or disable peer based filter based pktlog
@@ -740,7 +735,6 @@ cdp_enable_peer_based_pktlog(ol_txrx_soc_handle soc, uint8_t pdev_id,
 
 /**
  * cdp_calculate_delay_stats()- get rx delay stats
- *
  * @soc: pointer to the soc
  * @vdev_id: id of vdev handle
  * @nbuf: nbuf which is passed
@@ -767,20 +761,20 @@ cdp_calculate_delay_stats(ol_txrx_soc_handle soc, uint8_t vdev_id,
 }
 
 /**
- * @brief Subscribe to a specified WDI event.
- * @details
- *  This function adds the provided wdi_event_subscribe object to a list of
- *  subscribers for the specified WDI event.
- *  When the event in question happens, each subscriber for the event will
- *  have their callback function invoked.
- *  The order in which callback functions from multiple subscribers are
- *  invoked is unspecified.
+ * cdp_wdi_event_sub() - Subscribe to a specified WDI event.
+ * @soc: pointer to the soc
+ * @pdev_id: id of the data physical device object
+ * @event_cb_sub: the callback and context for the event subscriber
+ * @event: which event's notifications are being subscribed to
  *
- * @param soc - pointer to the soc
- * @param pdev_id - id of the data physical device object
- * @param event_cb_sub - the callback and context for the event subscriber
- * @param event - which event's notifications are being subscribed to
- * @return - int
+ * This function adds the provided wdi_event_subscribe object to a list of
+ * subscribers for the specified WDI event.
+ * When the event in question happens, each subscriber for the event will
+ * have their callback function invoked.
+ * The order in which callback functions from multiple subscribers are
+ * invoked is unspecified.
+ *
+ * Return: int
  */
 static inline int
 cdp_wdi_event_sub(ol_txrx_soc_handle soc, uint8_t pdev_id,
@@ -802,18 +796,18 @@ cdp_wdi_event_sub(ol_txrx_soc_handle soc, uint8_t pdev_id,
 }
 
 /**
- * @brief Unsubscribe from a specified WDI event.
- * @details
- *  This function removes the provided event subscription object from the
- *  list of subscribers for its event.
- *  This function shall only be called if there was a successful prior call
- *  to event_sub() on the same wdi_event_subscribe object.
+ * cdp_wdi_event_unsub() - Unsubscribe from a specified WDI event.
+ * @soc: pointer to the soc
+ * @pdev_id: id of the data physical device object
+ * @event_cb_sub: the callback and context for the event subscriber
+ * @event: which event's notifications are being subscribed to
  *
- * @param soc - pointer to the soc
- * @param pdev_id - id of the data physical device object
- * @param event_cb_sub - the callback and context for the event subscriber
- * @param event - which event's notifications are being subscribed to
- * @return - int
+ * This function removes the provided event subscription object from the
+ * list of subscribers for its event.
+ * This function shall only be called if there was a successful prior call
+ * to cdp_wdi_event_sub() on the same wdi_event_subscribe object.
+ *
+ * Return: int
  */
 static inline int
 cdp_wdi_event_unsub(ol_txrx_soc_handle soc,
@@ -836,17 +830,17 @@ cdp_wdi_event_unsub(ol_txrx_soc_handle soc,
 }
 
 /**
- * @brief Get security type from the from peer.
- * @details
+ * cdp_get_sec_type() - Get security type from the from peer.
+ * @soc: pointer to the soc
+ * @vdev_id: id of vdev handle
+ * @peer_mac: peer mac address
+ * @sec_idx: mcast or ucast frame type.
+ *
  * This function gets the Security information from the peer handler.
  * The security information is got from the rx descriptor and filled in
  * to the peer handler.
  *
- * @param soc - pointer to the soc
- * @param vdev_id - id of vdev handle
- * @param peer mac - peer mac address
- * @param sec_idx - mcast or ucast frame type.
- * @return - int
+ * Return: int
  */
 static inline int
 cdp_get_sec_type(ol_txrx_soc_handle soc, uint8_t vdev_id, uint8_t *peer_mac,
@@ -867,11 +861,12 @@ cdp_get_sec_type(ol_txrx_soc_handle soc, uint8_t vdev_id, uint8_t *peer_mac,
 }
 
 /**
-  * cdp_set_mgmt_tx_power(): function to set tx power for mgmt frames
-  * @param soc - pointer to the soc
+  * cdp_set_mgmt_tx_power() - function to set tx power for mgmt frames
+  * @soc: pointer to the soc
   * @vdev_id : id of vdev handle
-  * @subtype_index: subtype
+  * @subtype: subtype
   * @tx_power: Tx power
+  *
   * Return: QDF_STATUS
   */
 static inline QDF_STATUS
@@ -994,7 +989,6 @@ void cdp_set_cfr_rcc(ol_txrx_soc_handle soc, uint8_t pdev_id, bool enable)
 
 /**
  * cdp_get_cfr_dbg_stats() - Get debug statistics for CFR
- *
  * @soc: SOC TXRX handle
  * @pdev_id: ID of the physical device object
  * @buf: CFR RCC debug statistics buffer
@@ -1020,7 +1014,6 @@ cdp_get_cfr_dbg_stats(ol_txrx_soc_handle soc, uint8_t pdev_id,
 
 /**
  * cdp_cfr_clr_dbg_stats() - Clear debug statistics for CFR
- *
  * @soc: SOC TXRX handle
  * @pdev_id: ID of the physical device object
  */
@@ -1108,10 +1101,11 @@ cdp_update_pdev_rx_protocol_tag(ol_txrx_soc_handle soc,
 #ifdef WLAN_SUPPORT_RX_TAG_STATISTICS
 /**
  * cdp_dump_pdev_rx_protocol_tag_stats() - wrapper function to dump the protocol
-				tag statistics for given or all protocols
+ *				tag statistics for given or all protocols
  * @soc: SOC TXRX handle
  * @pdev_id: id of CDP pdev pointer
  * @protocol_type: Protocol type for which the tag should be update
+ *
  * Return: Returns QDF_STATUS_SUCCESS/FAILURE
  */
 static inline QDF_STATUS
@@ -1138,7 +1132,7 @@ cdp_dump_pdev_rx_protocol_tag_stats(ol_txrx_soc_handle soc,
 
 #ifdef ATH_SUPPORT_NAC_RSSI
 /**
-  * cdp_vdev_config_for_nac_rssi(): To invoke dp callback for nac rssi config
+  * cdp_vdev_config_for_nac_rssi() - To invoke dp callback for nac rssi config
   * @soc: soc pointer
   * @vdev_id: id of vdev
   * @nac_cmd: specifies nac_rss config action add, del, list
@@ -1167,8 +1161,8 @@ static inline QDF_STATUS cdp_vdev_config_for_nac_rssi(ol_txrx_soc_handle soc,
 			nac_cmd, bssid, client_macaddr, chan_num);
 }
 
-/*
- * cdp_vdev_get_neighbour_rssi(): To invoke dp callback to get rssi value of nac
+/**
+ * cdp_vdev_get_neighbour_rssi() - invoke dp callback to get rssi value of nac
  * @soc: soc pointer
  * @vdev_id: id of vdev
  * @macaddr: Non-Associated client MAC
@@ -1257,9 +1251,9 @@ cdp_dump_rx_flow_tag_stats(ol_txrx_soc_handle soc, uint8_t pdev_id,
 
 /**
  * cdp_txrx_peer_flush_frags() - flush frags for peer
- *
- * @soc - pointer to the soc
- * @vdev - the data virtual device object
+ * @soc: pointer to the soc
+ * @vdev_id: vdev id
+ * @peer_mac: peer MAC address
  *
  * Get peer-protocol-count drop-mask
  *
@@ -1370,8 +1364,8 @@ static inline QDF_STATUS cdp_get_uplink_delay(ol_txrx_soc_handle soc,
  * cdp_txrx_set_pdev_phyrx_error_mask() - set phyrx error mask
  * @soc: opaque soc handle
  * @pdev_id: id of data path pdev handle
- * @mask1: mask to configure 0 to 31 phy error
- * @mask2: mask to configure 32 to 63 phy error
+ * @mask: mask to configure 0 to 31 phy error
+ * @mask_cont: mask to configure 32 to 63 phy error
  *
  * Return: status: 0 - Success, non-zero: Failure
  */