efi_loader: fix description of memory functions

* Add missing function descriptions
* Adjust to Sphinx style

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Reviewed-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>

diff --git a/lib/efi_loader/efi_memory.c b/lib/efi_loader/efi_memory.c
index 32254d24337e4e46f448fd5bc8220581efdec423..b7bee98f79c31b6578610283a41af390db17035a 100644 (file)
--- a/lib/efi_loader/efi_memory.c
+++ b/lib/efi_loader/efi_memory.c
@@ -78,12 +78,19 @@ static u64 checksum(struct efi_pool_allocation *alloc)
        return ret;
 }
 
-/*
+/**
+ * efi_mem_cmp() - comparator function for sorting memory map
+ *
  * Sorts the memory list from highest address to lowest address
  *
  * When allocating memory we should always start from the highest
  * address chunk, so sort the memory list such that the first list
  * iterator gets the highest address and goes lower from there.
+ *
+ * @priv:      unused
+ * @a:         first memory area
+ * @b:         second memory area
+ * Return:     1 if @a is before @b, -1 if @b is before @a, 0 if equal
  */
 static int efi_mem_cmp(void *priv, struct list_head *a, struct list_head *b)
 {
@@ -98,11 +105,22 @@ static int efi_mem_cmp(void *priv, struct list_head *a, struct list_head *b)
                return -1;
 }
 
+/**
+ * desc_get_end() - get end address of memory area
+ *
+ * @desc:      memory descriptor
+ * Return:     end address + 1
+ */
 static uint64_t desc_get_end(struct efi_mem_desc *desc)
 {
        return desc->physical_start + (desc->num_pages << EFI_PAGE_SHIFT);
 }
 
+/**
+ * efi_mem_sort() - sort memory map
+ *
+ * Sort the memory map and then try to merge adjacent memory areas.
+ */
 static void efi_mem_sort(void)
 {
        struct list_head *lhandle;
@@ -148,12 +166,13 @@ static void efi_mem_sort(void)
        }
 }
 
-/** efi_mem_carve_out - unmap memory region
+/**
+ * efi_mem_carve_out() - unmap memory region
  *
  * @map:               memory map
  * @carve_desc:                memory region to unmap
  * @overlap_only_ram:  the carved out region may only overlap RAM
- * Return Value:       the number of overlapping pages which have been
+ * Return:             the number of overlapping pages which have been
  *                     removed from the map,
  *                     EFI_CARVE_NO_OVERLAP, if the regions don't overlap,
  *                     EFI_CARVE_OVERLAPS_NONRAM, if the carve and map overlap,
@@ -403,6 +422,13 @@ static efi_status_t efi_check_allocated(u64 addr, bool must_be_allocated)
        return EFI_NOT_FOUND;
 }
 
+/**
+ * efi_find_free_memory() - find free memory pages
+ *
+ * @len:       size of memory area needed
+ * @max_addr:  highest address to allocate
+ * Return:     pointer to free memory area or 0
+ */
 static uint64_t efi_find_free_memory(uint64_t len, uint64_t max_addr)
 {
        struct list_head *lhandle;
@@ -445,13 +471,13 @@ static uint64_t efi_find_free_memory(uint64_t len, uint64_t max_addr)
        return 0;
 }
 
-/*
- * Allocate memory pages.
+/**
+ * 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
+ * @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,
@@ -507,6 +533,13 @@ efi_status_t efi_allocate_pages(enum efi_allocate_type type,
        return EFI_SUCCESS;
 }
 
+/**
+ * efi_alloc() - allocate memory pages
+ *
+ * @len:               size of the memory to be allocated
+ * @memory_type:       usage type of the allocated memory
+ * Return:             pointer to the allocated memory area or NULL
+ */
 void *efi_alloc(uint64_t len, int memory_type)
 {
        uint64_t ret = 0;
@@ -552,7 +585,7 @@ efi_status_t efi_free_pages(uint64_t memory, efi_uintn_t pages)
 }
 
 /**
- * efi_alloc_aligned_pages - allocate
+ * efi_alloc_aligned_pages() - allocate aligned memory pages
  *
  * @len:               len in bytes
  * @memory_type:       usage type of the allocated memory
@@ -673,15 +706,15 @@ efi_status_t efi_free_pool(void *buffer)
        return ret;
 }
 
-/*
- * Get map describing memory usage.
+/**
+ * efi_get_memory_map() - get map describing memory usage.
  *
- * @memory_map_size    on entry the size, in bytes, of the memory map buffer,
+ * @memory_map_size:   on entry the size, in bytes, of the memory map buffer,
  *                     on exit the size of the copied memory map
- * @memory_map         buffer to which the memory map is written
- * @map_key            key for the memory map
- * @descriptor_size    size of an individual memory descriptor
- * @descriptor_version version number of the memory descriptor structure
+ * @memory_map:                buffer to which the memory map is written
+ * @map_key:           key for the memory map
+ * @descriptor_size:   size of an individual memory descriptor
+ * @descriptor_version:        version number of the memory descriptor structure
  * Return:             status code
  */
 efi_status_t efi_get_memory_map(efi_uintn_t *memory_map_size,
@@ -741,8 +774,8 @@ efi_status_t efi_get_memory_map(efi_uintn_t *memory_map_size,
  *
  * The caller is responsible for calling FreePool() if the call succeeds.
  *
- * @memory_map         buffer to which the memory map is written
- * @map_size           size of the memory map
+ * @map_size:          size of the memory map
+ * @memory_map:                buffer to which the memory map is written
  * Return:             status code
  */
 efi_status_t efi_get_memory_map_alloc(efi_uintn_t *map_size,
@@ -818,6 +851,11 @@ efi_status_t efi_add_conventional_memory_map(u64 ram_start, u64 ram_end,
        return EFI_SUCCESS;
 }
 
+/**
+ * efi_add_known_memory() - add memory banks to map
+ *
+ * This function may be overridden for specific architectures.
+ */
 __weak void efi_add_known_memory(void)
 {
        u64 ram_top = board_get_usable_ram_top(0) & ~EFI_PAGE_MASK;
@@ -844,7 +882,11 @@ __weak void efi_add_known_memory(void)
        }
 }
 
-/* Add memory regions for U-Boot's memory and for the runtime services code */
+/**
+ * add_u_boot_and_runtime() - add U-Boot code to memory map
+ *
+ * Add memory regions for U-Boot's memory and for the runtime services code.
+ */
 static void add_u_boot_and_runtime(void)
 {
        unsigned long runtime_start, runtime_end, runtime_pages;