Update or add comments to files and functions for use by Doxygen.

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

9 files changed, 436 insertions, 203 deletions

diff --git a/StdLib/Include/assert.h b/StdLib/Include/assert.h
index faa3f03294..26c7037ea6 100644
--- a/StdLib/Include/assert.h
+++ b/StdLib/Include/assert.h
@@ -1,5 +1,6 @@
 /** @file

-  Provides a definition of the assert macro.

+  Provides a definition of the assert macro used to insert diagnostic messages

+  into code.

 

   This header file defines the assert macro and refers to the NDEBUG macro,

   which is NOT defined in this file.

@@ -9,51 +10,62 @@
 

   If the NDEBUG macro is defined at the point where assert.h

   is included, the assert macro is defined so as to not produce code.

-  Otherwise, the assertion is tested and if the assertion is true a

-  diagnostic message of the form

-  "ASSERT <FileName>(<LineNumber>): <Description>\n" is produced.

-  A true assertion will also result in the application being terminated.

-

-  The behavior of the assert macro can be further modified by setting attributes

-  in the PcdDebugPropertyMask PCD entry when building the Application Toolkit.

-  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of PcdDebugProperyMask is set

-  then CpuBreakpoint() is called. Otherwise, if the

-  DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then

-  CpuDeadLoop() is called.  If neither of these bits are set, then the

-  application will be terminated immediately after the message is printed to

-  the debug output device.

-

-Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

-This program and the accompanying materials are licensed and made available under

-the terms and conditions of the BSD License that accompanies this distribution.

-The full text of the license may be found at

-http://opensource.org/licenses/bsd-license.php.

-

-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+  Otherwise, the assertion is tested and if the assertion is FALSE

+  (e.g. evaluates to 0) a diagnostic message of the form<BR>

+  "Assertion failed: (EXPR), file FILE, function FUNC, line LINE.\n"<BR>

+  is produced.

+  A FALSE evaluation will also result in the application being aborted.

 

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials are licensed and made available under

+  the terms and conditions of the BSD License that accompanies this distribution.

+  The full text of the license may be found at

+  http://opensource.org/licenses/bsd-license.

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 **/

 #include  <sys/EfiCdefs.h>

 

 #undef  assert        ///< Remove any existing definition for assert.

 

+/** Internal helper function for the assert macro.

+    The __assert function prints a diagnostic message then exits the

+    currently running application.

+

+    This function should NEVER be called directly.

+

+    Some pre-processors do not provide the __func__ identifier.  When that is

+    the case, __func__ will be NULL.  This function accounts for this and

+    will modify the diagnostic message appropriately.

+

+

+    @param[in]    file          The name of the file containing the assert.

+    @param[in]    func          The name of the function containing the assert.

+    @param[in]    line          The line number the assert is located on.

+    @param[in]    failedexpr    A literal representation of the assert's expression.

+

+    @return       The __assert function will never return.  It aborts the

+                  current application and returns to the environment that

+                  the application was launched from.

+**/

 extern void

-__assert(const char *func, const char *file, int line, const char *failedexpr);

+__assert(const char *file, const char *func, int line, const char *failedexpr);

 

 /** The assert macro puts diagnostic tests into programs; it expands to a

     void expression.

 

-    When it is executed, if expression (which shall have a scalar type) is

-    false (that is, compares equal to 0), the assert macro writes information

+    When it is executed, if expression (which must have a scalar type) is

+    FALSE (that is, compares equal to 0), the assert macro writes information

     about the particular call that failed (including the text of the argument,

     the name of the source file, the source line number, and the name of the

     enclosing function - the latter are respectively the values of the

     preprocessing macros __FILE__ and __LINE__ and of the identifier __func__)

     on the standard error stream. It then calls the abort function.

 

-  If NDEBUG is not defined, Expression is evaluated.  If Expression evaluates to FALSE, then

-  __assert is called passing in the source filename, source function, source line number,

-  and the Expression.

+  If NDEBUG is not defined, Expression is evaluated.  If Expression evaluates to FALSE,

+  then __assert is called passing in the source filename, source function, source

+  line number, and the Expression.

 

   @param  Expression  Boolean expression.

 

@@ -64,7 +76,7 @@ __assert(const char *func, const char *file, int line, const char *failedexpr);
 

 #else

 #define assert(Expression)   ((Expression) ? (void)0 :\

-                              __assert(__func__, __FILE__, __LINE__, #Expression) )

+                              __assert(__FILE__, __func__, __LINE__, #Expression) )

 #endif

 /// @}

 /* END of file assert.h */

