Update comments for Protocol definitions to match UEFI spec. And add the missing...

[mirror_edk2.git] / MdePkg / Include / Protocol / Bis.h

diff --git a/MdePkg/Include/Protocol/Bis.h b/MdePkg/Include/Protocol/Bis.h
index a7c16584f6edbc628142bba27eaeded4c912560e..194a0b526c1599a95734f75838a081ce288ddb11 100644 (file)
--- a/MdePkg/Include/Protocol/Bis.h
+++ b/MdePkg/Include/Protocol/Bis.h
@@ -57,8 +57,8 @@ typedef struct {
 /// EFI_BIS_VERSION type.\r
 ///\r
 typedef struct {\r
 /// EFI_BIS_VERSION type.\r
 ///\r
 typedef struct {\r

-  UINT32  Major;  ///< BIS Interface version number.\r
-  UINT32  Minor;  ///< Build number.\r
+  UINT32  Major;  ///< the major BIS version number.\r
+  UINT32  Minor;  ///< a minor BIS version number.\r

 } EFI_BIS_VERSION;\r
 \r
 //\r
 } EFI_BIS_VERSION;\r
 \r
 //\r


@@ -132,19 +132,33 @@ typedef struct {
                                    interface version desired.                                   \r
                                    On output, both the major and minor                         \r
                                    version numbers are updated with the major and minor version\r
                                    interface version desired.                                   \r
                                    On output, both the major and minor                         \r
                                    version numbers are updated with the major and minor version\r

-                                   numbers of the interface                                    \r
+                                   numbers of the interface. This update is done whether or not the\r
+                                   initialization was successful.                                    \r

   @param  TargetAddress            Indicates a network or device address of the BIS platform to connect to.                                                                 \r
 \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the                \r
                                    caller was not compatible with the interface version of the\r
   @param  TargetAddress            Indicates a network or device address of the BIS platform to connect to.                                                                 \r
 \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the                \r
                                    caller was not compatible with the interface version of the\r

+                                   implementation. The InterfaceVersion.Major has\r
+                                   been updated with the current interface version.\r

   @retval EFI_UNSUPPORTED          This is a local-platform implementation and        \r
                                    TargetAddress.Data was not NULL, or                \r
                                    TargetAddress.Data was any other value that was not\r
                                    supported by the implementation.                   \r
   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                              \r
   @retval EFI_UNSUPPORTED          This is a local-platform implementation and        \r
                                    TargetAddress.Data was not NULL, or                \r
                                    TargetAddress.Data was any other value that was not\r
                                    supported by the implementation.                   \r
   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                              \r

-  @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure.\r
-  @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.\r
+  @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure while\r
+                                   initializing a cryptographic software module, or\r
+                                   No cryptographic software module with compatible version was\r
+                                   found, or A resource limitation was encountered while using a\r
+                                   cryptographic software module.\r
+  @retval EFI_INVALID_PARAMETER    The This parameter supplied by the caller is NULL or does not\r
+                                   reference a valid EFI_BIS_PROTOCOL object, or\r
+                                   The AppHandle parameter supplied by the caller is NULL or\r
+                                   an invalid memory reference, or\r
+                                   The InterfaceVersion parameter supplied by the caller\r
+                                   is NULL or an invalid memory reference, or\r
+                                   The TargetAddress parameter supplied by the caller is\r
+                                   NULL or an invalid memory reference.\r

                                           \r
 **/                                       \r
 typedef\r
                                           \r
 **/                                       \r
 typedef\r


@@ -161,7 +175,8 @@ EFI_STATUS
       \r
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                         \r
       \r
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                         \r

-  @param  ToFree                   An EFI_BIS_DATA* and associated memory block to be freed.\r
+  @param  ToFree                   An EFI_BIS_DATA* and associated memory block to be freed. \r
+                                   This EFI_BIS_DATA* must have been allocated by one of the other BIS functions.\r

 \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r
 \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r


@@ -189,9 +204,10 @@ EFI_STATUS
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r
                                    application instance handle associated with the EFI_BIS protocol.                                     \r
   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                                \r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r
                                    application instance handle associated with the EFI_BIS protocol.                                     \r
   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                                \r

-  @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure.  \r
-                                           \r
-**/   \r
+  @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure while\r
+                                   returning resources associated with a cryptographic software module, or\r
+                                   while trying to shut down a cryptographic software module.\r
+**/\r

 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BIS_SHUTDOWN)(\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_BIS_SHUTDOWN)(\r


@@ -205,7 +221,8 @@ EFI_STATUS
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                           \r
   @param  Certificate              The function writes an allocated EFI_BIS_DATA* containing the Boot\r
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                           \r
   @param  Certificate              The function writes an allocated EFI_BIS_DATA* containing the Boot\r

-                                   Object Authorization Certificate object.                            \r
+                                   Object Authorization Certificate object.  The caller must\r
+                                   eventually free the memory allocated by this function using the function Free().\r

 \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r
 \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r


@@ -285,7 +302,8 @@ EFI_STATUS
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                           \r
   @param  UpdateToken              The function writes an allocated EFI_BIS_DATA* containing the new\r
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                           \r
   @param  UpdateToken              The function writes an allocated EFI_BIS_DATA* containing the new\r

-                                   unique update token value.                                                                          \r
+                                   unique update token value.  The caller must\r
+                                   eventually free the memory allocated by this function using the function Free().\r

                                    \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r
                                    \r
   @retval EFI_SUCCESS              The function completed successfully.\r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid\r


@@ -311,7 +329,8 @@ EFI_STATUS
   @param  RequestCredential        This is a Signed Manifest with embedded attributes that carry the details\r
                                    of the requested update.                                                 \r
   @param  NewUpdateToken           The function writes an allocated EFI_BIS_DATA* containing the new                        \r
   @param  RequestCredential        This is a Signed Manifest with embedded attributes that carry the details\r
                                    of the requested update.                                                 \r
   @param  NewUpdateToken           The function writes an allocated EFI_BIS_DATA* containing the new                        \r

-                                   unique update token value.                                       \r
+                                   unique update token value. The caller must\r
+                                   eventually free the memory allocated by this function using the function Free().\r

                                    \r
   @retval EFI_SUCCESS              The function completed successfully.                                                \r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid                              \r
                                    \r
   @retval EFI_SUCCESS              The function completed successfully.                                                \r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid                              \r


@@ -320,7 +339,10 @@ EFI_STATUS
   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.                                                 \r
   @retval EFI_SECURITY_VIOLATION   The signed manifest supplied as the RequestCredential parameter                           \r
                                    was invalid (could not be parsed) or Platform-specific authorization failed, etc.   \r
   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.                                                 \r
   @retval EFI_SECURITY_VIOLATION   The signed manifest supplied as the RequestCredential parameter                           \r
                                    was invalid (could not be parsed) or Platform-specific authorization failed, etc.   \r

-  @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.                                                                                                                                                                   \r
+  @retval EFI_DEVICE_ERROR         An unexpected internal error occurred while analyzing the new\r
+                                   certificate's key algorithm, or while attempting to retrieve\r
+                                   the public key algorithm of the manifest's signer's certificate,\r
+                                   or An unexpected internal error occurred in a cryptographic software module.                                                                                                                                                                  \r

                                    \r
 **/ \r
 typedef\r
                                    \r
 **/ \r
 typedef\r


@@ -357,8 +379,9 @@ EFI_STATUS
                                    or the AuthorityCertificate supplied by the caller was \r
                                    invalid (could not be parsed),                      \r
                                    or Platform-specific authorization failed, etc.   \r
                                    or the AuthorityCertificate supplied by the caller was \r
                                    invalid (could not be parsed),                      \r
                                    or Platform-specific authorization failed, etc.   \r

-  @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.                                                                                                                                                                   \r
-                                   \r
+  @retval EFI_DEVICE_ERROR         An unexpected internal error occurred while attempting to retrieve\r
+                                   the public key algorithm of the manifest¡¯s signer¡¯s certificate,\r
+                                   or An unexpected internal error occurred in a cryptographic software module.                                                                                                                                                                  \r

 **/ \r
 typedef\r
 EFI_STATUS\r
 **/ \r
 typedef\r
 EFI_STATUS\r


@@ -374,21 +397,25 @@ EFI_STATUS
 /**                                                                 \r
   Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\r
   combinations that the platform supports.                                                                      \r
 /**                                                                 \r
   Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\r
   combinations that the platform supports.                                                                      \r

-      \r
+\r

   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                           \r
   @param  SignatureInfo            The function writes an allocated EFI_BIS_DATA* containing the array\r
                                    of EFI_BIS_SIGNATURE_INFO structures representing the supported    \r
   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                    of the BIS service.                                                                                           \r
   @param  SignatureInfo            The function writes an allocated EFI_BIS_DATA* containing the array\r
                                    of EFI_BIS_SIGNATURE_INFO structures representing the supported    \r

-                                   digital certificate identifier, algorithm, and key length combinations.                                   \r
-                                   \r
+                                   digital certificate identifier, algorithm, and key length combinations.\r
+                                   The caller must eventually free the memory allocated by this function using the function Free().\r
+\r

   @retval EFI_SUCCESS              The function completed successfully.                                                \r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid                              \r
                                    application instance handle associated with the EFI_BIS protocol.                   \r
   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                       \r
   @retval EFI_INVALID_PARAMETER    The SignatureInfo parameter supplied by the caller is NULL\r
   @retval EFI_SUCCESS              The function completed successfully.                                                \r
   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid                              \r
                                    application instance handle associated with the EFI_BIS protocol.                   \r
   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.                       \r
   @retval EFI_INVALID_PARAMETER    The SignatureInfo parameter supplied by the caller is NULL\r

-                                   or an invalid memory reference.                           \r
-  @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.                                                                                                                                                                   \r
-                                   \r
+                                   or an invalid memory reference.\r
+  @retval EFI_DEVICE_ERROR         An unexpected internal error occurred in a\r
+                                   cryptographic software module, or\r
+                                   The function encountered an unexpected internal consistency check\r
+                                   failure (possible corruption of stored Boot Object Authorization Certificate).\r
+\r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r