diff options
author | mdkinney <mdkinney@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-07 23:10:08 +0000 |
---|---|---|
committer | mdkinney <mdkinney@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-07 23:10:08 +0000 |
commit | f4ec40abd6533850edb914de59b7ef5f1c1c1bb6 (patch) | |
tree | 1e398baa8e8a50367effc9d98fff318316838b96 /MdePkg/Include/Base.h | |
parent | 2a3f6a21d3fb87b66be48aa8be2c0380a0db0ae6 (diff) | |
download | edk2-platforms-f4ec40abd6533850edb914de59b7ef5f1c1c1bb6.tar.xz |
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
Diffstat (limited to 'MdePkg/Include/Base.h')
-rw-r--r-- | MdePkg/Include/Base.h | 252 |
1 files changed, 231 insertions, 21 deletions
diff --git a/MdePkg/Include/Base.h b/MdePkg/Include/Base.h index a90a67b98f..d1b6c82f6d 100644 --- a/MdePkg/Include/Base.h +++ b/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.
-// Unless otherwise specified, aligned on a 64 bit boundary.
-//
+///
+/// 128 bit buffer containing a unique identifier value.
+/// 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.
-///
-#define ENCODE_ERROR(a) (MAX_BIT | (a))
+/**
+ Produces a RETURN_STATUS code with the highest bit set.
-#define ENCODE_WARNING(a) (a)
-#define RETURN_ERROR(a) ((INTN) (a) < 0)
+ @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 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)
/**
|