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

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

6 files changed, 162 insertions, 109 deletions

diff --git a/StdLib/Include/Ia32/machine/limits.h b/StdLib/Include/Ia32/machine/limits.h
index 0b3cfbe4c5..f072e54a7d 100644
--- a/StdLib/Include/Ia32/machine/limits.h
+++ b/StdLib/Include/Ia32/machine/limits.h
@@ -1,14 +1,33 @@
+/** @file

+  This header <machine/limits.h> defines several macros that expand to various

+  CPU-architecture-specific limits and parameters of the standard integer types.

+

+  The values given below are constant expressions suitable for use

+  in #if preprocessing directives.

+

+  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  <x86/limits.h>

 

+/** Number of bits making up a pointer. **/

 #define __POINTER_BIT   32

+

+/** Number of bits comprising an object of type long int. **/

 #define __LONG_BIT      32

 

-/** minimum value for an object of type long int **/

-#define __LONG_MIN    (-2147483647L - 1L) // -(2^31 - 1)

+/** Minimum value for an object of type long int. **/

+#define __LONG_MIN    (-2147483647L - 1L)   // -(2^31 - 1)

 

-/** maximum value for an object of type long int **/

-#define __LONG_MAX    +2147483647L // 2^31 - 1

+/** Maximum value for an object of type long int. **/

+#define __LONG_MAX    +2147483647L          // 2^31 - 1

 

-/** maximum value for an object of type unsigned long int **/

-#define __ULONG_MAX   0xffffffff // 2^32 - 1

+/** Maximum value for an object of type unsigned long int. **/

+#define __ULONG_MAX   0xffffffff            // 2^32 - 1

 

diff --git a/StdLib/Include/iso646.h b/StdLib/Include/iso646.h
index db3450193d..d9dc860346 100644
--- a/StdLib/Include/iso646.h
+++ b/StdLib/Include/iso646.h
@@ -17,16 +17,16 @@
 #define _ISO646_H

 #include  <sys/EfiCdefs.h>

 

-#define and     &&

-#define and_eq  &=

-#define bitand  &

-#define bitor   |

-#define compl   ~

-#define not     !

-#define not_eq  !=

-#define or      ||

-#define or_eq   |=

-#define xor     ^

-#define xor_eq  ^=

+#define and     &&    ///< Logical AND of two boolean expressions

+#define and_eq  &=    ///< Bitwise AND with assignment to lval

+#define bitand  &     ///< Bitwise AND of two scalar expressions

+#define bitor   |     ///< Bitwise OR of two scalar expressions

+#define compl   ~     ///< Binary complement

+#define not     !     ///< Logical complement of a boolean expression

+#define not_eq  !=    ///< Not-equal comparison

+#define or      ||    ///< Logical OR of two boolean expressions

+#define or_eq   |=    ///< Bitwise OR with assignment to lval

+#define xor     ^     ///< Exclusive OR

+#define xor_eq  ^=    ///< Exclusive OR with assignment to lval

 

 #endif  /* _ISO646_H */

diff --git a/StdLib/Include/limits.h b/StdLib/Include/limits.h
index c0e60fe007..4fceca2015 100644
--- a/StdLib/Include/limits.h
+++ b/StdLib/Include/limits.h
@@ -2,30 +2,20 @@
   The header <limits.h> defines several macros that expand to various limits and

   parameters of the standard integer types.

 

-  The values given below shall be replaced by constant expressions suitable for

-  use in #if preprocessing directives. Moreover, except for CHAR_BIT and

-  MB_LEN_MAX, the following shall be replaced by expressions that have the same

+  The values given below are constant expressions suitable for

+  use in #if preprocessing directives. Except for CHAR_BIT and

+  MB_LEN_MAX, they have the same

   type as would an expression that is an object of the corresponding type

-  converted according to the integer promotions. Their implementation-defined

-  values shall be equal or greater in magnitude (absolute value) to those

