From 937042c22a9cacef8a6cbe20360cf341d4349001 Mon Sep 17 00:00:00 2001 From: Peter Mitsis Date: Thu, 13 Oct 2016 13:18:26 -0400 Subject: [PATCH] unified: Update mem_pool doxygen style function headers Change-Id: I3b751522bbabaec5c5146cc28b85d188344a693f Signed-off-by: Peter Mitsis --- include/kernel.h | 51 ++++++++++++++++++++++++++++++++++++-- kernel/unified/mem_pool.c | 52 +++------------------------------------ 2 files changed, 53 insertions(+), 50 deletions(-) diff --git a/include/kernel.h b/include/kernel.h index 1ead09c1465..417434a61bf 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -1441,12 +1441,59 @@ static void __attribute__ ((used)) __k_mem_pool_quad_block_size_define(void) : "n"(sizeof(struct k_mem_pool_quad_block))); } +/** + * @brief Allocate memory from a memory pool + * + * @param pool Pointer to the memory pool object + * @param block Pointer to the allocated memory's block descriptor + * @param size Minimum number of bytes to allocate + * @param timeout Maximum time (milliseconds) to wait for operation to + * complete. Use K_NO_WAIT to return immediately, or K_FOREVER + * to wait as long as necessary. + * + * @return 0 on success, -ENOMEM on failure + */ extern int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block, - int size, int32_t timeout); + int size, int32_t timeout); + +/** + * @brief Return previously allocated memory to its memory pool + * + * @param block Pointer to allocated memory's block descriptor + * + * @return N/A + */ extern void k_mem_pool_free(struct k_mem_block *block); + +/** + * @brief Defragment the specified memory pool + * + * @param pool Pointer to the memory pool object + * + * @return N/A + */ extern void k_mem_pool_defrag(struct k_mem_pool *pool); + +/** + * @brief Allocate memory from heap pool + * + * This routine provides traditional malloc semantics; internally it uses + * the memory pool APIs on a dedicated HEAP pool + * + * @param size Size of memory requested by the caller (in bytes) + * + * @return Address of the allocated memory on success; otherwise NULL + */ extern void *k_malloc(uint32_t size); -extern void k_free(void *p); + +/** + * @brief Free memory allocated through k_malloc() + * + * @param ptr Pointer to previously allocated memory + * + * @return N/A + */ +extern void k_free(void *ptr); /* * legacy.h must be before arch/cpu.h to allow the ioapic/loapic drivers to diff --git a/kernel/unified/mem_pool.c b/kernel/unified/mem_pool.c index 8222df2f646..3d6b1a92e82 100644 --- a/kernel/unified/mem_pool.c +++ b/kernel/unified/mem_pool.c @@ -464,13 +464,6 @@ static void block_waiters_check(struct k_mem_pool *pool) irq_unlock(key); } - -/** - * - * @brief Perform defragment memory pool request - * - * @return N/A - */ void k_mem_pool_defrag(struct k_mem_pool *pool) { k_sched_lock(); @@ -483,13 +476,6 @@ void k_mem_pool_defrag(struct k_mem_pool *pool) k_sched_unlock(); } - -/** - * - * @brief Perform allocate memory pool block request - * - * @return N/A - */ int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block, int size, int32_t timeout) { @@ -540,16 +526,6 @@ int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block, #define MALLOC_ALIGN (sizeof(uint32_t)) -/** - * @brief Allocate memory from heap pool - * - * This routine provides traditional malloc semantics; internally it uses - * the microkernel pool APIs on a dedicated HEAP pool - * - * @param size Size of memory requested by the caller. - * - * @retval address of the block if successful otherwise returns NULL - */ void *k_malloc(uint32_t size) { uint32_t new_size; @@ -586,43 +562,23 @@ void *k_malloc(uint32_t size) return ++aligned_addr; } - -/** - * - * @brief Perform return memory pool block request - * - * @param blockptr address of the memory block to be freed - * - * Marks a block belonging to a pool as free; if there are waiters that can use - * the the block it is passed to a waiting task. - * - * @return N/A - */ -void k_mem_pool_free(struct k_mem_block *blockptr) +void k_mem_pool_free(struct k_mem_block *block) { int offset; - struct k_mem_pool *pool = blockptr->pool_id; + struct k_mem_pool *pool = block->pool_id; k_sched_lock(); /* determine block set that block belongs to */ - offset = compute_block_set_index(pool, blockptr->req_size); + offset = compute_block_set_index(pool, block->req_size); /* mark the block as unused */ - free_existing_block(blockptr->addr_in_pool, pool, offset); + free_existing_block(block->addr_in_pool, pool, offset); /* reschedule anybody waiting for a block */ block_waiters_check(pool); k_sched_unlock(); } - -/** - * @brief Free memory allocated through task_malloc - * - * @param ptr pointer to be freed - * - * @return NA - */ void k_free(void *ptr) { struct k_mem_block mem_block;