MdeModulePkg: Align RuntimeDxe function headers with UEFI return values

RuntimeDxe is used to back the runtime services time functions,
so align the description of the function return values with the
defined values for these services as described in UEFI Spec 2.10.

REF: UEFI spec 2.10 section 8 Services ? Runtime Services

Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Signed-off-by: Suqiang Ren <suqiangx.ren@intel.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>

7 files changed, 174 insertions, 41 deletions

diff --git a/MdeModulePkg/Core/RuntimeDxe/Runtime.c b/MdeModulePkg/Core/RuntimeDxe/Runtime.c
index de8f2bfce0..c66ed71e35 100644
--- a/MdeModulePkg/Core/RuntimeDxe/Runtime.c
+++ b/MdeModulePkg/Core/RuntimeDxe/Runtime.c
@@ -117,7 +117,12 @@ RuntimeDriverCalculateEfiHdrCrc (
   @retval  EFI_SUCCESS              The pointer pointed to by Address was modified.

   @retval  EFI_NOT_FOUND            The pointer pointed to by Address was not found to be part

                                     of the current memory map. This is normally fatal.

-  @retval  EFI_INVALID_PARAMETER    One of the parameters has an invalid value.

+  @retval  EFI_INVALID_PARAMETER    1) Address is NULL.

+                                    2) *Address is NULL and DebugDisposition does

+                                    not have the EFI_OPTIONAL_PTR bit set.

+  @retval  EFI_UNSUPPORTED          This call is not supported by this platform at the time the call is made.

+                                    The platform should describe this runtime service as unsupported at runtime

+                                    via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

@@ -227,6 +232,9 @@ RuntimeDriverConvertInternalPointer (
                                   map that requires a mapping.

   @retval  EFI_NOT_FOUND          A virtual address was supplied for an address that is not found

                                   in the memory map.

+  @retval  EFI_UNSUPPORTED        This call is not supported by this platform at the time the call is made.

+                                  The platform should describe this runtime service as unsupported at runtime

+                                  via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Core/RuntimeDxe/Runtime.h b/MdeModulePkg/Core/RuntimeDxe/Runtime.h
index cc422e783f..1e28b98d78 100644
--- a/MdeModulePkg/Core/RuntimeDxe/Runtime.h
+++ b/MdeModulePkg/Core/RuntimeDxe/Runtime.h
@@ -59,7 +59,12 @@ RuntimeDriverCalculateCrc32 (
   @retval  EFI_SUCCESS              The pointer pointed to by Address was modified.

   @retval  EFI_NOT_FOUND            The pointer pointed to by Address was not found to be part

                                     of the current memory map. This is normally fatal.

-  @retval  EFI_INVALID_PARAMETER    One of the parameters has an invalid value.

+  @retval  EFI_INVALID_PARAMETER    1) Address is NULL.

+                                    2) *Address is NULL and DebugDisposition does

+                                    not have the EFI_OPTIONAL_PTR bit set.

+  @retval  EFI_UNSUPPORTED          This call is not supported by this platform at the time the call is made.

+                                    The platform should describe this runtime service as unsupported at runtime

+                                    via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

