On Sun, Jan 08, 2023 at 01:00:00AM +0100, Heinrich Schuchardt wrote: > * Add missing function descriptions > * Adjust to Sphinx style > > Signed-off-by: Heinrich Schuchardt <heinrich.schucha...@canonical.com> > --- > lib/efi_loader/efi_memory.c | 82 ++++++++++++++++++++++++++++--------- > 1 file changed, 62 insertions(+), 20 deletions(-) > > diff --git a/lib/efi_loader/efi_memory.c b/lib/efi_loader/efi_memory.c > index 32254d2433..a108427d72 100644 > --- 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; > -- > 2.37.2 >
Reviewed-by: Ilias Apalodimas <ilias.apalodi...@linaro.org>