Fix doxygen comment for structure and macro

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

diff --git a/MdePkg/Include/Protocol/Bis.h b/MdePkg/Include/Protocol/Bis.h
index aa4905b04e54775a6f61ef96c2d42386fd22dc6a..f03452e57915fc200ebc3e8d15ce9105566d0210 100644 (file)
--- a/MdePkg/Include/Protocol/Bis.h
+++ b/MdePkg/Include/Protocol/Bis.h
@@ -1,7 +1,9 @@
 /** @file\r
-  This file defines the BIS protocol.\r
+  BIS protocol are defined in the UEFI specification.\r
+  The EFI_BIS_PROTOCOL is used to check a digital signature of a data block \r
+  against a digital certificate for the purpose of an integrity and authorization check.\r
 \r
-  Copyright (c) 2006, Intel Corporation                                                         \r
+  Copyright (c) 2006 - 2008, Intel Corporation                                                         \r
   All rights reserved. This program and the accompanying materials                          \r
   are licensed and made available under the terms and conditions of the BSD License         \r
   which accompanies this distribution.  The full text of the license may be found at        \r
@@ -43,22 +45,20 @@ typedef VOID    *BIS_APPLICATION_HANDLE;
 typedef UINT16  BIS_ALG_ID;\r
 typedef UINT32  BIS_CERT_ID;\r
 \r
-//\r
-// EFI_BIS_DATA type.\r
-//\r
-// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
-//\r
+///\r
+/// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
+///\r
 typedef struct {\r
-  UINT32  Length; // Length of Data in 8 bit bytes.\r
-  UINT8   *Data;  // 32 Bit Flat Address of data.\r
+  UINT32  Length; ///< Length of Data in 8 bit bytes.\r
+  UINT8   *Data;  ///< 32 Bit Flat Address of data.\r
 } EFI_BIS_DATA;\r
 \r
-//\r
-// EFI_BIS_VERSION type.\r
-//\r
+///\r
+/// EFI_BIS_VERSION type.\r
+///\r
 typedef struct {\r
-  UINT32  Major;  // BIS Interface version number.\r
-  UINT32  Minor;  // Build number.\r
+  UINT32  Major;  ///< BIS Interface version number.\r
+  UINT32  Minor;  ///< Build number.\r
 } EFI_BIS_VERSION;\r
 \r
 //\r
@@ -70,53 +70,53 @@ typedef struct {
 #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1\r
 #define BIS_VERSION_1             1\r
 \r
-//\r
-// EFI_BIS_SIGNATURE_INFO type.\r
-//\r
+///\r
+/// EFI_BIS_SIGNATURE_INFO type.\r
+///\r
 typedef struct {\r
-  BIS_CERT_ID CertificateID;  // Truncated hash of platform Boot Object\r
-  //  authorization certificate.\r
-  //\r
-  BIS_ALG_ID  AlgorithmID;  // A signature algorithm number.\r
-  UINT16      KeyLength;    // Length of alg. keys in bits.\r
+  BIS_CERT_ID CertificateID;  ///< Truncated hash of platform Boot Object\r
+  BIS_ALG_ID  AlgorithmID;    ///< A signature algorithm number.\r
+  UINT16      KeyLength;      ///< Length of alg. keys in bits.\r
 } EFI_BIS_SIGNATURE_INFO;\r
 \r
-//\r
-// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
-// The exact numeric values come from\r
-//    "Common Data Security Architecture (CDSA) Specification".\r
-//\r
+///\r
+/// values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
+/// The exact numeric values come from\r
+///    "Common Data Security Architecture (CDSA) Specification".\r
+///\r
 #define BIS_ALG_DSA     (41)  // CSSM_ALGID_DSA\r
 #define BIS_ALG_RSA_MD5 (42)  // CSSM_ALGID_MD5_WITH_RSA\r
-// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
-//\r
+///\r
+/// values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
+///\r
 #define BIS_CERT_ID_DSA     BIS_ALG_DSA     // CSSM_ALGID_DSA\r
 #define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA\r
-// The  following  is a mask value that gets applied to the truncated hash of a\r
-// platform  Boot Object Authorization Certificate to create the certificateID.\r
-// A certificateID must not have any bits set to the value 1 other than bits in\r
-// this mask.\r
-//\r
+///\r
+/// the mask value that gets applied to the truncated hash of a\r
+/// platform  Boot Object Authorization Certificate to create the certificateID.\r
+/// A certificateID must not have any bits set to the value 1 other than bits in\r
+/// this mask.\r
+///\r
 #define BIS_CERT_ID_MASK  (0xFF7F7FFF)\r
 \r
-//\r
-// Macros for dealing with the EFI_BIS_DATA object obtained\r
-// from BIS_GetSignatureInfo()\r
-// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
-//  elements are contained in a EFI_BIS_DATA struct pointed to\r
-//  by the provided EFI_BIS_DATA*.\r
-//\r
+///\r
+/// Macros for dealing with the EFI_BIS_DATA object obtained\r
+/// from BIS_GetSignatureInfo()\r
+/// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
+///  elements are contained in a EFI_BIS_DATA struct pointed to\r
+///  by the provided EFI_BIS_DATA*.\r
+///\r
 #define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))\r
 \r
-//\r
-// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
-//  from a given EFI_BIS_DATA*.\r
-//\r
+///\r
+/// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
+///  from a given EFI_BIS_DATA*.\r
+///\r
 #define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\r
 \r
-//\r
-// Support old name for backward compatible\r
-//\r
+///\r
+/// Support old name for backward compatible\r
+///\r
 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
         BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
 \r
@@ -397,6 +397,11 @@ EFI_STATUS
   OUT EFI_BIS_DATA            **SignatureInfo      \r
   );\r
 \r
+/**\r
+  @par Protocol Description:\r
+  The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital\r
+  certificate for the purpose of an integrity and authorization check.\r
+**/\r
 struct _EFI_BIS_PROTOCOL {\r
   EFI_BIS_INITIALIZE                                  Initialize;\r
   EFI_BIS_SHUTDOWN                                    Shutdown;\r