-  documented, with the same sign.

-

-  If the value of an object of type char is treated as a signed integer when

-  used in an expression, the value of CHAR_MIN shall be the same as that of

-  SCHAR_MIN and the value of CHAR_MAX shall be the same as that of SCHAR_MAX.

-  Otherwise, the value of CHAR_MIN shall be 0 and the value of CHAR_MAX shall

-  be the same as that of UCHAR_MAX.)

-  The value UCHAR_MAX shall equal 2^(CHAR_BIT - 1).

-

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

+  converted according to the integer promotions.

+

+  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 _LIMITS_H

 #define _LIMITS_H

@@ -35,86 +25,91 @@
 /* Get the architecturally defined limits for this compilation unit. */

 #include  <machine/limits.h>

 

-/* Define the values required by Specification. */

+/* Define the values required by the ISO/IEC 9899 Specification. */

 

-/** maximum number of bytes in a multibyte character, for any supported locale **/

-#define MB_LEN_MAX  2 /* 16-bit UTC-2 */

+/** Maximum number of bytes in a multibyte character, for any supported locale. **/

+#define MB_LEN_MAX  2               /* 16-bit UTC-2 */

 

-/** Number of bits for smallest object that is not a bit-field (byte). **/

+/** Number of bits comprising the smallest object that is not a bit-field (byte). **/

 #define CHAR_BIT    __CHAR_BIT

 

-/** minimum value for an object of type signed char **/

+/** Minimum value for an object of type signed char. **/

 #define SCHAR_MIN   __SCHAR_MIN

 

-/** maximum value for an object of type signed char **/

+/** Maximum value for an object of type signed char. **/

 #define SCHAR_MAX   __SCHAR_MAX

 

-/** maximum value for an object of type unsigned char **/

+/** Maximum value for an object of type unsigned char. **/

 #define UCHAR_MAX   __UCHAR_MAX

 

 #ifdef __CHAR_UNSIGNED__

-  /** maximum value for an object of type char **/

+  /** Maximum value for an object of type char. **/

   #define CHAR_MAX  UCHAR_MAX

-  /** minimum value for an object of type char **/

+  /** Minimum value for an object of type char. **/

   #define CHAR_MIN  0

 #else

-  /** maximum value for an object of type char **/

+  /** Maximum value for an object of type char. **/

   #define CHAR_MAX  SCHAR_MAX

-  /** minimum value for an object of type char **/

+  /** Minimum value for an object of type char. **/

   #define CHAR_MIN  SCHAR_MIN

 #endif

 

-/** minimum value for an object of type short int **/

+/** Minimum value for an object of type short int. **/

 #define SHRT_MIN    __SHRT_MIN

 

-/** maximum value for an object of type short int **/

+/** Maximum value for an object of type short int. **/

 #define SHRT_MAX    __SHRT_MAX

 

-/** maximum value for an object of type unsigned short int **/

+/** Maximum value for an object of type unsigned short int. **/

 #define USHRT_MAX   __USHRT_MAX

 

-/** minimum value for an object of type int **/

+/** Minimum value for an object of type int. **/

 #define INT_MIN     __INT_MIN

 

-/** maximum value for an object of type int **/

+/** Maximum value for an object of type int. **/

 #define INT_MAX     __INT_MAX

 

-/** maximum value for an object of type unsigned int **/

+/** Maximum value for an object of type unsigned int. **/

 #define UINT_MAX    __UINT_MAX

 

-/** minimum value for an object of type long int **/

+/** Minimum value for an object of type long int. **/

 #define LONG_MIN    __LONG_MIN

 

-/** maximum value for an object of type long int **/

+/** Maximum value for an object of type long int. **/

 #define LONG_MAX    __LONG_MAX

 

-/** maximum value for an object of type unsigned long int **/

+/** Maximum value for an object of type unsigned long int. **/

 #define ULONG_MAX   __ULONG_MAX

 