diff --git a/StdLib/Include/ctype.h b/StdLib/Include/ctype.h
index 1796b81db7..64bccd5f66 100644
--- a/StdLib/Include/ctype.h
+++ b/StdLib/Include/ctype.h
@@ -1,5 +1,5 @@
 /** @file

-  Single-byte character classification and case conversion macros and

+  Single-byte character classification, case conversion macros, and

   function declarations.

 

   The header <ctype.h> declares several functions useful for testing and mapping

@@ -11,19 +11,18 @@
   default is the "C" locale.

 

   The term "printing character" refers to a member of a locale-specific

-  set of characters, each of which occupies one printing position on a display

+  set of characters, each of which occupies at least one printing position on an output

   device; the term control character refers to a member of a locale-specific

   set of characters that are not printing characters.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #ifndef _CTYPE_H

 #define _CTYPE_H

@@ -36,8 +35,10 @@ __BEGIN_DECLS
 /** The isalnum function tests for any character for which isalpha or isdigit

     is true.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isalnum(int c);

 

@@ -47,29 +48,37 @@ int isalnum(int c);
     isspace is true. In the "C" locale, isalpha returns true only for the

     characters for which isupper or islower is true.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isalpha(int c);

 

 /** The iscntrl function tests for any control character.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int iscntrl(int c);

 

 /** The isdigit function tests for any decimal-digit character.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isdigit(int c);

 

 /** The isgraph function tests for any printing character except space (' ').

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isgraph(int c);

 

@@ -78,15 +87,19 @@ int isgraph(int c);
     isdigit, ispunct, or isspace is true.  In the "C" locale, islower returns

     true only for the lowercase letters.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int islower(int c);

 

 /** The isprint function tests for any printing character including space (' ').

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isprint(int c);

 

@@ -95,8 +108,10 @@ int isprint(int c);
     isalnum is true. In the "C" locale, ispunct returns true for every printing

     character for which neither isspace nor isalnum is true.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int ispunct(int c);

 

@@ -107,8 +122,10 @@ int ispunct(int c);
     horizontal tab ('\t'), and vertical tab ('\v'). In the "C" locale, isspace

     returns true only for the standard white-space characters.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isspace(int c);

 

@@ -117,29 +134,47 @@ int isspace(int c);
     isdigit, ispunct, or isspace is true. In the "C" locale, isupper returns

     true only for the uppercase letters.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isupper(int c);

 

 /** The isxdigit function tests for any hexadecimal-digit character.

 

-    @return   Returns nonzero (true) if and only if the value of the argument c

-              conforms to that in the description of the function.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isxdigit(int c);

 

-/** The isascii function tests that a character is one of the 128 ASCII characters.

+/** The isblank function tests that a character is a white-space character that results

+    in a number of space (' ') characters being sent to the output device.  In the C locale

+    this is either ' ' or '\t'.

 

-  @param[in]  c   The character to test.

-  @return     Returns nonzero (true) if c is a valid ASCII character.  Otherwize,

-              zero (false) is returned.

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

+**/

+int isblank(int);

+

+/** The isascii function tests that a character is one of the 128 7-bit ASCII characters.

+

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

 int isascii(int c);

 

 /** The tolower function converts an uppercase letter to a corresponding

     lowercase letter.

 

+    @param[in]    c   The character to be converted.

+

     @return   If the argument is a character for which isupper is true and

               there are one or more corresponding characters, as specified by

               the current locale, for which islower is true, the tolower

@@ -152,6 +187,8 @@ int tolower(int c);
 /** The toupper function converts a lowercase letter to a corresponding

     uppercase letter.

 

+    @param[in]    c   The character to be converted.

+

     @return   If the argument is a character for which islower is true and

               there are one or more corresponding characters, as specified by

               the current locale, for which isupper is true, the toupper

@@ -161,13 +198,13 @@ int tolower(int c);
 **/

 int toupper(int c);

 

