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 <s...@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 3b1c7528e92..9d0f27dbb3e 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.43.0