@@ -86,6 +91,9 @@ RuntimeDriverConvertPointer (
                                   map that requires a mapping.

   @retval  EFI_NOT_FOUND          A virtual address was supplied for an address that is not found

                                   in the memory map.

+  @retval  EFI_UNSUPPORTED        This call is not supported by this platform at the time the call is made.

+                                  The platform should describe this runtime service as unsupported at runtime

+                                  via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c
index 50968a839e..f8047c23e1 100644
--- a/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c
+++ b/MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleService.c
@@ -53,6 +53,9 @@ UINT32  mMaxSizeNonPopulateCapsule = 0;
                                 in runtime. The caller may resubmit the capsule prior to ExitBootServices().

   @retval EFI_OUT_OF_RESOURCES  When ExitBootServices() has not been previously called then this error indicates

                                 the capsule is compatible with this platform but there are insufficient resources to process.

+  @retval EFI_UNSUPPORTED       This call is not supported by this platform at the time the call is made.

+                                The platform should describe this runtime service as unsupported at runtime

+                                via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

@@ -247,6 +250,16 @@ UpdateCapsule (
                                 MaximumCapsuleSize and ResetType are undefined.

   @retval EFI_INVALID_PARAMETER MaximumCapsuleSize is NULL, or ResetTyep is NULL,

                                 Or CapsuleCount is Zero, or CapsuleImage is not valid.

+  @retval EFI_OUT_OF_RESOURCES  When ExitBootServices() has been previously called this error indicates

+                                the capsule is compatible with this platform but is not capable of

+                                being submitted or processed in runtime.

+                                The caller may resubmit the capsule prior to ExitBootServices().

+  @retval EFI_OUT_OF_RESOURCES  When ExitBootServices() has not been previously called then this error

+                                indicates the capsule is compatible with this platform but there are

+                                insufficient resources to process.

+  @retval EFI_UNSUPPORTED       This call is not supported by this platform at the time the call is made.

+                                The platform should describe this runtime service as unsupported at runtime

+                                via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Universal/MonotonicCounterRuntimeDxe/MonotonicCounter.c b/MdeModulePkg/Universal/MonotonicCounterRuntimeDxe/MonotonicCounter.c
index 60b6e9350b..3e74713cc5 100644
--- a/MdeModulePkg/Universal/MonotonicCounterRuntimeDxe/MonotonicCounter.c
+++ b/MdeModulePkg/Universal/MonotonicCounterRuntimeDxe/MonotonicCounter.c
@@ -125,6 +125,9 @@ MonotonicCounterDriverGetNextMonotonicCount (
   @retval EFI_DEVICE_ERROR      The variable could not be saved due to a hardware failure.

   @retval EFI_OUT_OF_RESOURCES  If variable service reports that not enough storage

                                 is available to hold the variable and its data.

+  @retval EFI_UNSUPPORTED       This call is not supported by this platform at the time the call is made.

+                                The platform should describe this runtime service as unsupported at runtime

+                                via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.c b/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.c
index 3c360481f4..d394d237a5 100644
--- a/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.c
+++ b/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.c
@@ -2385,10 +2385,19 @@ Done:
   @param Data                       The buffer to return the contents of the variable. May be NULL

                                     with a zero DataSize in order to determine the size buffer needed.

 

-  @return EFI_INVALID_PARAMETER     Invalid parameter.

-  @return EFI_SUCCESS               Find the specified variable.

-  @return EFI_NOT_FOUND             Not found.

-  @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.

+  @retval EFI_SUCCESS               The function completed successfully.

+  @retval EFI_NOT_FOUND             The variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL      The DataSize is too small for the result.

+  @retval EFI_INVALID_PARAMETER     VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER     VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER     DataSize is NULL.

+  @retval EFI_INVALID_PARAMETER     The DataSize is not too small and Data is NULL.

+  @retval EFI_DEVICE_ERROR          The variable could not be retrieved due to a hardware error.

+  @retval EFI_SECURITY_VIOLATION    The variable could not be retrieved due to an authentication failure.

+  @retval EFI_UNSUPPORTED           After ExitBootServices() has been called, this return code may be returned

+                                    if no variable storage is supported. The platform should describe this

+                                    runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                    configuration table.

 

 **/

 EFI_STATUS

@@ -2479,6 +2488,11 @@ Done:
                                     GUID of an existing variable.

   @retval EFI_INVALID_PARAMETER     Null-terminator is not found in the first VariableNameSize bytes of

                                     the input VariableName buffer.

+  @retval EFI_DEVICE_ERROR          The variable could not be retrieved due to a hardware error.

+  @retval EFI_UNSUPPORTED           After ExitBootServices() has been called, this return code may be returned

+                                    if no variable storage is supported. The platform should describe this

+                                    runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                    configuration table.

 

 **/

 EFI_STATUS

@@ -2576,11 +2590,19 @@ VariableServiceGetNextVariableName (
                                           data, this value contains the required size.

   @param Data                             Data pointer.

 

-  @return EFI_INVALID_PARAMETER           Invalid parameter.

-  @return EFI_SUCCESS                     Set successfully.

-  @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.

-  @return EFI_NOT_FOUND                   Not found.

-  @return EFI_WRITE_PROTECTED             Variable is read-only.

+  @retval EFI_SUCCESS                     The function completed successfully.

+  @retval EFI_NOT_FOUND                   The variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL            The DataSize is too small for the result.

+  @retval EFI_INVALID_PARAMETER           VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER           VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER           DataSize is NULL.

+  @retval EFI_INVALID_PARAMETER           The DataSize is not too small and Data is NULL.

+  @retval EFI_DEVICE_ERROR                The variable could not be retrieved due to a hardware error.

+  @retval EFI_SECURITY_VIOLATION          The variable could not be retrieved due to an authentication failure.

+  @retval EFI_UNSUPPORTED                 After ExitBootServices() has been called, this return code may be returned

+                                          if no variable storage is supported. The platform should describe this

+                                          runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                          configuration table.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.h b/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.h
index a668abb82b..033c0625af 100644
--- a/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.h
+++ b/MdeModulePkg/Universal/Variable/RuntimeDxe/Variable.h
@@ -446,10 +446,19 @@ GetFvbInfoByAddress (
   @param Data                       The buffer to return the contents of the variable. May be NULL

                                     with a zero DataSize in order to determine the size buffer needed.

 

-  @return EFI_INVALID_PARAMETER     Invalid parameter.

-  @return EFI_SUCCESS               Find the specified variable.

-  @return EFI_NOT_FOUND             Not found.

-  @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.

+  @retval EFI_SUCCESS            The function completed successfully.

+  @retval EFI_NOT_FOUND          The variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL   The DataSize is too small for the result.

+  @retval EFI_INVALID_PARAMETER  VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER  VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER  DataSize is NULL.

+  @retval EFI_INVALID_PARAMETER  The DataSize is not too small and Data is NULL.

+  @retval EFI_DEVICE_ERROR       The variable could not be retrieved due to a hardware error.

+  @retval EFI_SECURITY_VIOLATION The variable could not be retrieved due to an authentication failure.

+  @retval EFI_UNSUPPORTED        After ExitBootServices() has been called, this return code may be returned

+                                 if no variable storage is supported. The platform should describe this

+                                 runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                 configuration table.

 

 **/

 EFI_STATUS

@@ -485,6 +494,11 @@ VariableServiceGetVariable (
                                     GUID of an existing variable.

   @retval EFI_INVALID_PARAMETER     Null-terminator is not found in the first VariableNameSize bytes of

                                     the input VariableName buffer.

+  @retval EFI_DEVICE_ERROR          The variable could not be retrieved due to a hardware error.

+  @retval EFI_UNSUPPORTED           After ExitBootServices() has been called, this return code may be returned

+                                    if no variable storage is supported. The platform should describe this

+                                    runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                    configuration table.

 

 **/

 EFI_STATUS

@@ -513,11 +527,19 @@ VariableServiceGetNextVariableName (
                                           data, this value contains the required size.

   @param Data                             Data pointer.

 

-  @return EFI_INVALID_PARAMETER           Invalid parameter.

-  @return EFI_SUCCESS                     Set successfully.

-  @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.

-  @return EFI_NOT_FOUND                   Not found.

-  @return EFI_WRITE_PROTECTED             Variable is read-only.

+  @retval EFI_SUCCESS                     The function completed successfully.

+  @retval EFI_NOT_FOUND                   The variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL            The DataSize is too small for the result.

+  @retval EFI_INVALID_PARAMETER           VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER           VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER           DataSize is NULL.

+  @retval EFI_INVALID_PARAMETER           The DataSize is not too small and Data is NULL.

+  @retval EFI_DEVICE_ERROR                The variable could not be retrieved due to a hardware error.

+  @retval EFI_SECURITY_VIOLATION          The variable could not be retrieved due to an authentication failure.

+  @retval EFI_UNSUPPORTED                 After ExitBootServices() has been called, this return code may be returned

+                                          if no variable storage is supported. The platform should describe this

+                                          runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                          configuration table.

 

 **/

 EFI_STATUS

diff --git a/MdeModulePkg/Universal/Variable/RuntimeDxe/VariableSmmRuntimeDxe.c b/MdeModulePkg/Universal/Variable/RuntimeDxe/VariableSmmRuntimeDxe.c
index 4aaeb5ba88..6930875e9f 100644
--- a/MdeModulePkg/Universal/Variable/RuntimeDxe/VariableSmmRuntimeDxe.c
+++ b/MdeModulePkg/Universal/Variable/RuntimeDxe/VariableSmmRuntimeDxe.c
@@ -831,10 +831,19 @@ Done:
                                      data, this value contains the required size.

   @param[out]     Data               Data pointer.

 

-  @retval EFI_INVALID_PARAMETER      Invalid parameter.

-  @retval EFI_SUCCESS                Find the specified variable.

-  @retval EFI_NOT_FOUND              Not found.

-  @retval EFI_BUFFER_TO_SMALL        DataSize is too small for the result.

+  @retval EFI_SUCCESS                The function completed successfully.

+  @retval EFI_NOT_FOUND              The variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL       The DataSize is too small for the result.

+  @retval EFI_INVALID_PARAMETER      VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER      VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER      DataSize is NULL.

+  @retval EFI_INVALID_PARAMETER      The DataSize is not too small and Data is NULL.

+  @retval EFI_DEVICE_ERROR           The variable could not be retrieved due to a hardware error.

+  @retval EFI_SECURITY_VIOLATION     The variable could not be retrieved due to an authentication failure.

+  @retval EFI_UNSUPPORTED            After ExitBootServices() has been called, this return code may be returned

+                                     if no variable storage is supported. The platform should describe this

+                                     runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                     configuration table.

 

 **/

 EFI_STATUS

@@ -876,10 +885,22 @@ RuntimeServiceGetVariable (
   @param[in, out] VariableName       Pointer to variable name.

   @param[in, out] VendorGuid         Variable Vendor Guid.

 

-  @retval EFI_INVALID_PARAMETER      Invalid parameter.

-  @retval EFI_SUCCESS                Find the specified variable.

-  @retval EFI_NOT_FOUND              Not found.

-  @retval EFI_BUFFER_TO_SMALL        DataSize is too small for the result.

+  @retval EFI_SUCCESS                The function completed successfully.

+  @retval EFI_NOT_FOUND              The next variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL       The VariableNameSize is too small for the result.

+                                     VariableNameSize has been updated with the size needed to complete the request.

+  @retval EFI_INVALID_PARAMETER      VariableNameSize is NULL.

+  @retval EFI_INVALID_PARAMETER      VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER      VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER      The input values of VariableName and VendorGuid are not a name and

+                                     GUID of an existing variable.

+  @retval EFI_INVALID_PARAMETER      Null-terminator is not found in the first VariableNameSize bytes of

+                                     the input VariableName buffer.

+  @retval EFI_DEVICE_ERROR           The variable could not be retrieved due to a hardware error.

+  @retval EFI_UNSUPPORTED            After ExitBootServices() has been called, this return code may be returned

+                                     if no variable storage is supported. The platform should describe this

+                                     runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                     configuration table.

 

 **/

 EFI_STATUS

@@ -951,10 +972,22 @@ GetNextVariableNameInRuntimeCache (
   @param[in, out] VariableName       Pointer to variable name.

   @param[in, out] VendorGuid         Variable Vendor Guid.

 

-  @retval EFI_INVALID_PARAMETER      Invalid parameter.

-  @retval EFI_SUCCESS                Find the specified variable.

-  @retval EFI_NOT_FOUND              Not found.

-  @retval EFI_BUFFER_TO_SMALL        DataSize is too small for the result.

+  @retval EFI_SUCCESS                The function completed successfully.

+  @retval EFI_NOT_FOUND              The next variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL       The VariableNameSize is too small for the result.

+                                     VariableNameSize has been updated with the size needed to complete the request.

+  @retval EFI_INVALID_PARAMETER      VariableNameSize is NULL.

+  @retval EFI_INVALID_PARAMETER      VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER      VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER      The input values of VariableName and VendorGuid are not a name and

+                                     GUID of an existing variable.

+  @retval EFI_INVALID_PARAMETER      Null-terminator is not found in the first VariableNameSize bytes of

+                                     the input VariableName buffer.

+  @retval EFI_DEVICE_ERROR           The variable could not be retrieved due to a hardware error.

+  @retval EFI_UNSUPPORTED            After ExitBootServices() has been called, this return code may be returned

+                                     if no variable storage is supported. The platform should describe this

+                                     runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                     configuration table.

 

 **/

 EFI_STATUS

@@ -1052,10 +1085,22 @@ Done:
   @param[in, out] VariableName       Pointer to variable name.

   @param[in, out] VendorGuid         Variable Vendor Guid.

 

-  @retval EFI_INVALID_PARAMETER      Invalid parameter.

-  @retval EFI_SUCCESS                Find the specified variable.

-  @retval EFI_NOT_FOUND              Not found.

-  @retval EFI_BUFFER_TO_SMALL        DataSize is too small for the result.

+  @retval EFI_SUCCESS                The function completed successfully.

+  @retval EFI_NOT_FOUND              The next variable was not found.

+  @retval EFI_BUFFER_TOO_SMALL       The VariableNameSize is too small for the result.

+                                     VariableNameSize has been updated with the size needed to complete the request.

+  @retval EFI_INVALID_PARAMETER      VariableNameSize is NULL.

+  @retval EFI_INVALID_PARAMETER      VariableName is NULL.

+  @retval EFI_INVALID_PARAMETER      VendorGuid is NULL.

+  @retval EFI_INVALID_PARAMETER      The input values of VariableName and VendorGuid are not a name and

+                                     GUID of an existing variable.

+  @retval EFI_INVALID_PARAMETER      Null-terminator is not found in the first VariableNameSize bytes of

+                                     the input VariableName buffer.

+  @retval EFI_DEVICE_ERROR           The variable could not be retrieved due to a hardware error.

+  @retval EFI_UNSUPPORTED            After ExitBootServices() has been called, this return code may be returned

+                                     if no variable storage is supported. The platform should describe this

+                                     runtime service as unsupported at runtime via an EFI_RT_PROPERTIES_TABLE

+                                     configuration table.

 

 **/

 EFI_STATUS

@@ -1112,11 +1157,23 @@ RuntimeServiceGetNextVariableName (
                                           data, this value contains the required size.

   @param[in] Data                         Data pointer.

 

-  @retval EFI_INVALID_PARAMETER           Invalid parameter.

-  @retval EFI_SUCCESS                     Set successfully.

-  @retval EFI_OUT_OF_RESOURCES            Resource not enough to set variable.

-  @retval EFI_NOT_FOUND                   Not found.

-  @retval EFI_WRITE_PROTECTED             Variable is read-only.

+  @retval EFI_SUCCESS                     The firmware has successfully stored the variable and its data as

+                                          defined by the Attributes.

+  @retval EFI_INVALID_PARAMETER           An invalid combination of attribute bits, name, and GUID was supplied, or the

+                                          DataSize exceeds the maximum allowed.

+  @retval EFI_INVALID_PARAMETER           VariableName is an empty string.

+  @retval EFI_OUT_OF_RESOURCES            Not enough storage is available to hold the variable and its data.

+  @retval EFI_DEVICE_ERROR                The variable could not be retrieved due to a hardware error.

+  @retval EFI_WRITE_PROTECTED             The variable in question is read-only.

+  @retval EFI_WRITE_PROTECTED             The variable in question cannot be deleted.

+  @retval EFI_SECURITY_VIOLATION          The variable could not be written due to

+                                          EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACESS being set,

+                                          but the AuthInfo does NOT pass the validation check carried out by the firmware.

+

+  @retval EFI_NOT_FOUND                   The variable trying to be updated or deleted was not found.

+  @retval EFI_UNSUPPORTED                 This call is not supported by this platform at the time the call is made.

+                                          The platform should describe this runtime service as unsupported at runtime

+                                          via an EFI_RT_PROPERTIES_TABLE configuration table.

 

 **/

 EFI_STATUS