-int isblank(int);

-

 __END_DECLS

 

-// Character Classification Macros

-// Undefine individually or define NO_CTYPE_MACROS, before including <ctype.h>,

-// in order to use the Function version of the character classification macros.

+/** Character Classification Macros.

+    Undefine individually or define NO_CTYPE_MACROS, before including <ctype.h>,

+    in order to use the Function version of the character classification macros.

+@{

+**/

 #ifndef NO_CTYPE_MACROS

   #define isalnum(c)    (__isCClass( (int)c, (_CD | _CU | _CL | _XA)))

   #define isalpha(c)    (__isCClass( (int)c, (_CU | _CL | _XA)))

@@ -183,5 +220,6 @@ __END_DECLS
   #define tolower(c)    (__toLower((int)c))

   #define toupper(c)    (__toUpper((int)c))

 #endif  /* NO_CTYPE_MACROS */

+///@}

 

 #endif  /* _CTYPE_H */

diff --git a/StdLib/Include/errno.h b/StdLib/Include/errno.h
index 9c6e071a2a..4989d4d150 100644
--- a/StdLib/Include/errno.h
+++ b/StdLib/Include/errno.h
@@ -1,28 +1,43 @@
 /** @file

-  The header <errno.h> defines several values, all relating to the reporting of

+  The header <errno.h> defines several macros, all relating to the reporting of

   error conditions.

 

-  The enum members expand to integral constant expressions

+  The macros expand to integral constant expressions

   with distinct nonzero values, suitable for use in #if preprocessing

-  directives; and errno which expands to a modifiable lvalue that has type int,

+  directives.

+

+  The ISO/IEC 9899 specification requires that these be macros.

+

+  The macros expand to integral constant expressions

+  with distinct nonzero values, suitable for use in #if preprocessing

+  directives; the variable errno which expands to a modifiable lvalue that has type int,

   the value of which is set to a positive error number by several library

-  functions.

+  functions; and the variable EFIerrno which is an extension allowing the return status

+  of the underlying UEFI functions to be returned.

 

-  The value of errno is zero at program startup, but is never set to zero by

+  The value of errno and EFIerrno is zero at program startup.  On program startup, errno

+  is initialized to zero but is never set to zero by

   any library function.  The value of errno may be set to a non-zero value by

   a library function call whether or not there is an error, provided the use

-  of errno is not is not documented in the description of the function in

-  the governing standard: ISO/IEC 9899:1990 with Amendment 1 or ISO/IEC 9899:1999.

+  of errno is not documented in the description of the function in

+  the governing standard: ISO/IEC 9899:1990 with Amendment 1 or ISO/IEC 9899:199409.

+

+  EFIerrno, like errno, should only be checked if it is known that the preceeding function call

+  called a UEFI function.  Functions in which UEFI functions are called dependent upon context

+  or parameter values should guarantee that EFIerrno is set to zero by default, or to the status

+  value returned by any UEFI functions which are called.

 

-Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

-This program and the accompanying materials are licensed and made available under

-the terms and conditions of the BSD License that accompanies this distribution.

-The full text of the license may be found at

-http://opensource.org/licenses/bsd-license.php.

+  All macro definitions in this list must begin with the letter 'E'

+  and be followed by a digit or an uppercase letter.

 

-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials are licensed and made available under

+  the terms and conditions of the BSD License that accompanies this distribution.

+  The full text of the license may be found at

+  http://opensource.org/licenses/bsd-license.

 

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 **/

 #ifndef _ERRNO_H

 #define _ERRNO_H

@@ -38,42 +53,42 @@ extern  RETURN_STATUS   EFIerrno;
 

 #define EMINERRORVAL      __EMINERRORVAL          /* The lowest valid error value */

 

-#define EPERM             __EPERM                 /*  1   Operation not permitted */

-#define ENOENT            __ENOENT                /*  2   No such file or directory */

-#define ESRCH             __ESRCH                 /*  3   No such process */

