efi_loader: document runtime functions

Add comments for runtime service functions.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Alexander Graf <agraf@suse.de>

1 files changed, 149 insertions, 4 deletions

diff --git a/lib/efi_loader/efi_runtime.c b/lib/efi_loader/efi_runtime.c
index 633e4cc3e5..27136cbedd 100644
--- a/lib/efi_loader/efi_runtime.c
+++ b/lib/efi_loader/efi_runtime.c
@@ -96,6 +96,20 @@ void __efi_runtime efi_update_table_header_crc32(struct efi_table_hdr *table)
 			     table->headersize);
 }
 
+/**
+ * efi_reset_system_boottime() - reset system at boottime
+ *
+ * This function implements the ResetSystem() runtime service before
+ * SetVirtualAddressMap() is called.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification for
+ * details.
+ *
+ * @reset_type:		type of reset to perform
+ * @reset_status:	status code for the reset
+ * @data_size:		size of reset_data
+ * @reset_data:		information about the reset
+ */
 static void EFIAPI efi_reset_system_boottime(
 			enum efi_reset_type reset_type,
 			efi_status_t reset_status,
@@ -130,15 +144,17 @@ static void EFIAPI efi_reset_system_boottime(
 }
 
 /**
- * efi_get_time_boottime - get current time
+ * efi_get_time_boottime() - get current time at boottime
+ *
+ * This function implements the GetTime runtime service before
+ * SetVirtualAddressMap() is called.
  *
- * This function implements the GetTime runtime service.
  * See the Unified Extensible Firmware Interface (UEFI) specification
  * for details.
  *
  * @time:		pointer to structure to receive current time
  * @capabilities:	pointer to structure to receive RTC properties
- * Return Value:	status code
+ * Returns:		status code
  */
 static efi_status_t EFIAPI efi_get_time_boottime(
 			struct efi_time *time,
@@ -191,8 +207,22 @@ out:
 #endif
 }
 
-/* Boards may override the helpers below to implement RTS functionality */
 
+/**
+ * efi_reset_system() - reset system
+ *
+ * This function implements the ResetSystem() runtime service after
+ * SetVirtualAddressMap() is called. It only executes an endless loop.
+ * Boards may override the helpers below to implement reset functionality.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification for
+ * details.
+ *
+ * @reset_type:		type of reset to perform
+ * @reset_status:	status code for the reset
+ * @data_size:		size of reset_data
+ * @reset_data:		information about the reset
+ */
 void __weak __efi_runtime EFIAPI efi_reset_system(
 			enum efi_reset_type reset_type,
 			efi_status_t reset_status,
@@ -202,11 +232,30 @@ void __weak __efi_runtime EFIAPI efi_reset_system(
 	while (1) { }
 }
 
+/**
+ * efi_reset_system_init() - initialize the reset driver
+ *
+ * Boards may override this function to initialize the reset driver.
+ */
 efi_status_t __weak efi_reset_system_init(void)
 {
 	return EFI_SUCCESS;
 }
 
+/**
+ * efi_get_time() - get current time
+ *
+ * This function implements the GetTime runtime service after
+ * SetVirtualAddressMap() is called. As the U-Boot driver are not available
+ * anymore only an error code is returned.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification
+ * for details.
+ *
+ * @time:		pointer to structure to receive current time
+ * @capabilities:	pointer to structure to receive RTC properties
+ * Returns:		status code
+ */
 efi_status_t __weak __efi_runtime EFIAPI efi_get_time(
 			struct efi_time *time,
 			struct efi_time_cap *capabilities)
@@ -353,6 +402,20 @@ void efi_runtime_relocate(ulong offset, struct efi_mem_desc *map)
         invalidate_icache_all();
 }
 
+/**
+ * efi_set_virtual_address_map() - change from physical to virtual mapping
+ *
+ * This function implements the SetVirtualAddressMap() runtime service.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification for
+ * details.
+ *
+ * @memory_map_size:	size of the virtual map
+ * @descriptor_size:	size of an entry in the map
+ * @descriptor_version:	version of the map entries
+ * @virtmap:		virtual address mapping information
+ * Return:		status code
+ */
 static efi_status_t EFIAPI efi_set_virtual_address_map(
 			unsigned long memory_map_size,
 			unsigned long descriptor_size,
@@ -419,6 +482,16 @@ static efi_status_t EFIAPI efi_set_virtual_address_map(
 	return EFI_EXIT(EFI_INVALID_PARAMETER);
 }
 
+/**
+ * efi_add_runtime_mmio() - add memory-mapped IO region
+ *
+ * This function adds a memory-mapped IO region to the memory map to make it
+ * available at runtime.
+ *
+ * @mmio_ptr:		address of the memory-mapped IO region
+ * @len:		size of thememory-mapped IO region
+ * Returns:		status code
+ */
 efi_status_t efi_add_runtime_mmio(void *mmio_ptr, u64 len)
 {
 	struct efi_runtime_mmio_list *newmmio;
@@ -461,21 +534,61 @@ efi_status_t efi_add_runtime_mmio(void *mmio_ptr, u64 len)
  * address map calls.
  */
 
+/**
+ * efi_unimplemented() - replacement function, returns EFI_UNSUPPORTED
+ *
+ * This function is used after SetVirtualAddressMap() is called as replacement
+ * for services that are not available anymore due to constraints of the U-Boot
+ * implementation.
+ *
+ * Return:	EFI_UNSUPPORTED
+ */
 static efi_status_t __efi_runtime EFIAPI efi_unimplemented(void)
 {
 	return EFI_UNSUPPORTED;
 }
 
+/**
+ * efi_device_error() - replacement function, returns EFI_DEVICE_ERROR
+ *
+ * This function is used after SetVirtualAddressMap() is called as replacement
+ * for services that are not available anymore due to constraints of the U-Boot
+ * implementation.
+ *
+ * Return:	EFI_DEVICE_ERROR
+ */
 static efi_status_t __efi_runtime EFIAPI efi_device_error(void)
 {
 	return EFI_DEVICE_ERROR;
 }
 
+/**
+ * efi_invalid_parameter() - replacement function, returns EFI_INVALID_PARAMETER
+ *
+ * This function is used after SetVirtualAddressMap() is called as replacement
+ * for services that are not available anymore due to constraints of the U-Boot
+ * implementation.
+ *
+ * Return:	EFI_INVALID_PARAMETER
+ */
 static efi_status_t __efi_runtime EFIAPI efi_invalid_parameter(void)
 {
 	return EFI_INVALID_PARAMETER;
 }
 
+/**
+ * efi_update_capsule() - process information from operating system
+ *
+ * This function implements the UpdateCapsule() runtime service.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification for
+ * details.
+ *
+ * @capsule_header_array:	pointer to array of virtual pointers
+ * @capsule_count:		number of pointers in capsule_header_array
+ * @scatter_gather_list:	pointer to arry of physical pointers
+ * Returns:			status code
+ */
 efi_status_t __efi_runtime EFIAPI efi_update_capsule(
 			struct efi_capsule_header **capsule_header_array,
 			efi_uintn_t capsule_count,
@@ -484,6 +597,20 @@ efi_status_t __efi_runtime EFIAPI efi_update_capsule(
 	return EFI_UNSUPPORTED;
 }
 
+/**
+ * efi_query_capsule_caps() - check if capsule is supported
+ *
+ * This function implements the QueryCapsuleCapabilities() runtime service.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification for
+ * details.
+ *
+ * @capsule_header_array:	pointer to array of virtual pointers
+ * @capsule_count:		number of pointers in capsule_header_array
+ * @capsule_size:		maximum capsule size
+ * @reset_type:			type of reset needed for capsule update
+ * Returns:			status code
+ */
 efi_status_t __efi_runtime EFIAPI efi_query_capsule_caps(
 			struct efi_capsule_header **capsule_header_array,
 			efi_uintn_t capsule_count,
@@ -493,6 +620,24 @@ efi_status_t __efi_runtime EFIAPI efi_query_capsule_caps(
 	return EFI_UNSUPPORTED;
 }
 
+/**
+ * efi_query_variable_info() - get information about EFI variables
+ *
+ * This function implements the QueryVariableInfo() runtime service.
+ *
+ * See the Unified Extensible Firmware Interface (UEFI) specification for
+ * details.
+ *
+ * @attributes:				bitmask to select variables to be
+ *					queried
+ * @maximum_variable_storage_size:	maximum size of storage area for the
+ *					selected variable types
+ * @remaining_variable_storage_size:	remaining size of storage are for the
+ *					selected variable types
+ * @maximum_variable_size:		maximum size of a variable of the
+ *					selected type
+ * Returns:				status code
+ */
 efi_status_t __efi_runtime EFIAPI efi_query_variable_info(
 			u32 attributes,
 			u64 *maximum_variable_storage_size,