On 25.11.24 21:44, Simon Glass 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@chromium.org
Please, have a look at this line in doc/
doc/api/efi.rst:78: .. kernel-doc:: lib/efi_loader/efi_memory.c
Should we use a separate header efi_memory.h?
Best regards
Heinrich
include/efi_loader.h | 70 ++++++++++++++++++++++++++++++++----- lib/efi_loader/efi_memory.c | 62 -------------------------------- 2 files changed, 62 insertions(+), 70 deletions(-)
diff --git a/include/efi_loader.h b/include/efi_loader.h index 39809eac1bc..ff7adc1e2a2 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,14 @@ 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 a range into the EFI memory map
- @start: start address, must be a multiple of EFI_PAGE_SIZE
- @size: Size, in bytes
- @memory_type: EFI type of memory added
- Return: status code
*/ efi_status_t efi_add_memory_map(u64 start, u64 size, int memory_type);
/**
@@ -791,7 +845,7 @@ efi_status_t efi_add_memory_map(u64 start, u64 size, int memory_type);
- @start: start address, must be a multiple of
EFI_PAGE_SIZE- @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 8b01821a993..7c8d9485094 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,18 +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
- @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;
@@ -438,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)
@@ -554,14 +522,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);
@@ -606,14 +566,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;
@@ -642,14 +594,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;
@@ -664,12 +608,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;