-#define EINTR             __EINTR                 /*  4   Interrupted system call */

-#define EIO               __EIO                   /*  5   Input/output error */

-#define ENXIO             __ENXIO                 /*  6   Device not configured */

-#define E2BIG             __E2BIG                 /*  7   Argument list too long */

-#define ENOEXEC           __ENOEXEC               /*  8   Exec format error */

-#define EBADF             __EBADF                 /*  9   Bad file descriptor */

-#define ECHILD            __ECHILD                /* 10   No child processes */

-#define EDEADLK           __EDEADLK               /* 11   Resource deadlock avoided */

-#define ENOMEM            __ENOMEM                /* 12   Cannot allocate memory */

-#define EACCES            __EACCES                /* 13   Permission denied */

-#define EFAULT            __EFAULT                /* 14   Bad address */

-#define ENOTBLK           __ENOTBLK               /* 15   Block device required */

-#define EBUSY             __EBUSY                 /* 16   Device busy */

-#define EEXIST            __EEXIST                /* 17   File exists */

-#define EXDEV             __EXDEV                 /* 18   Cross-device link */

-#define ENODEV            __ENODEV                /* 19   Operation not supported by device */

-#define ENOTDIR           __ENOTDIR               /* 20   Not a directory */

-#define EISDIR            __EISDIR                /* 21   Is a directory */

-#define EINVAL            __EINVAL                /* 22   Invalid argument */

-#define ENFILE            __ENFILE                /* 23   Too many open files in system */

-#define EMFILE            __EMFILE                /* 24   Too many open file descriptors */

-#define ENOTTY            __ENOTTY                /* 25   Inappropriate ioctl for device */

-#define ETXTBSY           __ETXTBSY               /* 26   Text file busy */

-#define EFBIG             __EFBIG                 /* 27   File too large */

-#define ENOSPC            __ENOSPC                /* 28   No space left on device */

-#define ESPIPE            __ESPIPE                /* 29   Illegal seek */

-#define EROFS             __EROFS                 /* 30   Read-only filesystem */

-#define EMLINK            __EMLINK                /* 31   Too many links */

-#define EPIPE             __EPIPE                 /* 32   Broken pipe */

+#define EPERM             __EPERM                 /* Operation not permitted */

+#define ENOENT            __ENOENT                /* No such file or directory */

+#define ESRCH             __ESRCH                 /* No such process */

+#define EINTR             __EINTR                 /* Interrupted system call */

+#define EIO               __EIO                   /* Input/output error */

+#define ENXIO             __ENXIO                 /* Device not configured */

+#define E2BIG             __E2BIG                 /* Argument list too long */

+#define ENOEXEC           __ENOEXEC               /* Exec format error */

+#define EBADF             __EBADF                 /* Bad file descriptor */

+#define ECHILD            __ECHILD                /* No child processes */

+#define EDEADLK           __EDEADLK               /* Resource deadlock avoided */

+#define ENOMEM            __ENOMEM                /* Cannot allocate memory */

+#define EACCES            __EACCES                /* Permission denied */

+#define EFAULT            __EFAULT                /* Bad address */

+#define ENOTBLK           __ENOTBLK               /* Block device required */

+#define EBUSY             __EBUSY                 /* Device busy */

+#define EEXIST            __EEXIST                /* File exists */

+#define EXDEV             __EXDEV                 /* Cross-device link */

+#define ENODEV            __ENODEV                /* Operation not supported by device */

+#define ENOTDIR           __ENOTDIR               /* Not a directory */

+#define EISDIR            __EISDIR                /* Is a directory */

+#define EINVAL            __EINVAL                /* Invalid argument */

+#define ENFILE            __ENFILE                /* Too many open files in system */

+#define EMFILE            __EMFILE                /* Too many open file descriptors */

+#define ENOTTY            __ENOTTY                /* Inappropriate ioctl for device */

+#define ETXTBSY           __ETXTBSY               /* Text file busy */

+#define EFBIG             __EFBIG                 /* File too large */

+#define ENOSPC            __ENOSPC                /* No space left on device */

+#define ESPIPE            __ESPIPE                /* Illegal seek */

+#define EROFS             __EROFS                 /* Read-only filesystem */

