There was a discussion recently on whether this should be in the .h or .c
But I don't really mind as long as we have a common policy
On Sun, 8 Dec 2024 at 02:21, Sam Protsenko semen.protsenko@linaro.org wrote:
Fix warnings from kernel-doc script. Improve and unify overall style of kernel-doc comments in lmb source files. Move all kernel-doc comments for public functions into the header, as recommended in U-Boot documentation, which also takes care of existing duplication. While at it, do a bit of cosmetic cleanups as well.
No functional change.
Signed-off-by: Sam Protsenko semen.protsenko@linaro.org
include/lmb.h | 125 ++++++++++++++++++++++++++++++-------------------- lib/lmb.c | 55 ---------------------- 2 files changed, 74 insertions(+), 106 deletions(-)
diff --git a/include/lmb.h b/include/lmb.h index f221f0cce8f7..03d5fac6aa79 100644 --- a/include/lmb.h +++ b/include/lmb.h @@ -1,6 +1,13 @@ /* SPDX-License-Identifier: GPL-2.0+ */ +/*
- Logical memory blocks.
- Copyright (C) 2001 Peter Bergner, IBM Corp.
- */
#ifndef _LINUX_LMB_H #define _LINUX_LMB_H
#ifdef __KERNEL__
#include <alist.h> @@ -8,21 +15,15 @@ #include <asm/u-boot.h> #include <linux/bitops.h>
-/*
- Logical memory blocks.
- Copyright (C) 2001 Peter Bergner, IBM Corp.
- */
-#define LMB_ALLOC_ANYWHERE 0 -#define LMB_ALIST_INITIAL_SIZE 4 +#define LMB_ALLOC_ANYWHERE 0 +#define LMB_ALIST_INITIAL_SIZE 4
/**
- enum lmb_flags - definition of memory region attributes
- @LMB_NONE: no special request
- @LMB_NOMAP: don't add to mmu configuration
- @LMB_NOOVERWRITE: the memory region cannot be overwritten/re-reserved
- @LMB_NONOTIFY: do not notify other modules of changes to this memory region
- enum lmb_flags - Definition of memory region attributes
- @LMB_NONE: No special request
- @LMB_NOMAP: Don't add to MMU configuration
- @LMB_NOOVERWRITE: The memory region cannot be overwritten/re-reserved
*/
- @LMB_NONOTIFY: Do not notify other modules of changes to this memory region
enum lmb_flags { LMB_NONE = 0, @@ -32,11 +33,10 @@ enum lmb_flags { };
/**
- struct lmb_region - Description of one region.
- @base: Base address of the region.
- @size: Size of the region
- @flags: memory region attributes
- struct lmb_region - Description of one region
- @base: Base address of the region
- @size: Size of the region
*/
- @flags: Memory region attributes
struct lmb_region { phys_addr_t base; @@ -46,10 +46,9 @@ struct lmb_region {
/**
- struct lmb - The LMB structure
- @free_mem: List of free memory regions
- @used_mem: List of used/reserved memory regions
- @test: Is structure being used for LMB tests
- @free_mem: List of free memory regions
- @used_mem: List of used/reserved memory regions
*/
- @test: Is structure being used for LMB tests
struct lmb { struct alist free_mem; @@ -58,51 +57,77 @@ struct lmb { };
/**
- lmb_init() - Initialise the LMB module
- lmb_init() - Initialise the LMB module.
- Return: 0 on success, negative error code on failure.
- Initialise the LMB lists needed for keeping the memory map. There
- are two lists, in form of alloced list data structure. One for the
- are two lists, in form of allocated list data structure. One for the
- available memory, and one for the used memory. Initialise the two
- lists as part of board init. Add memory to the available memory
- list and reserve common areas by adding them to the used memory
- list.
*/
- Return: 0 on success, -ve on error
int lmb_init(void);
/**
- lmb_add_memory() - Add memory range for LMB allocations
- lmb_add_memory() - Add memory range for LMB allocations.
- Add the entire available memory range to the pool of memory that
- can be used by the LMB module for allocations.
*/
- Return: None
void lmb_add_memory(void);
long lmb_add(phys_addr_t base, phys_size_t size); -long lmb_reserve(phys_addr_t base, phys_size_t size);
/**
- lmb_reserve_flags - Reserve one region with a specific flags bitfield.
- lmb_reserve() - Reserve a memory region (with no special flags)
- @base: Base address of the memory region
- @size: Size of the memory region
- @base: base address of the memory region
- @size: size of the memory region
- @flags: flags for the memory region
- Return: 0 if OK, > 0 for coalesced region or a negative error code.
- Return: 0 on success, negative error code on failure.
- */
+long lmb_reserve(phys_addr_t base, phys_size_t size);
+/**
- lmb_reserve_flags() - Reserve one region with a specific flags bitfield
- @base: Base address of the memory region
- @size: Size of the memory region
- @flags: Flags for the memory region
- Return:
- %0 - Added successfully, or it's already added (only if LMB_NONE)
- %-EEXIST - The region is already added, and flags != LMB_NONE
*/
- %-1 - Failure
long lmb_reserve_flags(phys_addr_t base, phys_size_t size, enum lmb_flags flags);
phys_addr_t lmb_alloc(phys_size_t size, ulong align); phys_addr_t lmb_alloc_base(phys_size_t size, ulong align, phys_addr_t max_addr); phys_addr_t lmb_alloc_addr(phys_addr_t base, phys_size_t size); phys_size_t lmb_get_free_size(phys_addr_t addr);
+/**
- lmb_alloc_base_flags() - Allocate specified memory region with specified
attributes
- @size: Size of the region requested
- @align: Alignment of the memory region requested
- @max_addr: Maximum address of the requested region
- @flags: Memory region attributes to be set
- Allocate a region of memory with the attributes specified through the
- parameter. The max_addr parameter is used to specify the maximum address
- below which the requested region should be allocated.
- Return: Base address on success, 0 on error.
- */
phys_addr_t lmb_alloc_base_flags(phys_size_t size, ulong align, phys_addr_t max_addr, uint flags);
/**
- lmb_alloc_addr_flags() - Allocate specified memory address with specified attributes
- lmb_alloc_addr_flags() - Allocate specified memory address with specified
attributes- @base: Base Address requested
- @size: Size of the region requested
- @flags: Memory region attributes to be set
@@ -111,20 +136,21 @@ phys_addr_t lmb_alloc_base_flags(phys_size_t size, ulong align,
- parameter. The base parameter is used to specify the base address
- of the requested region.
- Return: base address on success, 0 on error
*/
- Return: Base address on success, 0 on error.
phys_addr_t lmb_alloc_addr_flags(phys_addr_t base, phys_size_t size, uint flags);
/**
- lmb_is_reserved_flags() - test if address is in reserved region with flag bits set
- lmb_is_reserved_flags() - Test if address is in reserved region with flag
bits set
- @addr: Address to be tested
- @flags: Bitmap with bits to be tested
- The function checks if a reserved region comprising @addr exists which has
- all flag bits set which are set in @flags.
- @addr: address to be tested
- @flags: bitmap with bits to be tested
- Return: 1 if matching reservation exists, 0 otherwise
*/
- Return: 1 if matching reservation exists, 0 otherwise.
int lmb_is_reserved_flags(phys_addr_t addr, int flags);
@@ -134,9 +160,7 @@ int lmb_is_reserved_flags(phys_addr_t addr, int flags);
- @size: Size of the region to be freed
- @flags: Memory region attributes
- Free up a region of memory.
- Return: 0 if successful, -1 on failure
*/
- Return: 0 on success, negative error code on failure.
long lmb_free_flags(phys_addr_t base, phys_size_t size, uint flags);
@@ -160,7 +184,7 @@ static inline int lmb_read_check(phys_addr_t addr, phys_size_t len)
- io_lmb_setup() - Initialize LMB struct
- @io_lmb: IO LMB to initialize
- Returns: 0 on success, negative error code on failure
*/
- Return: 0 on success, negative error code on failure.
int io_lmb_setup(struct lmb *io_lmb);
@@ -178,12 +202,13 @@ void io_lmb_teardown(struct lmb *io_lmb);
- Add the IOVA space [base, base + size] to be managed by io_lmb.
- Returns: 0 if the region addition was successful, -1 on failure
*/
- Return: 0 on success, negative error code on failure.
long io_lmb_add(struct lmb *io_lmb, phys_addr_t base, phys_size_t size);
/**
- io_lmb_alloc() - Allocate specified IO memory address with specified alignment
- io_lmb_alloc() - Allocate specified IO memory address with specified
alignment- @io_lmb: LMB to alloc from
- @size: Size of the region requested
- @align: Required address and size alignment
@@ -191,7 +216,7 @@ long io_lmb_add(struct lmb *io_lmb, phys_addr_t base, phys_size_t size);
- Allocate a region of IO memory. The base parameter is used to specify the
- base address of the requested region.
- Return: base IO address on success, 0 on error
*/
- Return: Base IO address on success, 0 on error.
phys_addr_t io_lmb_alloc(struct lmb *io_lmb, phys_size_t size, ulong align);
@@ -201,9 +226,7 @@ phys_addr_t io_lmb_alloc(struct lmb *io_lmb, phys_size_t size, ulong align);
- @base: Base Address of region to be freed
- @size: Size of the region to be freed
- Free up a region of IOVA space.
- Return: 0 if successful, -1 on failure
*/
- Return: 0 on success, negative error code on failure.
long io_lmb_free(struct lmb *io_lmb, phys_addr_t base, phys_size_t size);
diff --git a/lib/lmb.c b/lib/lmb.c index 8c1c9b0f67c8..eee3bd37d446 100644 --- a/lib/lmb.c +++ b/lib/lmb.c @@ -609,14 +609,6 @@ static __maybe_unused void lmb_reserve_common_spl(void) } }
-/**
- lmb_add_memory() - Add memory range for LMB allocations
- Add the entire available memory range to the pool of memory that
- can be used by the LMB module for allocations.
- Return: None
- */
void lmb_add_memory(void) { int i; @@ -673,16 +665,6 @@ long lmb_add(phys_addr_t base, phys_size_t size) return lmb_map_update_notify(base, size, MAP_OP_ADD, LMB_NONE); }
-/**
- lmb_free_flags() - Free up a region of memory
- @base: Base Address of region to be freed
- @size: Size of the region to be freed
- @flags: Memory region attributes
- Free up a region of memory.
- Return: 0 if successful, negative error code on failure
- */
long lmb_free_flags(phys_addr_t base, phys_size_t size, uint flags) { @@ -790,19 +772,6 @@ phys_addr_t lmb_alloc_base(phys_size_t size, ulong align, phys_addr_t max_addr) return alloc; }
-/**
- lmb_alloc_base_flags() - Allocate specified memory region with specified attributes
- @size: Size of the region requested
- @align: Alignment of the memory region requested
- @max_addr: Maximum address of the requested region
- @flags: Memory region attributes to be set
- Allocate a region of memory with the attributes specified through the
- parameter. The max_addr parameter is used to specify the maximum address
- below which the requested region should be allocated.
- Return: base address on success, 0 on error
- */
phys_addr_t lmb_alloc_base_flags(phys_size_t size, ulong align, phys_addr_t max_addr, uint flags) { @@ -851,18 +820,6 @@ phys_addr_t lmb_alloc_addr(phys_addr_t base, phys_size_t size) return _lmb_alloc_addr(base, size, LMB_NONE); }
-/**
- lmb_alloc_addr_flags() - Allocate specified memory address with specified attributes
- @base: Base Address requested
- @size: Size of the region requested
- @flags: Memory region attributes to be set
- Allocate a region of memory with the attributes specified through the
- parameter. The base parameter is used to specify the base address
- of the requested region.
- Return: base address on success, 0 on error
- */
phys_addr_t lmb_alloc_addr_flags(phys_addr_t base, phys_size_t size, uint flags) { @@ -935,18 +892,6 @@ static int lmb_setup(bool test) return 0; }
-/**
- lmb_init() - Initialise the LMB module
- Initialise the LMB lists needed for keeping the memory map. There
- are two lists, in form of alloced list data structure. One for the
- available memory, and one for the used memory. Initialise the two
- lists as part of board init. Add memory to the available memory
- list and reserve common areas by adding them to the used memory
- list.
- Return: 0 on success, -ve on error
- */
int lmb_init(void) { int ret; -- 2.39.5
Acked-by: Ilias Apalodimas ilias.apalodimas@linaro.org