There was discussion about this and I am not sure what people prefer. What I do care about is that this has no place in this patchset. Please send it separately.
Thanks /Ilias On Wed, 11 Dec 2024 at 15:54, Simon Glass <[email protected]> wrote: > > Exported functions should be documented in the header file, not the > implementation. We tend to make such updates on a piecemeal basis to > avoid a 'flag day'. Move some comments related to memory allocation to > follow the convention. > > Signed-off-by: Simon Glass <[email protected]> > --- > > (no changes since v2) > > Changes in v2: > - Rebase on early patch > > include/efi_loader.h | 77 +++++++++++++++++++++++++++++++---- > lib/efi_loader/efi_memory.c | 81 ------------------------------------- > 2 files changed, 69 insertions(+), 89 deletions(-) > > diff --git a/include/efi_loader.h b/include/efi_loader.h > index ee0cdd36500..00a1259c006 100644 > --- a/include/efi_loader.h > +++ b/include/efi_loader.h > @@ -758,21 +758,68 @@ efi_status_t efi_next_variable_name(efi_uintn_t *size, > u16 **buf, > * Return: size in pages > */ > #define efi_size_in_pages(size) (((size) + EFI_PAGE_MASK) >> EFI_PAGE_SHIFT) > -/* Allocate boot service data pool memory */ > + > +/** > + * efi_alloc() - allocate boot-services-data pool-memory > + * > + * Allocate memory from pool and zero it out. > + * > + * @size: number of bytes to allocate > + * Return: pointer to allocated memory or NULL > + */ > void *efi_alloc(size_t len); > -/* Allocate pages on the specified alignment */ > + > +/** > + * efi_alloc_aligned_pages() - allocate aligned memory pages > + * > + * @len: len in bytes > + * @memory_type: usage type of the allocated memory > + * @align: alignment in bytes > + * Return: aligned memory or NULL > + */ > void *efi_alloc_aligned_pages(u64 len, int memory_type, size_t align); > -/* More specific EFI memory allocator, called by EFI payloads */ > + > +/** > + * efi_allocate_pages - allocate memory pages > + * > + * @type: type of allocation to be performed > + * @memory_type: usage type of the allocated memory > + * @pages: number of pages to be allocated > + * @memory: returns a pointer to the allocated memory > + * Return: status code > + */ > efi_status_t efi_allocate_pages(enum efi_allocate_type type, > enum efi_memory_type memory_type, > efi_uintn_t pages, uint64_t *memory); > -/* EFI memory free function. */ > + > +/** > + * efi_free_pages() - free memory pages > + * > + * @memory: start of the memory area to be freed > + * @pages: number of pages to be freed > + * Return: status code > + */ > efi_status_t efi_free_pages(uint64_t memory, efi_uintn_t pages); > -/* EFI memory allocator for small allocations */ > + > +/** > + * efi_allocate_pool - allocate memory from pool > + * > + * @pool_type: type of the pool from which memory is to be allocated > + * @size: number of bytes to be allocated > + * @buffer: allocated memory > + * Return: status code > + */ > efi_status_t efi_allocate_pool(enum efi_memory_type pool_type, > efi_uintn_t size, void **buffer); > -/* EFI pool memory free function. */ > + > +/** > + * efi_free_pool() - free memory from pool > + * > + * @buffer: start of memory to be freed > + * Return: status code > + */ > efi_status_t efi_free_pool(void *buffer); > + > /* Allocate and retrieve EFI memory map */ > efi_status_t efi_get_memory_map_alloc(efi_uintn_t *map_size, > struct efi_mem_desc **memory_map); > @@ -782,7 +829,21 @@ efi_status_t efi_get_memory_map(efi_uintn_t > *memory_map_size, > efi_uintn_t *map_key, > efi_uintn_t *descriptor_size, > uint32_t *descriptor_version); > -/* Adds a range into the EFI memory map */ > + > +/** > + * efi_add_memory_map() - add memory area to the memory map > + * > + * @start: start address of the memory area. Note that this is > + * actually a pointer provided as an integer. To pass in > + * an address, pass in (ulong)map_to_sysmem(addr) > + * @size: length in bytes of the memory area > + * @memory_type: type of memory added > + * > + * Return: status code > + * > + * This function automatically aligns the start and size of the memory area > + * to EFI_PAGE_SIZE. > + */ > efi_status_t efi_add_memory_map(u64 start, u64 size, int memory_type); > > /** > @@ -793,7 +854,7 @@ efi_status_t efi_add_memory_map(u64 start, u64 size, int > memory_type); > * in (ulong)map_to_sysmem(addr) > * > * @pages: number of pages to add > - * @memory_type: type of memory added > + * @memory_type: EFI type of memory added > * @overlap_conventional: region may only overlap free(conventional) > * memory > * Return: status code > diff --git a/lib/efi_loader/efi_memory.c b/lib/efi_loader/efi_memory.c > index f1154f73e05..4bc6d12a1fe 100644 > --- a/lib/efi_loader/efi_memory.c > +++ b/lib/efi_loader/efi_memory.c > @@ -257,17 +257,6 @@ static s64 efi_mem_carve_out(struct efi_mem_list *map, > return EFI_CARVE_LOOP_AGAIN; > } > > -/** > - * efi_add_memory_map_pg() - add pages to the memory map > - * > - * @start: start address, must be a multiple of > - * EFI_PAGE_SIZE > - * @pages: number of pages to add > - * @memory_type: type of memory added > - * @overlap_conventional: region may only overlap free(conventional) > - * memory > - * Return: status code > - */ > efi_status_t efi_add_memory_map_pg(u64 start, u64 pages, > int memory_type, > bool overlap_conventional) > @@ -381,20 +370,6 @@ efi_status_t efi_add_memory_map_pg(u64 start, u64 pages, > return EFI_SUCCESS; > } > > -/** > - * efi_add_memory_map() - add memory area to the memory map > - * > - * @start: start address of the memory area. Note that this is > - * actually a pointer provided as an integer. To pass in > - * an address, pass in (ulong)map_to_sysmem(addr) > - * @size: length in bytes of the memory area > - * @memory_type: type of memory added > - * > - * Return: status code > - * > - * This function automatically aligns the start and size of the memory area > - * to EFI_PAGE_SIZE. > - */ > efi_status_t efi_add_memory_map(u64 start, u64 size, int memory_type) > { > u64 pages; > @@ -440,15 +415,6 @@ static efi_status_t efi_check_allocated(u64 addr, bool > must_be_allocated) > return EFI_NOT_FOUND; > } > > -/** > - * efi_allocate_pages - allocate memory pages > - * > - * @type: type of allocation to be performed > - * @memory_type: usage type of the allocated memory > - * @pages: number of pages to be allocated > - * @memory: allocated memory > - * Return: status code > - */ > efi_status_t efi_allocate_pages(enum efi_allocate_type type, > enum efi_memory_type memory_type, > efi_uintn_t pages, uint64_t *memory) > @@ -516,13 +482,6 @@ efi_status_t efi_allocate_pages(enum efi_allocate_type > type, > return EFI_SUCCESS; > } > > -/** > - * efi_free_pages() - free memory pages > - * > - * @memory: start of the memory area to be freed > - * @pages: number of pages to be freed > - * Return: status code > - */ > efi_status_t efi_free_pages(uint64_t memory, efi_uintn_t pages) > { > u64 len; > @@ -556,14 +515,6 @@ efi_status_t efi_free_pages(uint64_t memory, efi_uintn_t > pages) > return ret; > } > > -/** > - * efi_alloc_aligned_pages() - allocate aligned memory pages > - * > - * @len: len in bytes > - * @memory_type: usage type of the allocated memory > - * @align: alignment in bytes > - * Return: aligned memory or NULL > - */ > void *efi_alloc_aligned_pages(u64 len, int memory_type, size_t align) > { > u64 req_pages = efi_size_in_pages(len); > @@ -608,14 +559,6 @@ void *efi_alloc_aligned_pages(u64 len, int memory_type, > size_t align) > return (void *)(uintptr_t)aligned_mem; > } > > -/** > - * efi_allocate_pool - allocate memory from pool > - * > - * @pool_type: type of the pool from which memory is to be allocated > - * @size: number of bytes to be allocated > - * @buffer: allocated memory > - * Return: status code > - */ > efi_status_t efi_allocate_pool(enum efi_memory_type pool_type, efi_uintn_t > size, void **buffer) > { > efi_status_t r; > @@ -644,14 +587,6 @@ efi_status_t efi_allocate_pool(enum efi_memory_type > pool_type, efi_uintn_t size, > return r; > } > > -/** > - * efi_alloc() - allocate boot services data pool memory > - * > - * Allocate memory from pool and zero it out. > - * > - * @size: number of bytes to allocate > - * Return: pointer to allocated memory or NULL > - */ > void *efi_alloc(size_t size) > { > void *buf; > @@ -666,12 +601,6 @@ void *efi_alloc(size_t size) > return buf; > } > > -/** > - * efi_free_pool() - free memory from pool > - * > - * @buffer: start of memory to be freed > - * Return: status code > - */ > efi_status_t efi_free_pool(void *buffer) > { > efi_status_t ret; > @@ -793,16 +722,6 @@ efi_status_t efi_get_memory_map_alloc(efi_uintn_t > *map_size, > return ret; > } > > -/** > - * efi_add_known_memory() - add memory types to the EFI memory map > - * > - * This function is to be used to add different memory types other > - * than EFI_CONVENTIONAL_MEMORY to the EFI memory map. The conventional > - * memory is handled by the LMB module and gets added to the memory > - * map through the LMB module. > - * > - * This function may be overridden for architectures specific purposes. > - */ > __weak void efi_add_known_memory(void) > { > } > -- > 2.34.1 >