+#define EMLINK            __EMLINK                /* Too many links */

+#define EPIPE             __EPIPE                 /* Broken pipe */

 

 /* math software -- these are the only two values required by the C Standard */

-#define EDOM              __EDOM                  /* 33   Numerical argument out of domain */

-#define ERANGE            __ERANGE                /* 34   Result too large */

+#define EDOM              __EDOM                  /* 3umerical argument out of domain */

+#define ERANGE            __ERANGE                /* 3esult too large */

 

 /* non-blocking and interrupt i/o */

 #define EAGAIN            __EAGAIN                /* 35   Resource temporarily unavailable */

diff --git a/StdLib/Include/sys/_ctype.h b/StdLib/Include/sys/_ctype.h
index e5872f48f8..6c2b327411 100644
--- a/StdLib/Include/sys/_ctype.h
+++ b/StdLib/Include/sys/_ctype.h
@@ -12,38 +12,40 @@
 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #ifndef _CTYPE_H

 #error  This file, <sys/_ctype.h>, may only be included by <ctype.h>.

 #endif

 

 __BEGIN_DECLS

-extern const UINT16 *_cClass;  // Locale independent pointer to Character Classification Table

-extern const UINT8  *_uConvT;  // Locale independent pointer to Lowercase to Uppercase Conversion Table

-extern const UINT8  *_lConvT;  // Locale independent pointer to Uppercase to Lowercase Conversion Table

+extern const UINT16 *_cClass;  ///< Locale independent pointer to Character Classification Table.

+extern const UINT8  *_uConvT;  ///< Locale independent pointer to Lowercase to Uppercase Conversion Table.

+extern const UINT8  *_lConvT;  ///< Locale independent pointer to Uppercase to Lowercase Conversion Table.

 

-extern  int  __isCClass( int _c, unsigned int mask);   // Internal character classification function

+extern  int  __isCClass( int _c, unsigned int mask);   ///< Internal character classification function.

 __END_DECLS

 

 

-// Character Class bit masks

-#define _CC   0x0001U     // Control Characters

-#define _CW   0x0002U     // White Space

-#define _CP   0x0004U     // Punctuation

-#define _CD   0x0008U     // Digits [0-9]

-#define _CU   0x0010U     // Uppercase Letter [A-Z]

-#define _CL   0x0020U     // Lowercase Letter [a-z]

-#define _CX   0x0040U     // Hexadecimal Digits [A-Fa-f]

+/** Character Class bit masks.

+@{

+**/

+#define _CC   0x0001U     ///< Control Characters

+#define _CW   0x0002U     ///< White Space

+#define _CP   0x0004U     ///< Punctuation

+#define _CD   0x0008U     ///< Digits [0-9]

+#define _CU   0x0010U     ///< Uppercase Letter [A-Z]

+#define _CL   0x0020U     ///< Lowercase Letter [a-z]

+#define _CX   0x0040U     ///< Hexadecimal Digits [A-Fa-f]

 #define _C0   0x0080U

-#define _CS   0x0100U     // Space Characters, ' ' in C locale

-#define _CG   0x0200U     // Graphic Characters

-#define _CB   0x0400U     // Blank Characters, ' ' and '\t' in C locale

+#define _CS   0x0100U     ///< Space Characters, ' ' in C locale

+#define _CG   0x0200U     ///< Graphic Characters

+#define _CB   0x0400U     ///< Blank Characters, ' ' and '\t' in C locale

 #define _C4   0x0800U

-#define _XA   0x1000U     // eXtra Alpha characters not in _CU or _CL

+#define _XA   0x1000U     ///< eXtra Alpha characters not in _CU or _CL

 #define _C6   0x2000U

 #define _C7   0x4000U

 #define _C8   0x8000U

+/// @}

 

 #ifndef NO_CTYPE_MACROS

   #define __isCClass( _c, mask)   (((_c) < 0 || (_c) > 127) ? 0 : (_cClass[(_c)] & (mask)))

