From b2294c287e65d6b71a8e4292d093b509fda0cba5 Mon Sep 17 00:00:00 2001 From: Jeff Johnson Date: Wed, 4 Jan 2023 17:52:16 -0800 Subject: [PATCH] qcacmn: Fix dp/wifi3.0/dp_tx_desc.* documentation The kernel-doc script identified a large number of documentation issues in dp/wifi3.0/dp_tx_desc.[ch], so fix those issues. In addition, there are a number of instances where public functions have their implementation documented instead of having their interface documented, so move that documentation. Change-Id: I349f0e9d9336ae632fb31e88ddc34ecacc4a1f68 CRs-Fixed: 3373161 --- dp/wifi3.0/dp_tx_desc.c | 160 +---------------------- dp/wifi3.0/dp_tx_desc.h | 283 +++++++++++++++++++++++++++++++--------- 2 files changed, 224 insertions(+), 219 deletions(-) diff --git a/dp/wifi3.0/dp_tx_desc.c b/dp/wifi3.0/dp_tx_desc.c index 5e080ac84d..e4fcbe51b6 100644 --- a/dp/wifi3.0/dp_tx_desc.c +++ b/dp/wifi3.0/dp_tx_desc.c @@ -42,8 +42,8 @@ do { \ /** * dp_tx_desc_pool_counter_initialize() - Initialize counters - * @tx_desc_pool Handle to DP tx_desc_pool structure - * @num_elem Number of descriptor elements per pool + * @tx_desc_pool: Handle to DP tx_desc_pool structure + * @num_elem: Number of descriptor elements per pool * * Return: None */ @@ -95,12 +95,6 @@ static void dp_tx_desc_clean_up(void *ctxt, void *elem, void *elem_list) } } -/** - * dp_tx_desc_pool_cleanup() - Clean up the tx dexcriptor pools - * @soc: Handle to DP SoC structure - * @nbuf_list: nbuf list for delayed free - * - */ void dp_tx_desc_pool_cleanup(struct dp_soc *soc, qdf_nbuf_t *nbuf_list) { int i; @@ -121,34 +115,6 @@ void dp_tx_desc_pool_cleanup(struct dp_soc *soc, qdf_nbuf_t *nbuf_list) } #endif -/** - * dp_tx_desc_pool_alloc() - Allocate Tx Descriptor pool(s) - * @soc Handle to DP SoC structure - * @pool_id pool to allocate - * @num_elem Number of descriptor elements per pool - * - * This function allocates memory for SW tx descriptors - * (used within host for tx data path). - * The number of tx descriptors required will be large - * since based on number of clients (1024 clients x 3 radios), - * outstanding MSDUs stored in TQM queues and LMAC queues will be significantly - * large. - * - * To avoid allocating a large contiguous memory, it uses multi_page_alloc qdf - * function to allocate memory - * in multiple pages. It then iterates through the memory allocated across pages - * and links each descriptor - * to next descriptor, taking care of page boundaries. - * - * Since WiFi 3.0 HW supports multiple Tx rings, multiple pools are allocated, - * one for each ring; - * This minimizes lock contention when hard_start_xmit is called - * from multiple CPUs. - * Alternately, multiple pools can be used for multiple VDEVs for VDEV level - * flow control. - * - * Return: Status code. 0 for success. - */ QDF_STATUS dp_tx_desc_pool_alloc(struct dp_soc *soc, uint8_t pool_id, uint32_t num_elem) { @@ -170,12 +136,6 @@ QDF_STATUS dp_tx_desc_pool_alloc(struct dp_soc *soc, uint8_t pool_id, return QDF_STATUS_SUCCESS; } -/** - * dp_tx_desc_pool_free() - Free the tx dexcriptor pools - * @soc: Handle to DP SoC structure - * @pool_id: pool to free - * - */ void dp_tx_desc_pool_free(struct dp_soc *soc, uint8_t pool_id) { struct dp_tx_desc_pool_s *tx_desc_pool; @@ -188,15 +148,6 @@ void dp_tx_desc_pool_free(struct dp_soc *soc, uint8_t pool_id) true); } -/** - * dp_tx_desc_pool_init() - Initialize Tx Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @pool_id: pool to allocate - * @num_elem: Number of descriptor elements per pool - * - * Return: QDF_STATUS_SUCCESS - * QDF_STATUS_E_FAULT - */ QDF_STATUS dp_tx_desc_pool_init(struct dp_soc *soc, uint8_t pool_id, uint32_t num_elem) { @@ -230,12 +181,6 @@ QDF_STATUS dp_tx_desc_pool_init(struct dp_soc *soc, uint8_t pool_id, return QDF_STATUS_SUCCESS; } -/** - * dp_tx_desc_pool_deinit() - de-initialize Tx Descriptor pool(s) - * @soc Handle to DP SoC structure - * @pool_id: pool to de-initialize - * - */ void dp_tx_desc_pool_deinit(struct dp_soc *soc, uint8_t pool_id) { struct dp_tx_desc_pool_s *tx_desc_pool; @@ -246,15 +191,6 @@ void dp_tx_desc_pool_deinit(struct dp_soc *soc, uint8_t pool_id) TX_DESC_LOCK_DESTROY(&tx_desc_pool->lock); } -/** - * dp_tx_ext_desc_pool_alloc() - allocate Tx extension Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to allocate - * @num_elem: Number of descriptor elements per pool - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_NOMEM - */ QDF_STATUS dp_tx_ext_desc_pool_alloc(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem) { @@ -335,15 +271,6 @@ fail_exit: return status; } -/** - * dp_tx_ext_desc_pool_init() - initialize Tx extension Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to initialize - * @num_elem: Number of descriptor elements per pool - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_NOMEM - */ QDF_STATUS dp_tx_ext_desc_pool_init(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem) { @@ -386,7 +313,7 @@ QDF_STATUS dp_tx_ext_desc_pool_init(struct dp_soc *soc, uint8_t num_pool, p_elem = c_elem; for (i = 0; i < dp_tx_ext_desc_pool->elem_count; i++) { if (!(i % pages->num_element_per_page)) { - /** + /* * First element for new page, * should point next page */ @@ -422,12 +349,6 @@ fail: return status; } -/** - * dp_tx_ext_desc_pool_free() - free Tx extension Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to free - * - */ void dp_tx_ext_desc_pool_free(struct dp_soc *soc, uint8_t num_pool) { uint8_t pool_id; @@ -450,12 +371,6 @@ void dp_tx_ext_desc_pool_free(struct dp_soc *soc, uint8_t num_pool) } } -/** - * dp_tx_ext_desc_pool_deinit() - deinit Tx extension Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to de-initialize - * - */ void dp_tx_ext_desc_pool_deinit(struct dp_soc *soc, uint8_t num_pool) { uint8_t pool_id; @@ -468,15 +383,6 @@ void dp_tx_ext_desc_pool_deinit(struct dp_soc *soc, uint8_t num_pool) } #if defined(FEATURE_TSO) -/** - * dp_tx_tso_desc_pool_alloc() - allocate TSO Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to allocate - * @num_elem: Number of descriptor elements per pool - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_NOMEM - */ QDF_STATUS dp_tx_tso_desc_pool_alloc(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem) { @@ -511,12 +417,6 @@ fail: return QDF_STATUS_E_NOMEM; } -/** - * dp_tx_tso_desc_pool_free() - free TSO Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to free - * - */ void dp_tx_tso_desc_pool_free(struct dp_soc *soc, uint8_t num_pool) { struct dp_tx_tso_seg_pool_s *tso_desc_pool; @@ -530,15 +430,6 @@ void dp_tx_tso_desc_pool_free(struct dp_soc *soc, uint8_t num_pool) } } -/** - * dp_tx_tso_desc_pool_init() - initialize TSO Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to initialize - * @num_elem: Number of descriptor elements per pool - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_NOMEM - */ QDF_STATUS dp_tx_tso_desc_pool_init(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem) { @@ -571,12 +462,6 @@ QDF_STATUS dp_tx_tso_desc_pool_init(struct dp_soc *soc, uint8_t num_pool, return QDF_STATUS_SUCCESS; } -/** - * dp_tx_tso_desc_pool_deinit() - deinitialize TSO Descriptor pool(s) - * @soc: Handle to DP SoC structure - * @num_pool: Number of pools to free - * - */ void dp_tx_tso_desc_pool_deinit(struct dp_soc *soc, uint8_t num_pool) { struct dp_tx_tso_seg_pool_s *tso_desc_pool; @@ -594,17 +479,6 @@ void dp_tx_tso_desc_pool_deinit(struct dp_soc *soc, uint8_t num_pool) } } -/** - * dp_tx_tso_num_seg_pool_alloc() - Allocate descriptors that tracks the - * fragments in each tso segment - * - * @soc: handle to dp soc structure - * @num_pool: number of pools to allocate - * @num_elem: total number of descriptors to be allocated - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_NOMEM - */ QDF_STATUS dp_tx_tso_num_seg_pool_alloc(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem) { @@ -638,13 +512,6 @@ fail: return QDF_STATUS_E_NOMEM; } -/** - * dp_tx_tso_num_seg_pool_free() - free descriptors that tracks the - * fragments in each tso segment - * - * @soc: handle to dp soc structure - * @num_pool: number of pools to free - */ void dp_tx_tso_num_seg_pool_free(struct dp_soc *soc, uint8_t num_pool) { struct dp_tx_tso_num_seg_pool_s *tso_num_seg_pool; @@ -658,17 +525,6 @@ void dp_tx_tso_num_seg_pool_free(struct dp_soc *soc, uint8_t num_pool) } } -/** - * dp_tx_tso_num_seg_pool_init() - Initialize descriptors that tracks the - * fragments in each tso segment - * - * @soc: handle to dp soc structure - * @num_pool: number of pools to initialize - * @num_elem: total number of descriptors to be initialized - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_FAULT - */ QDF_STATUS dp_tx_tso_num_seg_pool_init(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem) { @@ -698,16 +554,6 @@ QDF_STATUS dp_tx_tso_num_seg_pool_init(struct dp_soc *soc, uint8_t num_pool, return QDF_STATUS_SUCCESS; } -/** - * dp_tx_tso_num_seg_pool_deinit() - de-initialize descriptors that tracks the - * fragments in each tso segment - * - * @soc: handle to dp soc structure - * @num_pool: number of pools to de-initialize - * - * Return - QDF_STATUS_SUCCESS - * QDF_STATUS_E_FAULT - */ void dp_tx_tso_num_seg_pool_deinit(struct dp_soc *soc, uint8_t num_pool) { struct dp_tx_tso_num_seg_pool_s *tso_num_seg_pool; diff --git a/dp/wifi3.0/dp_tx_desc.h b/dp/wifi3.0/dp_tx_desc.h index 5182c3a737..bcd7034550 100644 --- a/dp/wifi3.0/dp_tx_desc.h +++ b/dp/wifi3.0/dp_tx_desc.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 @@ -24,7 +24,7 @@ #include "dp_tx.h" #include "dp_internal.h" -/** +/* * 21 bits cookie * 2 bits pool id 0 ~ 3, * 10 bits page id 0 ~ 1023 @@ -38,7 +38,7 @@ #define DP_TX_DESC_ID_OFFSET_MASK 0x00001F #define DP_TX_DESC_ID_OFFSET_OS 0 -/** +/* * Compilation assert on tx desc size * * if assert is hit please update POOL_MASK, @@ -107,35 +107,201 @@ static inline void dp_tx_desc_set_magic(struct dp_tx_desc_s *tx_desc, } #endif +/** + * dp_tx_desc_pool_alloc() - Allocate Tx Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @pool_id: pool to allocate + * @num_elem: Number of descriptor elements per pool + * + * This function allocates memory for SW tx descriptors + * (used within host for tx data path). + * The number of tx descriptors required will be large + * since based on number of clients (1024 clients x 3 radios), + * outstanding MSDUs stored in TQM queues and LMAC queues will be significantly + * large. + * + * To avoid allocating a large contiguous memory, it uses multi_page_alloc qdf + * function to allocate memory + * in multiple pages. It then iterates through the memory allocated across pages + * and links each descriptor + * to next descriptor, taking care of page boundaries. + * + * Since WiFi 3.0 HW supports multiple Tx rings, multiple pools are allocated, + * one for each ring; + * This minimizes lock contention when hard_start_xmit is called + * from multiple CPUs. + * Alternately, multiple pools can be used for multiple VDEVs for VDEV level + * flow control. + * + * Return: Status code. 0 for success. + */ QDF_STATUS dp_tx_desc_pool_alloc(struct dp_soc *soc, uint8_t pool_id, uint32_t num_elem); + +/** + * dp_tx_desc_pool_init() - Initialize Tx Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @pool_id: pool to allocate + * @num_elem: Number of descriptor elements per pool + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_FAULT + */ QDF_STATUS dp_tx_desc_pool_init(struct dp_soc *soc, uint8_t pool_id, uint32_t num_elem); + +/** + * dp_tx_desc_pool_free() - Free the tx dexcriptor pools + * @soc: Handle to DP SoC structure + * @pool_id: pool to free + * + */ void dp_tx_desc_pool_free(struct dp_soc *soc, uint8_t pool_id); + +/** + * dp_tx_desc_pool_deinit() - de-initialize Tx Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @pool_id: pool to de-initialize + * + */ void dp_tx_desc_pool_deinit(struct dp_soc *soc, uint8_t pool_id); -QDF_STATUS dp_tx_ext_desc_pool_alloc(struct dp_soc *soc, uint8_t pool_id, +/** + * dp_tx_ext_desc_pool_alloc() - allocate Tx extension Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to allocate + * @num_elem: Number of descriptor elements per pool + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_NOMEM + */ +QDF_STATUS dp_tx_ext_desc_pool_alloc(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem); -QDF_STATUS dp_tx_ext_desc_pool_init(struct dp_soc *soc, uint8_t pool_id, - uint32_t num_elem); -void dp_tx_ext_desc_pool_free(struct dp_soc *soc, uint8_t pool_id); -void dp_tx_ext_desc_pool_deinit(struct dp_soc *soc, uint8_t pool_id); -QDF_STATUS dp_tx_tso_desc_pool_alloc(struct dp_soc *soc, uint8_t pool_id, +/** + * dp_tx_ext_desc_pool_init() - initialize Tx extension Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to initialize + * @num_elem: Number of descriptor elements per pool + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_NOMEM + */ +QDF_STATUS dp_tx_ext_desc_pool_init(struct dp_soc *soc, uint8_t num_pool, + uint32_t num_elem); + +/** + * dp_tx_ext_desc_pool_free() - free Tx extension Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to free + * + */ +void dp_tx_ext_desc_pool_free(struct dp_soc *soc, uint8_t num_pool); + +/** + * dp_tx_ext_desc_pool_deinit() - deinit Tx extension Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to de-initialize + * + */ +void dp_tx_ext_desc_pool_deinit(struct dp_soc *soc, uint8_t num_pool); + +/** + * dp_tx_tso_desc_pool_alloc() - allocate TSO Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to allocate + * @num_elem: Number of descriptor elements per pool + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_NOMEM + */ +QDF_STATUS dp_tx_tso_desc_pool_alloc(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem); -QDF_STATUS dp_tx_tso_desc_pool_init(struct dp_soc *soc, uint8_t pool_id, - uint32_t num_elem); -void dp_tx_tso_desc_pool_free(struct dp_soc *soc, uint8_t pool_id); -void dp_tx_tso_desc_pool_deinit(struct dp_soc *soc, uint8_t pool_id); -QDF_STATUS dp_tx_tso_num_seg_pool_alloc(struct dp_soc *soc, uint8_t pool_id, - uint32_t num_elem); -QDF_STATUS dp_tx_tso_num_seg_pool_init(struct dp_soc *soc, uint8_t pool_id, +/** + * dp_tx_tso_desc_pool_init() - initialize TSO Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to initialize + * @num_elem: Number of descriptor elements per pool + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_NOMEM + */ +QDF_STATUS dp_tx_tso_desc_pool_init(struct dp_soc *soc, uint8_t num_pool, + uint32_t num_elem); + +/** + * dp_tx_tso_desc_pool_free() - free TSO Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to free + * + */ +void dp_tx_tso_desc_pool_free(struct dp_soc *soc, uint8_t num_pool); + +/** + * dp_tx_tso_desc_pool_deinit() - deinitialize TSO Descriptor pool(s) + * @soc: Handle to DP SoC structure + * @num_pool: Number of pools to free + * + */ +void dp_tx_tso_desc_pool_deinit(struct dp_soc *soc, uint8_t num_pool); + +/** + * dp_tx_tso_num_seg_pool_alloc() - Allocate descriptors that tracks the + * fragments in each tso segment + * + * @soc: handle to dp soc structure + * @num_pool: number of pools to allocate + * @num_elem: total number of descriptors to be allocated + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_NOMEM + */ +QDF_STATUS dp_tx_tso_num_seg_pool_alloc(struct dp_soc *soc, uint8_t num_pool, + uint32_t num_elem); + +/** + * dp_tx_tso_num_seg_pool_init() - Initialize descriptors that tracks the + * fragments in each tso segment + * + * @soc: handle to dp soc structure + * @num_pool: number of pools to initialize + * @num_elem: total number of descriptors to be initialized + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_FAULT + */ +QDF_STATUS dp_tx_tso_num_seg_pool_init(struct dp_soc *soc, uint8_t num_pool, uint32_t num_elem); -void dp_tx_tso_num_seg_pool_free(struct dp_soc *soc, uint8_t pool_id); -void dp_tx_tso_num_seg_pool_deinit(struct dp_soc *soc, uint8_t pool_id); + +/** + * dp_tx_tso_num_seg_pool_free() - free descriptors that tracks the + * fragments in each tso segment + * + * @soc: handle to dp soc structure + * @num_pool: number of pools to free + */ +void dp_tx_tso_num_seg_pool_free(struct dp_soc *soc, uint8_t num_pool); + +/** + * dp_tx_tso_num_seg_pool_deinit() - de-initialize descriptors that tracks the + * fragments in each tso segment + * + * @soc: handle to dp soc structure + * @num_pool: number of pools to de-initialize + * + * Return: QDF_STATUS_SUCCESS + * QDF_STATUS_E_FAULT + */ +void dp_tx_tso_num_seg_pool_deinit(struct dp_soc *soc, uint8_t num_pool); #ifdef DP_UMAC_HW_RESET_SUPPORT +/** + * dp_tx_desc_pool_cleanup() - Clean up the tx dexcriptor pools + * @soc: Handle to DP SoC structure + * @nbuf_list: nbuf list for delayed free + * + */ void dp_tx_desc_pool_cleanup(struct dp_soc *soc, qdf_nbuf_t *nbuf_list); #endif @@ -177,7 +343,7 @@ struct dp_tx_desc_s *dp_tx_get_desc_flow_pool(struct dp_tx_desc_pool_s *pool) } /** - * ol_tx_put_desc_flow_pool() - put descriptor to flow pool freelist + * dp_tx_put_desc_flow_pool() - put descriptor to flow pool freelist * @pool: flow pool * @tx_desc: tx descriptor * @@ -198,7 +364,6 @@ void dp_tx_put_desc_flow_pool(struct dp_tx_desc_pool_s *pool, /** * dp_tx_flow_pool_member_clean() - Clean the members of TX flow pool - * * @pool: flow pool * * Return: None @@ -217,7 +382,6 @@ dp_tx_flow_pool_member_clean(struct dp_tx_desc_pool_s *pool) /** * dp_tx_is_threshold_reached() - Check if current avail desc meet threshold - * * @pool: flow pool * @avail_desc: available descriptor number * @@ -240,7 +404,6 @@ dp_tx_is_threshold_reached(struct dp_tx_desc_pool_s *pool, uint16_t avail_desc) /** * dp_tx_adjust_flow_pool_state() - Adjust flow pool state - * * @soc: dp soc * @pool: flow pool */ @@ -295,7 +458,6 @@ dp_tx_adjust_flow_pool_state(struct dp_soc *soc, /** * dp_tx_desc_alloc() - Allocate a Software Tx descriptor from given pool - * * @soc: Handle to DP SoC structure * @desc_pool_id: ID of the flow control fool * @@ -390,11 +552,10 @@ dp_tx_desc_alloc(struct dp_soc *soc, uint8_t desc_pool_id) } /** - * dp_tx_desc_free() - Fee a tx descriptor and attach it to free list - * + * dp_tx_desc_free() - Free a tx descriptor and attach it to free list * @soc: Handle to DP SoC structure * @tx_desc: the tx descriptor to be freed - * @desc_pool_id: ID of the flow control fool + * @desc_pool_id: ID of the flow control pool * * Return: None */ @@ -505,11 +666,10 @@ dp_tx_is_threshold_reached(struct dp_tx_desc_pool_s *pool, uint16_t avail_desc) /** * dp_tx_desc_alloc() - Allocate a Software Tx Descriptor from given pool + * @soc: Handle to DP SoC structure + * @desc_pool_id: * - * @soc Handle to DP SoC structure - * @pool_id - * - * Return: + * Return: Tx descriptor or NULL */ static inline struct dp_tx_desc_s * dp_tx_desc_alloc(struct dp_soc *soc, uint8_t desc_pool_id) @@ -548,11 +708,10 @@ dp_tx_desc_alloc(struct dp_soc *soc, uint8_t desc_pool_id) } /** - * dp_tx_desc_free() - Fee a tx descriptor and attach it to free list - * - * @soc Handle to DP SoC structure - * @pool_id - * @tx_desc + * dp_tx_desc_free() - Free a tx descriptor and attach it to free list + * @soc: Handle to DP SoC structure + * @tx_desc: Descriptor to free + * @desc_pool_id: Descriptor pool Id * * Return: None */ @@ -657,11 +816,10 @@ void dp_tx_prefetch_desc(struct dp_tx_desc_s *tx_desc) /** * dp_tx_desc_alloc() - Allocate a Software Tx Descriptor from given pool + * @soc: Handle to DP SoC structure + * @desc_pool_id: pool id * - * @param soc Handle to DP SoC structure - * @param pool_id - * - * Return: + * Return: Tx Descriptor or NULL */ static inline struct dp_tx_desc_s *dp_tx_desc_alloc(struct dp_soc *soc, uint8_t desc_pool_id) @@ -695,12 +853,12 @@ static inline struct dp_tx_desc_s *dp_tx_desc_alloc(struct dp_soc *soc, * dp_tx_desc_alloc_multiple() - Allocate batch of software Tx Descriptors * from given pool * @soc: Handle to DP SoC structure - * @pool_id: pool id should pick up + * @desc_pool_id: pool id should pick up * @num_requested: number of required descriptor * * allocate multiple tx descriptor and make a link * - * Return: h_desc first descriptor pointer + * Return: first descriptor pointer or NULL */ static inline struct dp_tx_desc_s *dp_tx_desc_alloc_multiple( struct dp_soc *soc, uint8_t desc_pool_id, uint8_t num_requested) @@ -741,11 +899,10 @@ static inline struct dp_tx_desc_s *dp_tx_desc_alloc_multiple( } /** - * dp_tx_desc_free() - Fee a tx descriptor and attach it to free list - * - * @soc Handle to DP SoC structure - * @pool_id - * @tx_desc + * dp_tx_desc_free() - Free a tx descriptor and attach it to free list + * @soc: Handle to DP SoC structure + * @tx_desc: descriptor to free + * @desc_pool_id: ID of the free pool */ static inline void dp_tx_desc_free(struct dp_soc *soc, struct dp_tx_desc_s *tx_desc, @@ -770,9 +927,8 @@ dp_tx_desc_free(struct dp_soc *soc, struct dp_tx_desc_s *tx_desc, #ifdef QCA_DP_TX_DESC_ID_CHECK /** * dp_tx_is_desc_id_valid() - check is the tx desc id valid - * - * @soc Handle to DP SoC structure - * @tx_desc_id + * @soc: Handle to DP SoC structure + * @tx_desc_id: * * Return: true or false */ @@ -874,13 +1030,16 @@ static inline void dp_tx_desc_update_fast_comp_flag(struct dp_soc *soc, #endif /* QCA_DP_TX_DESC_FAST_COMP_ENABLE */ /** - * dp_tx_desc_find() - find dp tx descriptor from cokie - * @soc - handle for the device sending the data - * @tx_desc_id - the ID of the descriptor in question - * @return the descriptor object that has the specified ID + * dp_tx_desc_find() - find dp tx descriptor from pool/page/offset + * @soc: handle for the device sending the data + * @pool_id: + * @page_id: + * @offset: * - * Use a tx descriptor ID to find the corresponding descriptor object. + * Use page and offset to find the corresponding descriptor object in + * the given descriptor pool. * + * Return: the descriptor object that has the specified ID */ static inline struct dp_tx_desc_s *dp_tx_desc_find(struct dp_soc *soc, uint8_t pool_id, uint16_t page_id, uint16_t offset) @@ -894,7 +1053,7 @@ static inline struct dp_tx_desc_s *dp_tx_desc_find(struct dp_soc *soc, /** * dp_tx_ext_desc_alloc() - Get tx extension descriptor from pool * @soc: handle for the device sending the data - * @pool_id: target pool id + * @desc_pool_id: target pool id * * Return: None */ @@ -920,8 +1079,8 @@ struct dp_tx_ext_desc_elem_s *dp_tx_ext_desc_alloc(struct dp_soc *soc, /** * dp_tx_ext_desc_free() - Release tx extension descriptor to the pool * @soc: handle for the device sending the data - * @pool_id: target pool id * @elem: ext descriptor pointer should release + * @desc_pool_id: target pool id * * Return: None */ @@ -937,7 +1096,7 @@ static inline void dp_tx_ext_desc_free(struct dp_soc *soc, } /** - * dp_tx_ext_desc_free_multiple() - Fee multiple tx extension descriptor and + * dp_tx_ext_desc_free_multiple() - Free multiple tx extension descriptor and * attach it to free list * @soc: Handle to DP SoC structure * @desc_pool_id: pool id should pick up @@ -1056,11 +1215,11 @@ void dp_tso_num_seg_free(struct dp_soc *soc, } #endif -/* - * dp_tx_me_alloc_buf() Alloc descriptor from me pool - * @pdev DP_PDEV handle for datapath +/** + * dp_tx_me_alloc_buf() - Alloc descriptor from me pool + * @pdev: DP_PDEV handle for datapath * - * Return:dp_tx_me_buf_t(buf) + * Return: tx descriptor on success, NULL on error */ static inline struct dp_tx_me_buf_t* dp_tx_me_alloc_buf(struct dp_pdev *pdev) @@ -1081,7 +1240,7 @@ dp_tx_me_alloc_buf(struct dp_pdev *pdev) return buf; } -/* +/** * dp_tx_me_free_buf() - Unmap the buffer holding the dest * address, free me descriptor and add it to the free-pool * @pdev: DP_PDEV handle for datapath