[PATCH v5 06/23] efi_loader: Move some memory-function comments to header
Ilias Apalodimas
ilias.apalodimas at linaro.org
Wed Dec 11 15:51:55 CET 2024
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 <sjg at chromium.org> 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 <sjg at chromium.org>
> ---
>
> (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
>
More information about the U-Boot
mailing list