diff --git a/StdLib/Include/sys/errno.h b/StdLib/Include/sys/errno.h
index 3662c8d441..53c9e6903b 100644
--- a/StdLib/Include/sys/errno.h
+++ b/StdLib/Include/sys/errno.h
@@ -4,7 +4,8 @@
 

   The enum members expand to integral constant expressions

   with distinct nonzero values, suitable for use in #if preprocessing

-  directives.

+  directives.  These default values are specified as an enum in order to ease

+  the maintenance of the values.

 

   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

@@ -14,7 +15,6 @@
 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #ifdef  _ERRNO_H          // May only be included from <errno.h>

 #ifndef _SYS_ERRNO_H

diff --git a/StdLib/LibC/Ctype/CClass.c b/StdLib/LibC/Ctype/CClass.c
index f350063352..1e1e0fdccb 100644
--- a/StdLib/LibC/Ctype/CClass.c
+++ b/StdLib/LibC/Ctype/CClass.c
@@ -1,140 +1,253 @@
 /** @file

-  Character classification and case conversion functions for <ctype.h>.

+  Character classification function implementations for <ctype.h>.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #include  <LibConfig.h>

 

 #define NO_CTYPE_MACROS            // So that we don't define the classification macros

 #include  <ctype.h>

 

+/** Internal worker function for character classification.

+

+    Determines if a character is a member of a set of character classes.

+

+    @param[in]    _c      The character to be tested.

+    @param[in]    mask    A bitmapped specification of the character classes to

+                          test the character against.  These bits are defined

+                          in _ctype.h.

+

+    @retval   0         The character, _c, is NOT a member of the character classes specified by mask.

+    @retval   nonZero   The character, _c, IS a member of a specified character class.

+**/

 int

-__isCClass( int _c, unsigned int mask)

+__isCClass(

+  IN  int _c,

+  unsigned int mask

+  )

 {

   return ((_c < 0 || _c > 127) ? 0 : (_cClass[_c] & mask));

 }

 

-/**

+/** The isalnum function tests for any character for which isalpha or isdigit

+    is true.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isalnum(int c)

+int

+isalnum(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CD | _CU | _CL | _XA)));

 }

 

-/**

+/** The isalpha function tests for any character for which isupper or islower

+    is true, or any character that is one of a locale-specific set of

+    alphabetic characters for which none of iscntrl, isdigit, ispunct, or

+    isspace is true. In the "C" locale, isalpha returns true only for the

+    characters for which isupper or islower is true.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isalpha(int c)

+int

+isalpha(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CU | _CL | _XA)));

 }

 

-/**

+/** The iscntrl function tests for any control character.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int iscntrl(int c)

+int

+iscntrl(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CC)));

 }

 

-/**

+/** The isdigit function tests for any decimal-digit character.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isdigit(int c)

+int

+isdigit(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CD)));

 }

 

-/**

+/** The isgraph function tests for any printing character except space (' ').

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isgraph(int c)

+int

+isgraph(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CG)));

 }

 

-/**

+/** The islower function tests for any character that is a lowercase letter or

+    is one of a locale-specific set of characters for which none of iscntrl,

+    isdigit, ispunct, or isspace is true.  In the "C" locale, islower returns

+    true only for the lowercase letters.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int islower(int c)

+int

+islower(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CL)));

 }

 

-/**

+/** The isprint function tests for any printing character including space (' ').

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isprint(int c)

+int

+isprint(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CS | _CG)));

 }

 

-/**

+/** The ispunct function tests for any printing character that is one of a

+    locale-specific set of punctuation characters for which neither isspace nor

+    isalnum is true. In the "C" locale, ispunct returns true for every printing

+    character for which neither isspace nor isalnum is true.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int ispunct(int c)

+int

+ispunct(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CP)));

 }

 

-/**

+/** The isspace function tests for any character that is a standard white-space

+    character or is one of a locale-specific set of characters for which

+    isalnum is false. The standard white-space characters are the following:

+    space (' '), form feed ('\f'), new-line ('\n'), carriage return ('\r'),

+    horizontal tab ('\t'), and vertical tab ('\v'). In the "C" locale, isspace

+    returns true only for the standard white-space characters.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isspace(int c)

+int

+isspace(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CW)));

 }

 

-/**

+/** The isupper function tests for any character that is an uppercase letter or

+    is one of a locale-specific set of characters for which none of iscntrl,

+    isdigit, ispunct, or isspace is true. In the "C" locale, isupper returns

+    true only for the uppercase letters.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isupper(int c)

+int

+isupper(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CU)));

 }

 

-/**

+/** The isxdigit function tests for any hexadecimal-digit character.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isxdigit(int c)

+int

+isxdigit(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CD | _CX)));

 }

 

-#if defined(_NETBSD_SOURCE)

+/** The isblank function tests that a character is a white-space character that results

+    in a number of space (' ') characters being sent to the output device.  In the C locale

+    this is either ' ' or '\t'.

+

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

+**/

 int