-/** minimum value for an object of type long long int **/

+/** Minimum value for an object of type long long int. **/

 #define LLONG_MIN   __LLONG_MIN

 

-/** maximum value for an object of type long long int **/

+/** Maximum value for an object of type long long int. **/

 #define LLONG_MAX   __LLONG_MAX

 

-/** maximum value for an object of type unsigned long long int **/

+/** Maximum value for an object of type unsigned long long int. **/

 #define ULLONG_MAX  __ULLONG_MAX

 

 /* Object limits used in the Standard Libraries */

 #if (PcdGet32(PcdMaximumAsciiStringLength) > 0)

+  /** Maximum length of an arbitrary "narrow-character" string. **/

   #define ASCII_STRING_MAX    PcdGet32(PcdMaximumAsciiStringLength)

 #else

+  /** Maximum length of an arbitrary "narrow-character" string. **/

   #define ASCII_STRING_MAX    256

 #endif

 

 #if (PcdGet32(PcdMaximumUnicodeStringLength) > 0)

+  /** Maximum length of an arbitrary "wide-character" string. **/

   #define UNICODE_STRING_MAX    PcdGet32(PcdMaximumUnicodeStringLength)

 #else

+  /** Maximum length of an arbitrary "wide-character" string. **/

   #define UNICODE_STRING_MAX    512

 #endif

 

 /* Limits for BSD Compatibility */

 #define NL_TEXTMAX    2048

+

 #include  <sys/syslimits.h>

 

 #endif  /* _LIMITS_H */

diff --git a/StdLib/Include/locale.h b/StdLib/Include/locale.h
index 220f35a043..73a6bf4ca7 100644
--- a/StdLib/Include/locale.h
+++ b/StdLib/Include/locale.h
@@ -1,6 +1,15 @@
-/*  $NetBSD: locale.h,v 1.14 2005/02/03 04:39:32 perry Exp $  */

+/** @file

+  Localization functions and macros.

+

+  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.

 

-/*

  * Copyright (c) 1991, 1993

  *  The Regents of the University of California.  All rights reserved.

  *

@@ -29,11 +38,15 @@
  * SUCH DAMAGE.

  *

  *  @(#)locale.h  8.1 (Berkeley) 6/2/93

- */

+ *  $NetBSD: locale.h,v 1.14 2005/02/03 04:39:32 perry Exp

+**/

 

 #ifndef _LOCALE_H_

 #define _LOCALE_H_

 

