qcacmn: Fix QDF memory documentation

The kernel-doc script identified a large number of documentation
issues in the QDF memory abstractions, 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: I4e30fd85e65567485cdc7a9adfc38c69df0cfa55
CRs-Fixed: 3406199
This commit is contained in:
Jeff Johnson
2023-02-12 20:52:37 -08:00
committed by Madan Koyyalamudi
parent b9fcc44fd3
commit 1e4a1adb96
3 changed files with 267 additions and 256 deletions

View File

@@ -61,6 +61,7 @@ struct qdf_mem_dma_page_t {
* @num_pages: Number of allocation needed pages
* @dma_pages: page information storage in case of coherent memory
* @cacheable_pages: page information storage in case of cacheable memory
* @page_size: page size
* @is_mem_prealloc: flag for multiple pages pre-alloc or not
*/
struct qdf_mem_multi_page_t {
@@ -115,7 +116,7 @@ bool qdf_mem_debug_config_get(void);
#ifdef QCA_WIFI_MODULE_PARAMS_FROM_INI
/**
* qdf_mem_debug_disabled_set() - Set mem_debug_disabled
* qdf_mem_debug_disabled_config_set() - Set mem_debug_disabled
* @str_value: value of the module param
*
* This function will set qdf module param mem_debug_disabled
@@ -132,7 +133,7 @@ QDF_STATUS qdf_mem_debug_disabled_config_set(const char *str_value);
* @line: Line number of the call site
* @caller: Address of the caller function
*
* This function will dynamicallly allocate the specified number of bytes of
* This function will dynamically allocate the specified number of bytes of
* memory and add it to the qdf tracking list to check for memory leaks and
* corruptions
*
@@ -144,8 +145,10 @@ void *qdf_mem_malloc_atomic_debug(size_t size, const char *func,
/**
* qdf_mem_malloc_atomic_debug_fl() - allocation QDF memory atomically
* @size: Number of bytes of memory to allocate.
* @func: Function name of the call site
* @line: Line number of the call site
*
* This function will dynamicallly allocate the specified number of bytes of
* This function will dynamically allocate the specified number of bytes of
* memory.
*
* Return:
@@ -164,7 +167,7 @@ void *qdf_mem_malloc_atomic_debug_fl(qdf_size_t size, const char *func,
* @caller: Address of the caller function
* @flag: GFP flag
*
* This function will dynamicallly allocate the specified number of bytes of
* This function will dynamically allocate the specified number of bytes of
* memory and add it to the qdf tracking list to check for memory leaks and
* corruptions
*
@@ -183,7 +186,7 @@ void *qdf_mem_malloc_debug(size_t size, const char *func, uint32_t line,
qdf_mem_malloc_atomic_debug(size, __func__, __LINE__, QDF_RET_IP)
/**
* qdf_mem_free_debug() - debug version of qdf_mem_free
* qdf_mem_free() - free allocate memory
* @ptr: Pointer to the starting address of the memory to be freed.
*
* This function will free the memory pointed to by 'ptr'. It also checks for
@@ -191,11 +194,30 @@ void *qdf_mem_malloc_debug(size_t size, const char *func, uint32_t line,
*
* Return: none
*/
void qdf_mem_free_debug(void *ptr, const char *file, uint32_t line);
#define qdf_mem_free(ptr) \
qdf_mem_free_debug(ptr, __func__, __LINE__)
void qdf_mem_free_debug(void *ptr, const char *file, uint32_t line);
/**
* qdf_mem_multi_pages_alloc_debug() - Debug version of
* qdf_mem_multi_pages_alloc
* @osdev: OS device handle pointer
* @pages: Multi page information storage
* @element_size: Each element size
* @element_num: Total number of elements should be allocated
* @memctxt: Memory context
* @cacheable: Coherent memory or cacheable memory
* @func: Caller of this allocator
* @line: Line number of the caller
* @caller: Return address of the caller
*
* This function will allocate large size of memory over multiple pages.
* Large size of contiguous memory allocation will fail frequently, then
* instead of allocate large memory by one shot, allocate through multiple, non
* contiguous memory and combine pages when actual usage
*
* Return: None
*/
void qdf_mem_multi_pages_alloc_debug(qdf_device_t osdev,
struct qdf_mem_multi_page_t *pages,
size_t element_size, uint32_t element_num,
@@ -203,17 +225,57 @@ void qdf_mem_multi_pages_alloc_debug(qdf_device_t osdev,
const char *func, uint32_t line,
void *caller);
/**
* qdf_mem_multi_pages_alloc() - allocate large size of kernel memory
* @osdev: OS device handle pointer
* @pages: Multi page information storage
* @element_size: Each element size
* @element_num: Total number of elements should be allocated
* @memctxt: Memory context
* @cacheable: Coherent memory or cacheable memory
*
* This function will allocate large size of memory over multiple pages.
* Large size of contiguous memory allocation will fail frequently, then
* instead of allocate large memory by one shot, allocate through multiple, non
* contiguous memory and combine pages when actual usage
*
* Return: None
*/
#define qdf_mem_multi_pages_alloc(osdev, pages, element_size, element_num,\
memctxt, cacheable) \
qdf_mem_multi_pages_alloc_debug(osdev, pages, element_size, \
element_num, memctxt, cacheable, \
__func__, __LINE__, QDF_RET_IP)
/**
* qdf_mem_multi_pages_free_debug() - Debug version of qdf_mem_multi_pages_free
* @osdev: OS device handle pointer
* @pages: Multi page information storage
* @memctxt: Memory context
* @cacheable: Coherent memory or cacheable memory
* @func: Caller of this allocator
* @line: Line number of the caller
*
* This function will free large size of memory over multiple pages.
*
* Return: None
*/
void qdf_mem_multi_pages_free_debug(qdf_device_t osdev,
struct qdf_mem_multi_page_t *pages,
qdf_dma_context_t memctxt, bool cacheable,
const char *func, uint32_t line);
/**
* qdf_mem_multi_pages_free() - free large size of kernel memory
* @osdev: OS device handle pointer
* @pages: Multi page information storage
* @memctxt: Memory context
* @cacheable: Coherent memory or cacheable memory
*
* This function will free large size of memory over multiple pages.
*
* Return: None
*/
#define qdf_mem_multi_pages_free(osdev, pages, memctxt, cacheable) \
qdf_mem_multi_pages_free_debug(osdev, pages, memctxt, cacheable, \
__func__, __LINE__)
@@ -251,47 +313,42 @@ void qdf_mem_multi_pages_free_debug(qdf_device_t osdev,
void qdf_mem_check_for_leaks(void);
/**
* qdf_mem_alloc_consistent_debug() - allocates consistent qdf memory
* qdf_mem_alloc_consistent() - allocates consistent qdf memory
* @osdev: OS device handle
* @dev: Pointer to device handle
* @size: Size to be allocated
* @paddr: Physical address
* @func: Function name of the call site
* @line: line numbe rof the call site
* @caller: Address of the caller function
*
* Return: pointer of allocated memory or null if memory alloc fails
*/
#define qdf_mem_alloc_consistent(osdev, dev, size, paddr) \
qdf_mem_alloc_consistent_debug(osdev, dev, size, paddr, \
__func__, __LINE__, QDF_RET_IP)
void *qdf_mem_alloc_consistent_debug(qdf_device_t osdev, void *dev,
qdf_size_t size, qdf_dma_addr_t *paddr,
const char *func, uint32_t line,
void *caller);
#define qdf_mem_alloc_consistent(osdev, dev, size, paddr) \
qdf_mem_alloc_consistent_debug(osdev, dev, size, paddr, \
__func__, __LINE__, QDF_RET_IP)
/**
* qdf_mem_free_consistent_debug() - free consistent qdf memory
* qdf_mem_free_consistent() - free consistent qdf memory
* @osdev: OS device handle
* @dev: OS device
* @size: Size to be allocated
* @vaddr: virtual address
* @paddr: Physical address
* @memctx: Pointer to DMA context
* @func: Function name of the call site
* @line: line numbe rof the call site
*
* Return: none
*/
#define qdf_mem_free_consistent(osdev, dev, size, vaddr, paddr, memctx) \
qdf_mem_free_consistent_debug(osdev, dev, size, vaddr, paddr, memctx, \
__func__, __LINE__)
void qdf_mem_free_consistent_debug(qdf_device_t osdev, void *dev,
qdf_size_t size, void *vaddr,
qdf_dma_addr_t paddr,
qdf_dma_context_t memctx,
const char *func, uint32_t line);
#define qdf_mem_free_consistent(osdev, dev, size, vaddr, paddr, memctx) \
qdf_mem_free_consistent_debug(osdev, dev, size, vaddr, paddr, memctx, \
__func__, __LINE__)
#else
static inline bool qdf_mem_debug_config_get(void)
{
@@ -308,7 +365,7 @@ QDF_STATUS qdf_mem_debug_disabled_config_set(const char *str_value)
* qdf_mem_malloc() - allocation QDF memory
* @size: Number of bytes of memory to allocate.
*
* This function will dynamicallly allocate the specified number of bytes of
* This function will dynamically allocate the specified number of bytes of
* memory.
*
* Return:
@@ -326,7 +383,7 @@ QDF_STATUS qdf_mem_debug_disabled_config_set(const char *str_value)
* qdf_mem_malloc_atomic() - allocation QDF memory atomically
* @size: Number of bytes of memory to allocate.
*
* This function will dynamicallly allocate the specified number of bytes of
* This function will dynamically allocate the specified number of bytes of
* memory.
*
* Return:
@@ -413,8 +470,6 @@ void qdf_mem_multi_pages_zero(struct qdf_mem_multi_page_t *pages,
* @paddr_unaligned: Unaligned physical address.
* @paddr_aligned: Aligned physical address.
* @align: Base address alignment.
* @func: Function name of the call site.
* @line: Line number of the call site.
*
* This function will dynamically allocate the specified number of bytes of
* memory. Checks if the allocated base address is aligned with base_align.
@@ -445,8 +500,6 @@ void *qdf_aligned_malloc_fl(uint32_t *size, void **vaddr_unaligned,
* @paddr_unaligned: Unaligned physical address.
* @paddr_aligned: Aligned physical address.
* @align: Base address alignment.
* @func: Function name of the call site.
* @line: Line number of the call site.
*
* Return: pointer of allocated memory or null if memory alloc fails.
*/
@@ -464,10 +517,32 @@ void *qdf_aligned_mem_alloc_consistent_fl(qdf_device_t osdev, uint32_t *size,
uint32_t align, const char *func,
uint32_t line);
#define qdf_mem_virt_to_phys(vaddr) virt_to_phys(vaddr)
/**
* qdf_mem_virt_to_phys() - Convert virtual address to physical
* @vaddr: virtual address
*
* Return: physical address
*/
#define qdf_mem_virt_to_phys(vaddr) __qdf_mem_virt_to_phys(vaddr)
/**
* qdf_mem_set_io() - set (fill) memory with a specified byte value.
* @ptr: Pointer to memory that will be set
* @value: Byte set in memory
* @num_bytes: Number of bytes to be set
*
* Return: None
*/
void qdf_mem_set_io(void *ptr, uint32_t num_bytes, uint32_t value);
/**
* qdf_mem_copy_toio() - copy memory
* @dst_addr: Pointer to destination memory location (to copy to)
* @src_addr: Pointer to source memory location (to copy from)
* @num_bytes: Number of bytes to copy.
*
* Return: none
*/
void qdf_mem_copy_toio(void *dst_addr, const void *src_addr,
uint32_t num_bytes);
@@ -525,7 +600,7 @@ void qdf_mem_copy(void *dst_addr, const void *src_addr, uint32_t num_bytes);
* Move host memory from one location to another, similar to memmove in
* standard C. Note this function *does* handle overlapping
* source and destination memory locations.
*
* Return: None
*/
void qdf_mem_move(void *dst_addr, const void *src_addr, uint32_t num_bytes);
@@ -546,6 +621,15 @@ void qdf_mem_move(void *dst_addr, const void *src_addr, uint32_t num_bytes);
*/
int qdf_mem_cmp(const void *left, const void *right, size_t size);
/**
* qdf_ether_addr_copy() - copy an Ethernet address
* @dst_addr: A six-byte array Ethernet address destination
* @src_addr: A six-byte array Ethernet address source
*
* Please note: dst & src must both be aligned to u16.
*
* Return: none
*/
void qdf_ether_addr_copy(void *dst_addr, const void *src_addr);
/**
@@ -614,9 +698,10 @@ static inline int qdf_mempool_init(qdf_device_t osdev,
}
/**
* qdf_mempool_destroy - Destroy memory pool
* qdf_mempool_destroy() - Destroy memory pool
* @osdev: platform device object
* @Handle: to memory pool
* @pool: to memory pool
*
* Return: none
*/
static inline void qdf_mempool_destroy(qdf_device_t osdev, qdf_mempool_t pool)
@@ -625,9 +710,10 @@ static inline void qdf_mempool_destroy(qdf_device_t osdev, qdf_mempool_t pool)
}
/**
* qdf_mempool_alloc - Allocate an element memory pool
* qdf_mempool_alloc() - Allocate an element memory pool
* @osdev: platform device object
* @Handle: to memory pool
* @pool: to memory pool
*
* Return: Pointer to the allocated element or NULL if the pool is empty
*/
static inline void *qdf_mempool_alloc(qdf_device_t osdev, qdf_mempool_t pool)
@@ -636,10 +722,11 @@ static inline void *qdf_mempool_alloc(qdf_device_t osdev, qdf_mempool_t pool)
}
/**
* qdf_mempool_free - Free a memory pool element
* qdf_mempool_free() - Free a memory pool element
* @osdev: Platform device object
* @pool: Handle to memory pool
* @buf: Element to be freed
*
* Return: none
*/
static inline void qdf_mempool_free(qdf_device_t osdev, qdf_mempool_t pool,
@@ -650,7 +737,6 @@ static inline void qdf_mempool_free(qdf_device_t osdev, qdf_mempool_t pool,
/**
* qdf_kmem_cache_create() - OS abstraction for cache creation
*
* @cache_name: Cache name
* @size: Size of the object to be created
*
@@ -664,8 +750,7 @@ qdf_kmem_cache_create(const char *cache_name,
}
/**
* qdf_kmem_cache_destroy() - OS abstraction for cache destructin
*
* qdf_kmem_cache_destroy() - OS abstraction for cache destruction
* @cache: Cache pointer
*
* Return: void
@@ -677,7 +762,6 @@ static inline void qdf_kmem_cache_destroy(qdf_kmem_cache_t cache)
/**
* qdf_kmem_cache_alloc() - Function to allocation object from a cache
*
* @cache: Cache address
*
* Return: Object from cache
@@ -690,9 +774,8 @@ static inline void *qdf_kmem_cache_alloc(qdf_kmem_cache_t cache)
/**
* qdf_kmem_cache_free() - Function to free cache object
*
* @cache: Cache address
* @object: Object to be returned to cache
* @node: Object to be returned to cache
*
* Return: void
*/
@@ -701,19 +784,55 @@ static inline void qdf_kmem_cache_free(qdf_kmem_cache_t cache, void *node)
__qdf_kmem_cache_free(cache, node);
}
/**
* qdf_mem_dma_sync_single_for_device() - assign memory to device
* @osdev: OS device handle
* @bus_addr: dma address to give to the device
* @size: Size of the memory block
* @direction: direction data will be DMAed
*
* Assign memory to the remote device.
* The cache lines are flushed to ram or invalidated as needed.
*
* Return: none
*/
void qdf_mem_dma_sync_single_for_device(qdf_device_t osdev,
qdf_dma_addr_t bus_addr,
qdf_size_t size,
__dma_data_direction direction);
/**
* qdf_mem_dma_sync_single_for_cpu() - assign memory to CPU
* @osdev: OS device handle
* @bus_addr: dma address to give to the cpu
* @size: Size of the memory block
* @direction: direction data will be DMAed
*
* Assign memory to the CPU.
*
* Return: none
*/
void qdf_mem_dma_sync_single_for_cpu(qdf_device_t osdev,
qdf_dma_addr_t bus_addr,
qdf_size_t size,
__dma_data_direction direction);
/**
* qdf_mem_multi_page_link() - Make links for multi page elements
* @osdev: OS device handle pointer
* @pages: Multi page information storage
* @elem_size: Single element size
* @elem_count: elements count should be linked
* @cacheable: Coherent memory or cacheable memory
*
* This function will make links for multi page allocated structure
*
* Return: 0 success
*/
int qdf_mem_multi_page_link(qdf_device_t osdev,
struct qdf_mem_multi_page_t *pages,
uint32_t elem_size, uint32_t elem_count, uint8_t cacheable);
struct qdf_mem_multi_page_t *pages,
uint32_t elem_size, uint32_t elem_count,
uint8_t cacheable);
/**
* qdf_mem_kmalloc_inc() - increment kmalloc allocated bytes count
@@ -949,7 +1068,7 @@ qdf_dma_addr_t qdf_mem_paddr_from_dmaaddr(qdf_device_t osdev,
/**
* qdf_mem_smmu_s1_enabled() - Return SMMU stage 1 translation enable status
* @osdev parent device instance
* @osdev: parent device instance
*
* Return: true if smmu s1 enabled, false if smmu s1 is bypassed
*/
@@ -1064,7 +1183,7 @@ qdf_mem_set_dma_size(qdf_device_t osdev,
}
/**
* qdf_mem_get_dma_size() - Return DMA physical address
* qdf_mem_get_dma_pa() - Return DMA physical address
* @osdev: parent device instance
* @mem_info: Pointer to allocated memory information
*
@@ -1078,7 +1197,7 @@ qdf_mem_get_dma_pa(qdf_device_t osdev,
}
/**
* qdf_mem_set_dma_size() - Set DMA physical address
* qdf_mem_set_dma_pa() - Set DMA physical address
* @osdev: parent device instance
* @mem_info: Pointer to allocated memory information
* @dma_pa: DMA phsical address
@@ -1096,13 +1215,12 @@ qdf_mem_set_dma_pa(qdf_device_t osdev,
/**
* qdf_mem_shared_mem_alloc() - Allocate DMA memory for shared resource
* @osdev: parent device instance
* @mem_info: Pointer to allocated memory information
* @size: size to be allocated
*
* Allocate DMA memory which will be shared with external kernel module. This
* information is needed for SMMU mapping.
*
* Return: 0 success
* Return: Pointer to allocated DMA memory on success, NULL on failure
*/
qdf_shared_mem_t *qdf_mem_shared_mem_alloc(qdf_device_t osdev, uint32_t size);
@@ -1318,6 +1436,11 @@ void qdf_mem_tx_desc_cnt_update(qdf_atomic_t pending_tx_descs,
*/
#define qdf_mem_valloc(size) __qdf_mem_valloc(size, __func__, __LINE__)
/**
* qdf_ioremap() - map bus memory into cpu space
* @HOST_CE_ADDRESS: bus address of the memory
* @HOST_CE_SIZE: memory size to map
*/
#define qdf_ioremap(HOST_CE_ADDRESS, HOST_CE_SIZE) \
__qdf_ioremap(HOST_CE_ADDRESS, HOST_CE_SIZE)