-isblank(int c)

+isblank(

+  IN  int c

+  )

 {

   return (__isCClass( c, _CB));

 }

-#endif

 

-/** The isascii function tests that a character is one of the 128 ASCII characters.

+/** The isascii function tests that a character is one of the 128 7-bit ASCII characters.

 

   @param[in]  c   The character to test.

+

   @return     Returns nonzero (true) if c is a valid ASCII character.  Otherwize,

               zero (false) is returned.

 **/

-int isascii(int c){

+int

+isascii(

+  IN  int c

+  )

+{

   return ((c >= 0) && (c < 128));

 }

diff --git a/StdLib/LibC/Ctype/CConv.c b/StdLib/LibC/Ctype/CConv.c
index 6ad4f8722d..f551c43325 100644
--- a/StdLib/LibC/Ctype/CConv.c
+++ b/StdLib/LibC/Ctype/CConv.c
@@ -1,5 +1,5 @@
 /** @file

-  Case conversion functions for <ctype.h>

+  Case conversion function implementations for <ctype.h>

 

   The tolower function converts an uppercase letter to a corresponding

   lowercase letter.  If the argument is a character for which isupper

@@ -15,34 +15,56 @@
   of the corresponding characters (always the same one for any given locale);

   otherwise, the argument is returned unchanged.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #include  <LibConfig.h>

 

 #define NO_CTYPE_MACROS            // So that we don't define the classification macros

 #include  <ctype.h>

 

+/** The tolower function converts an uppercase letter to a corresponding

+    lowercase letter.

+

+    @param[in]    c   The character to be converted.

+

+    @return   If the argument is a character for which isupper is true and

+              there are one or more corresponding characters, as specified by

+              the current locale, for which islower is true, the tolower

+              function returns one of the corresponding characters (always the

+              same one for any given locale); otherwise, the argument is

+              returned unchanged.

+**/

 int

 tolower(

-  int _c

+  IN  int _c

   )

 {

-//  return ((_c < 0 || _c > 127) ? _c : _lConvT[_c]);

   return (isupper(_c) ? _lConvT[_c] : _c);

 }

 

-int toupper(

-  int _c

+/** The toupper function converts a lowercase letter to a corresponding

+    uppercase letter.

+

+    @param[in]    c   The character to be converted.

+

+    @return   If the argument is a character for which islower is true and

+              there are one or more corresponding characters, as specified by

+              the current locale, for which isupper is true, the toupper

+              function returns one of the corresponding characters (always the

+              same one for any given locale); otherwise, the argument is

+              returned unchanged.

+**/

+int

+toupper(

+  IN  int _c

   )

 {

-//  return ((_c < 0 || _c > 127) ? _c : _uConvT[_c]);

   return (islower(_c) ? _uConvT[_c] : _c);

 }

diff --git a/StdLib/LibC/Ctype/iCtype.c b/StdLib/LibC/Ctype/iCtype.c
index 69df21e7ae..6b289bf2f2 100644
--- a/StdLib/LibC/Ctype/iCtype.c
+++ b/StdLib/LibC/Ctype/iCtype.c
@@ -4,20 +4,19 @@
 

   These are the default, C locale, tables.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #include  <LibConfig.h>

 #include  <ctype.h>

 

-/// ASCII-8 Character Classification Table

+/// ASCII-7 Character Classification Table

 const UINT16  _C_CharClassTable[128] = {

   /* 00 NUL */    ( _CC ),

   /* 01 SOH */    ( _CC ),

@@ -149,7 +148,7 @@ const UINT16  _C_CharClassTable[128] = {
   /* 7F DEL */    ( _CC )

 };

 

-/// ASCII-8 Upper case to Lower case character conversion table

+/// ASCII-7 Upper case to Lower case character conversion table

 const UINT8  _C_ToLowerTable[128] = {

   /* 00 NUL */    0x00,           /* 01 SOH */    0x01,

   /* 02 STX */    0x02,           /* 03 ETX */    0x03,

@@ -217,7 +216,7 @@ const UINT8  _C_ToLowerTable[128] = {
   /* 7E '~' */    0x7E,           /* 7F DEL */    0x7F

 };

 

-/// ASCII-8 Lower case to Upper case character conversion table

+/// ASCII-7 Lower case to Upper case character conversion table

 const UINT8  _C_ToUpperTable[128] = {

   /* 00 NUL */    0x00,           /* 01 SOH */    0x01,

   /* 02 STX */    0x02,           /* 03 ETX */    0x03,

@@ -285,15 +284,21 @@ const UINT8  _C_ToUpperTable[128] = {
   /* 7E '~' */    0x7E,           /* 7F DEL */    0x7F

 };

 

-/// Default character classification table is 8-bit ASCII

+/// Default character classification table is 7-bit ASCII

 const UINT16  *_cClass = _C_CharClassTable;

 

-/// Default upper to lower conversion table is 8-bit ASCII

+/// Default upper to lower conversion table is 7-bit ASCII

 const UINT8  *_lConvT = _C_ToLowerTable;

 

-/// Default lower to upper conversion table is 8-bit ASCII

+/// Default lower to upper conversion table is 7-bit ASCII

 const UINT8  *_uConvT = _C_ToUpperTable;

 

+/** Sets the character classification and case conversion tables for the 'C' locale.

+

+    A set of locale-independent pointers are used to point to the classification and

+    conversion tables for the currently specified locale.  This function is used to

+    establish the tables for the 'C' locale.

+**/

 void

 __set_C_locale( void )

 {

diff --git a/StdLib/LibC/Main/assert.c b/StdLib/LibC/Main/assert.c
index a20a656ef0..a6b96d81d7 100644
--- a/StdLib/LibC/Main/assert.c
+++ b/StdLib/LibC/Main/assert.c
@@ -1,31 +1,57 @@
-/**

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+/** @file

+  The implementation of the __assert function used internally by the assert macro

+  to insert diagnostic messages into code.

+

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 **/

-//#include  <Uefi.h>

-//#include  <Library/UefiLib.h>

-

 #include  <LibConfig.h>

 #include  <sys/EfiCdefs.h>

 

 #include  <stdio.h>

 #include  <stdlib.h>

 

+/** Internal helper function for the assert macro.

+    The __assert function prints a diagnostic message then exits the

+    currently running application.

+

+    This function should NEVER be called directly.

+

+    Some pre-processors do not provide the __func__ identifier.  When that is

+    the case, __func__ will be NULL.  This function accounts for this and

+    will modify the diagnostic message appropriately.

+

+

+    @param[in]    file          The name of the file containing the assert.

+    @param[in]    func          The name of the function containing the assert

+                                or NULL.

+    @param[in]    line          The line number the assert is located on.

+    @param[in]    failedexpr    A literal representation of the assert's expression.

+

+    @return       The __assert function will never return.  It terminates execution

+                  of the current application and returns to the environment that

+                  the application was launched from.

+**/

 void

-__assert(const char *func, const char *file, int line, const char *failedexpr)

+__assert(

+  IN  const char *file,

+  IN  const char *func,

+  IN  int         line,

+  IN  const char *failedexpr

+  )

 {

   if (func == NULL)

     printf("Assertion failed: (%s), file %s, line %d.\n",

                 failedexpr, file, line);

   else

-    printf("Assertion failed: (%s), function %s, file %s, line %d.\n",

-                failedexpr, func, file, line);

+    printf("Assertion failed: (%s), file %s, function %s, line %d.\n",

+                failedexpr, file, func, line);

   abort();

   /* NOTREACHED */

 }