+/** This is a structure containing members pertaining to the formatting of numeric values.

+    There is no requirement for members of this structure to be in any particular order.

+**/

 struct lconv {

   char  *decimal_point;

   char  *thousands_sep;

@@ -61,27 +74,42 @@ struct lconv {
   char  int_n_sign_posn;

 };

 

-#define LC_ALL      0

-#define LC_COLLATE  1

-#define LC_CTYPE    2

-#define LC_MONETARY 3

-#define LC_NUMERIC  4

-#define LC_TIME     5

-#define LC_MESSAGES 6

+/** These macros expand to integer expressions suitable for use as the first

+    argument to the setlocale() function.

 

-#define _LC_LAST    7   /* marks end */

+    Only the first six macros are required by the C language specification.

+    Implementations are free to extend this list, as has been done with LC_MESSAGES,

+    with additional macro definitions, beginning with the characters LC_ and

+    an uppercase letter.

+@{

+**/

+#define LC_ALL      0   ///< The application's entire locale.

+#define LC_COLLATE  1   ///< Affects the behavior of the strcoll and strxfrm functions.

+#define LC_CTYPE    2   ///< Affects the behavior of the character handling, multibyte, and wide character functions.

+#define LC_MONETARY 3   ///< Affects monetary formatting information.

+#define LC_NUMERIC  4   ///< Affects the decimal-point character and non-monetary formatting information.

+#define LC_TIME     5   ///< Affects the behavior of the strftime and wcsftime functions.

+#define LC_MESSAGES 6

+#define _LC_LAST    7   ///< Number of defined macros. Marks end.

+/// @}

 

 #include  <sys/EfiCdefs.h>

 

+/** @fn   char *setlocale(int, const char *)

+**/

+

+/** @fn   struct lconv *localeconv(void)

+**/

+

 __BEGIN_DECLS

-struct lconv  *localeconv(void);

-  char    *__setlocale_mb_len_max_32(int, const char *);

 #ifdef __SETLOCALE_SOURCE__

   char    *setlocale(int, const char *);

   char    *__setlocale(int, const char *);

 #else /* !__SETLOCALE_SOURCE__ */

   char    *setlocale(int, const char *) __RENAME(__setlocale_mb_len_max_32);

 #endif /* !__SETLOCALE_SOURCE__ */

+struct lconv  *localeconv(void);

+  char    *__setlocale_mb_len_max_32(int, const char *);

 __END_DECLS

 

 #endif /* _LOCALE_H_ */

diff --git a/StdLib/Include/sys/syslimits.h b/StdLib/Include/sys/syslimits.h
index d308387f2a..bee810cc12 100644
--- a/StdLib/Include/sys/syslimits.h
+++ b/StdLib/Include/sys/syslimits.h
@@ -1,6 +1,15 @@
-/*  $NetBSD: syslimits.h,v 1.23 2005/12/11 12:25:21 christos Exp $  */

+/** @file

+  Platform specific values for <limits.h>.

+

+  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.

 

-/*

  * Copyright (c) 1988, 1993

  *  The Regents of the University of California.  All rights reserved.

  *

@@ -28,28 +37,30 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

  * SUCH DAMAGE.

  *

- *  @(#)syslimits.h 8.1 (Berkeley) 6/2/93

- */

+ *  syslimits.h 8.1 (Berkeley) 6/2/93

+ *  NetBSD: syslimits.h,v 1.23 2005/12/11 12:25:21 christos Exp

+**/

 

 #ifndef _SYS_SYSLIMITS_H_

 #define _SYS_SYSLIMITS_H_

 

 #include <sys/featuretest.h>

 

-#define ARG_MAX    (2 * 1024) /* max bytes for an exec function */

-#define ARGC_MAX       (64)   /* Maximum value for argc */

+#define ARG_MAX     (2 * 1024)  ///< Maximum bytes for an exec function.

+#define ARGC_MAX          (64)  ///< Maximum value for argc.

 

-#ifndef CHILD_MAX

-  #define CHILD_MAX     128 /* max simultaneous processes */

-#endif

-#define MAX_INPUT     255 /* max bytes in terminal input */

-#define NAME_MAX      255 /* max bytes in a file name */

+#define MAX_INPUT         255   ///< Maximum bytes in terminal input.

+#define NAME_MAX          255   ///< Maximum bytes in a file name.

 #ifndef OPEN_MAX

-  #define OPEN_MAX       20 /* max open files per process */

+  #define OPEN_MAX         20   ///< Maximum open files per process.

+#endif

+#define PATH_MAX         1024   ///< Maximum bytes in pathname.

+#define PIPE_BUF          512   ///< Maximum bytes for atomic pipe writes.

+

+#ifndef CHILD_MAX

+  #define CHILD_MAX       128   ///< Maximum simultaneous processes.

 #endif

-#define PATH_MAX     1024 /* max bytes in pathname */

-#define PIPE_BUF      512 /* max bytes for atomic pipe writes */

 

-#define LOGIN_NAME_MAX       17 /* max login name length incl. NUL */

+#define LOGIN_NAME_MAX     17   ///< Maximum login name length including the NUL.

 

 #endif /* !_SYS_SYSLIMITS_H_ */

diff --git a/StdLib/Include/x86/limits.h b/StdLib/Include/x86/limits.h
index 08222fa2d6..b5339c2fdc 100644
--- a/StdLib/Include/x86/limits.h
+++ b/StdLib/Include/x86/limits.h
@@ -1,14 +1,14 @@
 /** @file

-  Machine specific values for <limits.h>.

+  Intel x86 architecture (both Ia32 and X64) specific values for <limits.h>.

 

   Within this file, the ^ character is used in comments to represent exponentiation.

   Thus, 2^7 means "2 to the 7th power", NOT "2 XOR 7".

 

-  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.

@@ -19,49 +19,49 @@
 /** Number of bits for smallest object that is not a bit-field (byte). **/

 #define __CHAR_BIT    8

 

-/** minimum value for an object of type signed char **/

+/** Minimum value for an object of type signed char. **/

 #define __SCHAR_MIN   -128 // -(2^7 - 1)

 

-/** maximum value for an object of type signed char **/

+/** Maximum value for an object of type signed char. **/

 #define __SCHAR_MAX   +127 // 2^7 - 1

 

-/** maximum value for an object of type unsigned char **/

+/** Maximum value for an object of type unsigned char. **/

 #define __UCHAR_MAX   255  // 2^8 - 1

 

-/** minimum value for an object of type short int **/

+/** Minimum value for an object of type short int. **/

 #define __SHRT_MIN    -32768 // -(2^15 - 1)

 

-/** maximum value for an object of type short int **/

+/** Maximum value for an object of type short int. **/

 #define __SHRT_MAX    +32767 // 2^15 - 1

 

-/** maximum value for an object of type unsigned short int **/

+/** Maximum value for an object of type unsigned short int. **/

 #define __USHRT_MAX   65535 // 2^16 - 1

 

-/** maximum value for an object of type int **/

+/** Maximum value for an object of type int. **/

 #define __INT_MAX     +2147483647 // 2^31 - 1

 

-/** minimum value for an object of type int **/

+/** Minimum value for an object of type int. **/

 #define __INT_MIN     (-2147483647 - 1) // -(2^31 - 1)

 

-/** maximum value for an object of type unsigned int **/

+/** Maximum value for an object of type unsigned int. **/

 #define __UINT_MAX    0xffffffff // 2^32 - 1

 

-/** minimum value for an object of type long long int **/

-//#define __LLONG_MIN   -9223372036854775808LL // -(2^63 - 1)

-//#define __LLONG_MIN   ((-9223372036854775807LL)-1) // -(2^63 - 1)

-#define __LLONG_MIN   (-9223372036854775807LL - 1LL) // -(2^63 - 1)

+/** Minimum value for an object of type long long int. **/

+#define __LLONG_MIN   (-9223372036854775807LL - 1LL)  // -(2^63 - 1)

 

-/** maximum value for an object of type long long int **/

+/** Maximum value for an object of type long long int. **/

 #define __LLONG_MAX   9223372036854775807LL // 2^63 - 1

 

-/** maximum value for an object of type unsigned long long int **/

-//#define __ULLONG_MAX  18446744073709551615ULL // 2^64 - 1

+/** Maximum value for an object of type unsigned long long int. **/

 #define __ULLONG_MAX  0xFFFFFFFFFFFFFFFFULL // 2^64 - 1

 

-/* Intel extensions to <limits.h> for UEFI */

-#define __SHORT_BIT     16

-#define __WCHAR_BIT     16

-#define __INT_BIT       32

-#define __LONG_LONG_BIT 64

+/** Intel extensions to <limits.h> for UEFI

+@{

+**/

+#define __SHORT_BIT     16    ///< Number of bits comprising a short int.

+#define __WCHAR_BIT     16    ///< Number of bits comprising a wide character.

+#define __INT_BIT       32    ///< Number of bits comprising an int.

+#define __LONG_LONG_BIT 64    ///< Number of bits comprising a long long int.

+/// @}

 

 #endif    /* _MACHINE_LIMITS_H */