From 5c829783e5f8dbb7ca6fce50c5c4a33f7c75d0d4 Mon Sep 17 00:00:00 2001 From: Christoph Hellwig Date: Thu, 13 Nov 2025 09:39:44 +0100 Subject: [PATCH] mempool: improve kerneldoc comments Use proper formatting, use full sentences and reduce some verbosity in function parameter descriptions. Signed-off-by: Christoph Hellwig Link: https://patch.msgid.link/20251113084022.1255121-4-hch@lst.de Signed-off-by: Vlastimil Babka --- mm/mempool.c | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/mm/mempool.c b/mm/mempool.c index 1c38e873e546f..1f47017132036 100644 --- a/mm/mempool.c +++ b/mm/mempool.c @@ -372,18 +372,20 @@ out: EXPORT_SYMBOL(mempool_resize); /** - * mempool_alloc - allocate an element from a specific memory pool - * @pool: pointer to the memory pool which was allocated via - * mempool_create(). - * @gfp_mask: the usual allocation bitmask. + * mempool_alloc - allocate an element from a memory pool + * @pool: pointer to the memory pool + * @gfp_mask: GFP_* flags. %__GFP_ZERO is not supported. * - * this function only sleeps if the alloc_fn() function sleeps or - * returns NULL. Note that due to preallocation, this function - * *never* fails when called from process contexts. (it might - * fail if called from an IRQ context.) - * Note: using __GFP_ZERO is not supported. + * Allocate an element from @pool. This is done by first calling into the + * alloc_fn supplied at pool initialization time, and dipping into the reserved + * pool when alloc_fn fails to allocate an element. * - * Return: pointer to the allocated element or %NULL on error. + * This function only sleeps if the alloc_fn callback sleeps, or when waiting + * for elements to become available in the pool. + * + * Return: pointer to the allocated element or %NULL when failing to allocate + * an element. Allocation failure can only happen when @gfp_mask does not + * include %__GFP_DIRECT_RECLAIM. */ void *mempool_alloc_noprof(mempool_t *pool, gfp_t gfp_mask) { @@ -456,11 +458,10 @@ EXPORT_SYMBOL(mempool_alloc_noprof); /** * mempool_alloc_preallocated - allocate an element from preallocated elements - * belonging to a specific memory pool - * @pool: pointer to the memory pool which was allocated via - * mempool_create(). + * belonging to a memory pool + * @pool: pointer to the memory pool * - * This function is similar to mempool_alloc, but it only attempts allocating + * This function is similar to mempool_alloc(), but it only attempts allocating * an element from the preallocated elements. It does not sleep and immediately * returns if no preallocated elements are available. * @@ -492,12 +493,14 @@ void *mempool_alloc_preallocated(mempool_t *pool) EXPORT_SYMBOL(mempool_alloc_preallocated); /** - * mempool_free - return an element to the pool. - * @element: pool element pointer. - * @pool: pointer to the memory pool which was allocated via - * mempool_create(). + * mempool_free - return an element to a mempool + * @element: pointer to element + * @pool: pointer to the memory pool + * + * Returns @element to @pool if it needs replenishing, else frees it using + * the free_fn callback in @pool. * - * this function only sleeps if the free_fn() function sleeps. + * This function only sleeps if the free_fn callback sleeps. */ void mempool_free(void *element, mempool_t *pool) { -- 2.47.3