Add more detailed comments for many of the Base Types

Remove all declarations of UINT8_MAX.  Use BIT8-1 instead.


git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6909 6f19259b-4bc3-4df7-8a09-765794883524

MdePkg/Include/Base.h

@@ -26,11 +26,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 //
 #include <ProcessorBind.h>
 
-
+///
-//
+/// 128 bit buffer containing a unique identifier value.  
-// 128 bit buffer containing a unique identifier value.  
+/// Unless otherwise specified, aligned on a 64 bit boundary.
-// Unless otherwise specified, aligned on a 64 bit boundary.
+///
-//
 typedef struct {
   UINT32  Data1;
   UINT16  Data2;
@@ -44,10 +43,13 @@ typedef struct {
 typedef UINT64 PHYSICAL_ADDRESS;
 
 ///
-/// LIST_ENTRY definition.
+/// LIST_ENTRY structure definition.
 ///
 typedef struct _LIST_ENTRY LIST_ENTRY;
 
+///
+/// _LIST_ENTRY structure definition.
+///
 struct _LIST_ENTRY {
   LIST_ENTRY  *ForwardLink;
   LIST_ENTRY  *BackLink;
@@ -56,28 +58,63 @@ struct _LIST_ENTRY {
 //
 // Modifiers to abstract standard types to aid in debug of problems
 //
+
+///
+/// Datum is read-only
+///
 #define CONST     const
+
+///
+/// Datum is scoped to the current file or function
+///
 #define STATIC    static
+
+///
+/// Undclared type
+///
 #define VOID      void
 
 //
 // Modifiers for Data Types used to self document code.
 // This concept is borrowed for UEFI specification.
 //
+
+///
+/// Datum is passed to the function
+///
 #define IN
+
+///
+/// Datum is returned from the function
+///
 #define OUT
+
+///
+/// Passing the datum to the function is optional, and a NULL
+/// be passed if the value is not supplied.
+///
 #define OPTIONAL
 
 //
 //  UEFI specification claims 1 and 0. We are concerned about the 
 //  complier portability so we did it this way.
 //
+
+///
+/// Boolean true value.  UEFI Specification defines this value to be 1,
+/// but this form is more portable.
+///
 #define TRUE  ((BOOLEAN)(1==1))
+
+///
+/// Boolean false value.  UEFI Specification defines this value to be 0,
+/// but this form is more portable.
+///
 #define FALSE ((BOOLEAN)(0==1))
 
-//
+///
-// NULL pointer (VOID *)
+/// NULL pointer (VOID *)
-//
+///
 #define NULL  ((VOID *) 0)
 
 
@@ -188,9 +225,9 @@ struct _LIST_ENTRY {
 
 #define _INT_SIZE_OF(n) ((sizeof (n) + sizeof (UINTN) - 1) &~(sizeof (UINTN) - 1))
 
-//
+///
-// Pointer to the start of a variable argument list. Same as UINT8 *.
+/// Pointer to the start of a variable argument list. Same as CHAR8 *.
-//
+///
 typedef CHAR8 *VA_LIST;
 
 /**
@@ -353,57 +390,230 @@ typedef CHAR8 *VA_LIST;
 #define MIN(a, b)                       \
   (((a) < (b)) ? (a) : (b))
 
-
 //
-// EFI Error Codes common to all execution phases
+// Status codes common to all execution phases
 //
-
 typedef INTN RETURN_STATUS;
 
-///
+/**
-/// Set the upper bit to indicate EFI Error.
+  Produces a RETURN_STATUS code with the highest bit set. 
-///
-#define ENCODE_ERROR(a)              (MAX_BIT | (a))
 
-#define ENCODE_WARNING(a)            (a)
+  @param  StatusCode	The status code value to convert into a warning code.  
-#define RETURN_ERROR(a)              ((INTN) (a) < 0)
+                        StatusCode must be in the range 0x00000000..0x7FFFFFFF.
 
+  @return The value specified by StatusCode with the highest bit set.
+
+**/
+#define ENCODE_ERROR(StatusCode)     (MAX_BIT | (StatusCode))
+
+/**
+  Produces a RETURN_STATUS code with the highest bit clear. 
+
+  @param  StatusCode	The status code value to convert into a warning code.  
+                        StatusCode must be in the range 0x00000000..0x7FFFFFFF.
+
+  @return The value specified by StatusCode with the highest bit clear.
+
+**/
+#define ENCODE_WARNING(StatusCode)   (StatusCode)
+
+/**
+  Returns TRUE if a specified RETURN_STATUS code is an error code. 
+
+  This function returns TRUE if StatusCode has the high bit set.  Otherwise FALSE is returned.  
+  
+  @param  StatusCode	The status code value to evaluate.
+
+  @retval TRUE          The high bit of StatusCode is set.
+  @retval FALSE         The high bit of StatusCode is clear.
+
+**/
+#define RETURN_ERROR(StatusCode)     ((INTN) (StatusCode) < 0)
+
+///
+/// The operation completed successfully.
+///
 #define RETURN_SUCCESS               0
+
+///
+/// The image failed to load.
+///
 #define RETURN_LOAD_ERROR            ENCODE_ERROR (1)
+
+///
+/// The parameter was incorrect.
+///
 #define RETURN_INVALID_PARAMETER     ENCODE_ERROR (2)
+
+///
+/// The operation is not supported.
+///
 #define RETURN_UNSUPPORTED           ENCODE_ERROR (3)
+
+///
+/// The buffer was not the proper size for the request.
+///
 #define RETURN_BAD_BUFFER_SIZE       ENCODE_ERROR (4)
+
+///
+/// The buffer was not large enough to hold the requested data.
+/// The required buffer size is returned in the appropriate
+/// parameter when this error occurs.
+///
 #define RETURN_BUFFER_TOO_SMALL      ENCODE_ERROR (5)
+
+///
+/// There is no data oending upon return.
+///
 #define RETURN_NOT_READY             ENCODE_ERROR (6)
+
+///
+/// The physical device reported an error while attempting the
+/// operation.
+///
 #define RETURN_DEVICE_ERROR          ENCODE_ERROR (7)
+
+///
+/// The device can not be written to.
+///
 #define RETURN_WRITE_PROTECTED       ENCODE_ERROR (8)
+
+///
+/// The resource has run out.
+///
 #define RETURN_OUT_OF_RESOURCES      ENCODE_ERROR (9)
+
+///
+/// An inconsistancy was detected on the file system causing the 
+/// operation to fail.
+///
 #define RETURN_VOLUME_CORRUPTED      ENCODE_ERROR (10)
+
+///
+/// There is no more space on the file system.
+///
 #define RETURN_VOLUME_FULL           ENCODE_ERROR (11)
+
+///
+/// The device does not contain any medium to perform the 
+/// operation.
+///
 #define RETURN_NO_MEDIA              ENCODE_ERROR (12)
+
+///
+/// The medium in the device has changed since the last
+/// access.
+///
 #define RETURN_MEDIA_CHANGED         ENCODE_ERROR (13)
+
+///
+/// The item was not found.
+///
 #define RETURN_NOT_FOUND             ENCODE_ERROR (14)
+
+///
+/// Access was denied.
+///
 #define RETURN_ACCESS_DENIED         ENCODE_ERROR (15)
+
+///
+/// The server was not found or did not respond to the request.
+///
 #define RETURN_NO_RESPONSE           ENCODE_ERROR (16)
+
+///
+/// A mapping to the device does not exist.
+///
 #define RETURN_NO_MAPPING            ENCODE_ERROR (17)
+
+///
+/// A timeout time expired.
+///
 #define RETURN_TIMEOUT               ENCODE_ERROR (18)
+
+///
+/// The protocol has not been started.
+///
 #define RETURN_NOT_STARTED           ENCODE_ERROR (19)
+
+///
+/// The protocol has already been started.
+///
 #define RETURN_ALREADY_STARTED       ENCODE_ERROR (20)
+
+///
+/// The operation was aborted.
+///
 #define RETURN_ABORTED               ENCODE_ERROR (21)
+
+///
+/// An ICMP error occurred during the nrtwork operation.
+///
 #define RETURN_ICMP_ERROR            ENCODE_ERROR (22)
+
+///
+/// A TFTP error occurred during the nrtwork operation.
+///
 #define RETURN_TFTP_ERROR            ENCODE_ERROR (23)
+
+///
+/// A protocol error occurred during the nrtwork operation.
+///
 #define RETURN_PROTOCOL_ERROR        ENCODE_ERROR (24)
+
+///
+/// A function encountered an internal version that was
+/// iuncomptible with a version requested by the caller.
+///
 #define RETURN_INCOMPATIBLE_VERSION  ENCODE_ERROR (25)
+
+///
+/// The function was not performed due to a security violation.
+///
 #define RETURN_SECURITY_VIOLATION    ENCODE_ERROR (26)
+
+///
+/// A CRC error was detected.
+///
 #define RETURN_CRC_ERROR             ENCODE_ERROR (27)
+
+///
+/// Beginning or end of media was reached.
+///
 #define RETURN_END_OF_MEDIA          ENCODE_ERROR (28)
+
+///
+/// The end of the file was reached.
+///
 #define RETURN_END_OF_FILE           ENCODE_ERROR (31)
+
+///
+/// The language specified was invalid.
+///
 #define RETURN_INVALID_LANGUAGE      ENCODE_ERROR (32)
 
 
+///
+/// The Unicode string contained one or more characters that
+/// the device could not render and were skipped.
+///
 #define RETURN_WARN_UNKNOWN_GLYPH    ENCODE_WARNING (1)
+
+///
+/// The handle was closed, but the file was not deleted.
+///
 #define RETURN_WARN_DELETE_FAILURE   ENCODE_WARNING (2)
+
+///
+/// The handle was closed, but the data to the file was not
+/// flushed properly.
+///
 #define RETURN_WARN_WRITE_FAILURE    ENCODE_WARNING (3)
+
+///
+/// The resulting buffer was too small, and the data was 
+/// truncated to the buffer size.
+///
 #define RETURN_WARN_BUFFER_TOO_SMALL ENCODE_WARNING (4)
 
 /**

MdePkg/Include/Ebc/ProcessorBind.h

@@ -26,33 +26,76 @@
 //
 // Native integer types
 //
+
+///
+/// 1-byte signed value
+///
 typedef char                  INT8;
+///
+/// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+/// values are undefined.
+///
 typedef unsigned char         BOOLEAN;
+///
+/// 1-byte unsigned value
+///
 typedef unsigned char         UINT8;
+///
+/// 1-byte Character
+///
 typedef char                  CHAR8;
-
+///
+/// 2-byte signed value
+///
 typedef short                 INT16;
+///
+/// 2-byte unsigned value
+///
 typedef unsigned short        UINT16;
+///
+/// 2-byte Character.  Unless otherwise specified all strings are stored in the
+/// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+///
 typedef unsigned short        CHAR16;
-
+///
+/// 4-byte signed value
+///
 typedef int                   INT32;
+///
+/// 4-byte unsigned value
+///
 typedef unsigned int          UINT32;
-
+///
+/// 8-byte signed value
+///
 typedef __int64               INT64;
+///
+/// 8-byte unsigned value
+///
 typedef unsigned __int64      UINT64;
 
 ///
+/// Signed value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
 /// "long" type scales to the processor native size with EBC compiler
 ///
 typedef long                  INTN;
+///
+/// Unsigned value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+/// "long" type scales to the processor native size with EBC compiler
+///
 typedef unsigned long         UINTN;
 
-#define UINT8_MAX 0xff
-
 ///
+/// A value of native width with the highest bit set.
 /// Scalable macro to set the most significant bit in a natural number
 ///
 #define MAX_BIT     (1ULL << (sizeof (INTN) * 8 - 1)) 
+///
+/// A value of native width with the two highest bits set.
+/// Scalable macro to set the most 2 significant bits in a natural number
+///
 #define MAX_2_BITS  (3ULL << (sizeof (INTN) * 8 - 2))
 
 ///
@@ -89,7 +132,6 @@ typedef unsigned long         UINTN;
 
   @return The pointer to the first instruction of a function given a function pointer.
 **/
-
 #define FUNCTION_ENTRY_POINT(FunctionPointer) (VOID *)(UINTN)(FunctionPointer)
 
 #endif 

MdePkg/Include/Ia32/ProcessorBind.h

@@ -98,18 +98,54 @@
   #if _MSC_EXTENSIONS 
 
     //
-    // use Microsoft* C complier dependent interger width types 
+    // use Microsoft C complier dependent integer width types 
     //
+
+    ///
+    /// 8-byte unsigned value
+    ///
     typedef unsigned __int64    UINT64;
+    ///
+    /// 8-byte signed value
+    ///
     typedef __int64             INT64;
+    ///
+    /// 4-byte unsigned value
+    ///
     typedef unsigned __int32    UINT32;
+    ///
+    /// 4-byte signed value
+    ///
     typedef __int32             INT32;
+    ///
+    /// 2-byte unsigned value
+    ///
     typedef unsigned short      UINT16;
+    ///
+    /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+    /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+    ///
     typedef unsigned short      CHAR16;
+    ///
+    /// 2-byte signed value
+    ///
     typedef short               INT16;
+    ///
+    /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+    /// values are undefined.
+    ///
     typedef unsigned char       BOOLEAN;
+    ///
+    /// 1-byte unsigned value
+    ///
     typedef unsigned char       UINT8;
+    ///
+    /// 1-byte Character
+    ///
     typedef char                CHAR8;
+    ///
+    /// 1-byte signed value
+    ///
     typedef char                INT8;
   #else
 
@@ -117,48 +153,131 @@
     // Assume standard IA-32 alignment. 
     // Need to check portability of long long
     //
+
+    ///
+    /// 8-byte unsigned value
+    ///
     typedef unsigned long long  UINT64;
+    ///
+    /// 8-byte signed value
+    ///
     typedef long long           INT64;
+    ///
+    /// 4-byte unsigned value
+    ///
     typedef unsigned int        UINT32;
+    ///
+    /// 4-byte signed value
+    ///
     typedef int                 INT32;
+    ///
+    /// 2-byte unsigned value
+    ///
     typedef unsigned short      UINT16;
+    ///
+    /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+    /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+    ///
     typedef unsigned short      CHAR16;
+    ///
+    /// 2-byte signed value
+    ///
     typedef short               INT16;
+    ///
+    /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+    /// values are undefined.
+    ///
     typedef unsigned char       BOOLEAN;
+    ///
+    /// 1-byte unsigned value
+    ///
     typedef unsigned char       UINT8;
+    ///
+    /// 1-byte Character
+    ///
     typedef char                CHAR8;
+    ///
+    /// 1-byte signed value
+    ///
     typedef char                INT8;
   #endif
-
-  #define UINT8_MAX 0xff
-
 #else
   //
   // Use ANSI C 2000 stdint.h integer width declarations
   //
-  #include "stdint.h"
+  #include <stdint.h>
+
+  ///
+  /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+  /// values are undefined.
+  ///
   typedef uint8_t   BOOLEAN;
+  ///
+  /// 1-byte signed value
+  ///
   typedef int8_t    INT8;
+  ///
+  /// 1-byte unsigned value
+  ///
   typedef uint8_t   UINT8;
+  ///
+  /// 2-byte signed value
+  ///
   typedef int16_t   INT16;
+  ///
+  /// 2-byte unsigned value
+  ///
   typedef uint16_t  UINT16;
+  ///
+  /// 4-byte signed value
+  ///
   typedef int32_t   INT32;
+  ///
+  /// 4-byte unsigned value
+  ///
   typedef uint32_t  UINT32;
+  ///
+  /// 8-byte signed value
+  ///
   typedef int64_t   INT64;
+  ///
+  /// 8-byte unsigned value
+  ///
   typedef uint64_t  UINT64;
+  ///
+  /// 1-byte Character
+  ///
   typedef char      CHAR8;
+  ///
+  /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+  /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+  ///
   typedef uint16_t  CHAR16;
 
 #endif
 
+///
+/// Unsigned value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+///
 typedef UINT32  UINTN;
+///
+/// Signed value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+///
 typedef INT32   INTN;
 
+//
+// Processor specific defines
+//
 
 ///
-/// Processor specific defines
+/// A value of native width with the highest bit set.
 ///
 #define MAX_BIT     0x80000000
+///
+/// A value of native width with the two highest bits set.
+///
 #define MAX_2_BITS  0xC0000000
 
 ///
@@ -178,11 +297,14 @@ typedef INT32   INTN;
 //
 #if _MSC_EXTENSIONS
   ///
-  /// Microsoft* compiler requires _EFIAPI useage, __cdecl is Microsoft* specific C.
+  /// Microsoft* compiler specific method for EFIAPI calling convension
   /// 
   #define EFIAPI __cdecl  
 #else
   #if __GNUC__
+    ///
+    /// GCC specific method for EFIAPI calling convension
+    /// 
     #define EFIAPI __attribute__((cdecl))  
   #endif  
 #endif
@@ -193,8 +315,16 @@ typedef INT32   INTN;
 //  a non standard extension
 //
 #if _MSC_EXTENSIONS
+  ///
+  /// Remove global variable from the linked image if there are no references to 
+  /// it after all compiler and linker optimizations have been performed.
+  ///
   #define GLOBAL_REMOVE_IF_UNREFERENCED __declspec(selectany)
 #else
+  ///
+  /// Remove global variable from the linked image if there are no references to 
+  /// it after all compiler and linker optimizations have been performed.
+  ///
   #define GLOBAL_REMOVE_IF_UNREFERENCED
 #endif
 

MdePkg/Include/Ipf/ProcessorBind.h

@@ -53,7 +53,7 @@
 #if _MSC_EXTENSIONS
 //
 // Disable warning that make it impossible to compile at /W4
-// This only works for Microsoft tools. 
+// This only works for Microsoft* tools
 //
 
 //
@@ -61,7 +61,7 @@
 //
 #pragma warning ( disable : 4214 )
 
-
+//
 // Disabling the unreferenced formal parameter warnings.
 //
 #pragma warning ( disable : 4100 )
@@ -110,91 +110,247 @@
     //
     // use Microsoft C complier dependent integer width types
     //
+
+    ///
+    /// 8-byte unsigned value
+    ///
     typedef unsigned __int64    UINT64;
+    ///
+    /// 8-byte signed value
+    ///
     typedef __int64             INT64;
+    ///
+    /// 4-byte unsigned value
+    ///
     typedef unsigned __int32    UINT32;
+    ///
+    /// 4-byte signed value
+    ///
     typedef __int32             INT32;
+    ///
+    /// 2-byte unsigned value
+    ///
     typedef unsigned short      UINT16;
+    ///
+    /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+    /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+    ///
     typedef unsigned short      CHAR16;
+    ///
+    /// 2-byte signed value
+    ///
     typedef short               INT16;
+    ///
+    /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+    /// values are undefined.
+    ///
     typedef unsigned char       BOOLEAN;
+    ///
+    /// 1-byte unsigned value
+    ///
     typedef unsigned char       UINT8;
+    ///
+    /// 1-byte Character
+    ///
     typedef char                CHAR8;
+    ///
+    /// 1-byte signed value
+    ///
     typedef char                INT8;
   #else
     #ifdef _EFI_P64
       //
       // P64 - pointers being 64-bit and longs and ints are 32-bits.
       //
+
+      ///
+      /// 8-byte unsigned value
+      ///
       typedef unsigned long long  UINT64;
+      ///
+      /// 8-byte signed value
+      ///
       typedef long long           INT64;
+      ///
+      /// 4-byte unsigned value
+      ///
       typedef unsigned int        UINT32;
+      ///
+      /// 4-byte signed value
+      ///
       typedef int                 INT32;
+      ///
+      /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+      /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+      ///
       typedef unsigned short      CHAR16;
+      ///
+      /// 2-byte unsigned value
+      ///
       typedef unsigned short      UINT16;
+      ///
+      /// 2-byte signed value
+      ///
       typedef short               INT16;
+      ///
+      /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+      /// values are undefined.
+      ///
       typedef unsigned char       BOOLEAN;
+      ///
+      /// 1-byte unsigned value
+      ///
       typedef unsigned char       UINT8;
+      ///
+      /// 1-byte Character
+      ///
       typedef char                CHAR8;
+      ///
+      /// 1-byte signed value
+      ///
       typedef char                INT8;
     #else
       //
       // Assume LP64 - longs and pointers are 64-bit. Ints are 32-bit.
       //
+
+      ///
+      /// 8-byte unsigned value
+      ///
       typedef unsigned long   UINT64;
+      ///
+      /// 8-byte signed value
+      ///
       typedef long            INT64;
+      ///
+      /// 4-byte unsigned value
+      ///
       typedef unsigned int    UINT32;
+      ///
+      /// 4-byte signed value
+      ///
       typedef int             INT32;
+      ///
+      /// 2-byte unsigned value
+      ///
       typedef unsigned short  UINT16;
+      ///
+      /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+      /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+      ///
       typedef unsigned short  CHAR16;
+      ///
+      /// 2-byte signed value
+      ///
       typedef short           INT16;
+      ///
+      /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+      /// values are undefined.
+      ///
       typedef unsigned char   BOOLEAN;
+      ///
+      /// 1-byte unsigned value
+      ///
       typedef unsigned char   UINT8;
+      ///
+      /// 1-byte Character
+      ///
       typedef char            CHAR8;
+      ///
+      /// 1-byte signed value
+      ///
       typedef char            INT8;
     #endif
   #endif
-
-  #define UINT8_MAX 0xff
-
 #else
   //
   // Use ANSI C 2000 stdint.h integer width declarations
   //
   #include <stdint.h>
+
+  ///
+  /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+  /// values are undefined.
+  ///
   typedef uint8_t   BOOLEAN;
+  ///
+  /// 1-byte signed value
+  ///
   typedef int8_t    INT8;
+  ///
+  /// 1-byte unsigned value
+  ///
   typedef uint8_t   UINT8;
+  ///
+  /// 2-byte signed value
+  ///
   typedef int16_t   INT16;
+  ///
+  /// 2-byte unsigned value
+  ///
   typedef uint16_t  UINT16;
+  ///
+  /// 4-byte signed value
+  ///
   typedef int32_t   INT32;
+  ///
+  /// 4-byte unsigned value
+  ///
   typedef uint32_t  UINT32;
+  ///
+  /// 8-byte signed value
+  ///
   typedef int64_t   INT64;
+  ///
+  /// 8-byte unsigned value
+  ///
   typedef uint64_t  UINT64;
+  ///
+  /// 1-byte Character
+  ///
   typedef char      CHAR8;
+  ///
+  /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+  /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+  ///
   typedef uint16_t  CHAR16;
 
 #endif
 
+///
+/// Unsigned value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+///
 typedef UINT64  UINTN;
+///
+/// Signed value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+///
 typedef INT64   INTN;
 
 
 //
 // Processor specific defines
 //
+
+///
+/// A value of native width with the highest bit set.
+///
 #define MAX_BIT     0x8000000000000000ULL
+///
+/// A value of native width with the two highest bits set.
+///
 #define MAX_2_BITS  0xC000000000000000ULL
 
-//
+///
-// Maximum legal Itanium-based address
+/// Maximum legal Itanium-based address
-//
+///
 #define MAX_ADDRESS   0xFFFFFFFFFFFFFFFFULL
 
-//
+///
-// Per the Itanium Software Conventions and Runtime Architecture Guide,
+/// Per the Itanium Software Conventions and Runtime Architecture Guide,
-// section 3.3.4, IPF stack must always be 16-byte aligned.
+/// section 3.3.4, IPF stack must always be 16-byte aligned.
-//
+///
 #define CPU_STACK_ALIGNMENT   16
 
 //
@@ -203,9 +359,9 @@ typedef INT64   INTN;
 // EFI intrinsics are required to modify their member functions with EFIAPI.
 //
 #if _MSC_EXTENSIONS
-  //
+  ///
-  // Microsoft* compiler requires _EFIAPI useage, __cdecl is Microsoft* specific C.
+  /// Microsoft* compiler specific method for EFIAPI calling convension
-  //
+  /// 
   #define EFIAPI __cdecl
 #else
   #define EFIAPI
@@ -217,8 +373,18 @@ typedef INT64   INTN;
 //  a non standard extension
 //
 #if _MSC_EXTENSIONS
+  ///
+  /// Remove global variable from the linked image if there are no references to 
+  /// it after all compiler and linker optimizations have been performed.
+  ///
+  ///
   #define GLOBAL_REMOVE_IF_UNREFERENCED __declspec(selectany)
 #else
+  ///
+  /// Remove global variable from the linked image if there are no references to 
+  /// it after all compiler and linker optimizations have been performed.
+  ///
+  ///
   #define GLOBAL_REMOVE_IF_UNREFERENCED
 #endif
 
@@ -230,6 +396,9 @@ typedef struct {
   UINT64  GP;
 } EFI_PLABEL;
 
+///
+/// PAL Call return structure.
+///
 typedef struct {
   UINT64                    Status;
   UINT64                    r9;

MdePkg/Include/X64/ProcessorBind.h

@@ -101,101 +101,256 @@
     //
     // use Microsoft C complier dependent integer width types 
     //
+
+    ///
+    /// 8-byte unsigned value
+    ///
     typedef unsigned __int64    UINT64;
+    ///
+    /// 8-byte signed value
+    ///
     typedef __int64             INT64;
+    ///
+    /// 4-byte unsigned value
+    ///
     typedef unsigned __int32    UINT32;
+    ///
+    /// 4-byte signed value
+    ///
     typedef __int32             INT32;
+    ///
+    /// 2-byte unsigned value
+    ///
     typedef unsigned short      UINT16;
+    ///
+    /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+    /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+    ///
     typedef unsigned short      CHAR16;
+    ///
+    /// 2-byte signed value
+    ///
     typedef short               INT16;
+    ///
+    /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+    /// values are undefined.
+    ///
     typedef unsigned char       BOOLEAN;
+    ///
+    /// 1-byte unsigned value
+    ///
     typedef unsigned char       UINT8;
+    ///
+    /// 1-byte Character
+    ///
     typedef char                CHAR8;
+    ///
+    /// 1-byte signed value
+    ///
     typedef char                INT8;
   #else
     #ifdef _EFI_P64 
       //
       // P64 - pointers being 64-bit and longs and ints are 32-bits.
       //
+
+      ///
+      /// 8-byte unsigned value
+      ///
       typedef unsigned long long  UINT64;
+      ///
+      /// 8-byte signed value
+      ///
       typedef long long           INT64;
+      ///
+      /// 4-byte unsigned value
+      ///
       typedef unsigned int        UINT32;
+      ///
+      /// 4-byte signed value
+      ///
       typedef int                 INT32;
+      ///
+      /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+      /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+      ///
       typedef unsigned short      CHAR16;
+      ///
+      /// 2-byte unsigned value
+      ///
       typedef unsigned short      UINT16;
+      ///
+      /// 2-byte signed value
+      ///
       typedef short               INT16;
+      ///
+      /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+      /// values are undefined.
+      ///
       typedef unsigned char       BOOLEAN;
+      ///
+      /// 1-byte unsigned value
+      ///
       typedef unsigned char       UINT8;
+      ///
+      /// 1-byte Character
+      ///
       typedef char                CHAR8;
+      ///
+      /// 1-byte signed value
+      ///
       typedef char                INT8;
     #else
       //
       // Assume LP64 - longs and pointers are 64-bit. Ints are 32-bit.
       //
+
+      ///
+      /// 8-byte unsigned value
+      ///
       typedef unsigned long   UINT64;
+      ///
+      /// 8-byte signed value
+      ///
       typedef long            INT64;
+      ///
+      /// 4-byte unsigned value
+      ///
       typedef unsigned int    UINT32;
+      ///
+      /// 4-byte signed value
+      ///
       typedef int             INT32;
+      ///
+      /// 2-byte unsigned value
+      ///
       typedef unsigned short  UINT16;
+      ///
+      /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+      /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+      ///
       typedef unsigned short  CHAR16;
+      ///
+      /// 2-byte signed value
+      ///
       typedef short           INT16;
+      ///
+      /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+      /// values are undefined.
+      ///
       typedef unsigned char   BOOLEAN;
+      ///
+      /// 1-byte unsigned value
+      ///
       typedef unsigned char   UINT8;
+      ///
+      /// 1-byte Character
+      ///
       typedef char            CHAR8;
+      ///
+      /// 1-byte signed value
+      ///
       typedef char            INT8;
     #endif
   #endif
-
-  #define UINT8_MAX 0xff
-
 #else
   //
   // Use ANSI C 2000 stdint.h integer width declarations
   //
   #include <stdint.h>
+
+  ///
+  /// Logical Boolean.  1-byte value containing 0 for FALSE or a 1 for TRUE.  Other
+  /// values are undefined.
+  ///
   typedef uint8_t   BOOLEAN;
+  ///
+  /// 1-byte signed value
+  ///
   typedef int8_t    INT8;
+  ///
+  /// 1-byte unsigned value
+  ///
   typedef uint8_t   UINT8;
+  ///
+  /// 2-byte signed value
+  ///
   typedef int16_t   INT16;
+  ///
+  /// 2-byte unsigned value
+  ///
   typedef uint16_t  UINT16;
+  ///
+  /// 4-byte signed value
+  ///
   typedef int32_t   INT32;
+  ///
+  /// 4-byte unsigned value
+  ///
   typedef uint32_t  UINT32;
+  ///
+  /// 8-byte signed value
+  ///
   typedef int64_t   INT64;
+  ///
+  /// 8-byte unsigned value
+  ///
   typedef uint64_t  UINT64;
+  ///
+  /// 1-byte Character
+  ///
   typedef char      CHAR8;
+  ///
+  /// 2-byte Character.  Unless otherwise specified all strings are stored in the
+  /// UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
+  ///
   typedef uint16_t  CHAR16;
 
 #endif
 
+///
+/// Unsigned value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+///
 typedef UINT64  UINTN;
+///
+/// Signed value of native width.  (4 bytes on supported 32-bit processor instructions,
+/// 8 bytes on supported 64-bit processor instructions)
+///
 typedef INT64   INTN;
 
 
 //
 // Processor specific defines
 //
+
+///
+/// A value of native width with the highest bit set.
+///
 #define MAX_BIT     0x8000000000000000ULL
+///
+/// A value of native width with the two highest bits set.
+///
 #define MAX_2_BITS  0xC000000000000000ULL
 
-//
+///
-// Maximum legal x64 address
+/// Maximum legal x64 address
-//
+///
 #define MAX_ADDRESS   0xFFFFFFFFFFFFFFFFULL
 
-//
+///
-// The stack alignment required for x64
+/// The stack alignment required for x64
-//
+///
 #define CPU_STACK_ALIGNMENT   16
 
 //
 // Modifier to ensure that all protocol member functions and EFI intrinsics
 // use the correct C calling convention. All protocol member functions and
-// EFI intrinsics are required to modify thier member functions with EFIAPI.
+// EFI intrinsics are required to modify their member functions with EFIAPI.
 //
 #if _MSC_EXTENSIONS 
   ///
-  /// Define the standard calling convention reguardless of optimization level.
+  /// Microsoft* compiler specific method for EFIAPI calling convension
-  /// __cdecl is Microsoft* specific C extension.
   /// 
   #define EFIAPI __cdecl  
 #elif __GNUC__
@@ -222,8 +377,18 @@ typedef INT64   INTN;
 //  a non standard extension
 //
 #if _MSC_EXTENSIONS
+  ///
+  /// Remove global variable from the linked image if there are no references to 
+  /// it after all compiler and linker optimizations have been performed.
+  ///
+  ///
   #define GLOBAL_REMOVE_IF_UNREFERENCED __declspec(selectany)
 #else
+  ///
+  /// Remove global variable from the linked image if there are no references to 
+  /// it after all compiler and linker optimizations have been performed.
+  ///
+  ///
   #define GLOBAL_REMOVE_IF_UNREFERENCED
 #endif