MdePkg: correct and clarify documentation of VA_LIST in Base.h

This is to resolve bug 457.
https://bugzilla.tianocore.org/show_bug.cgi?id=457

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Zenith432 <zenith432@users.sourceforge.net>
Reviewed-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
[lersek@redhat.com: reconstruct commit from patch pasted into email]
Signed-off-by: Laszlo Ersek <lersek@redhat.com>

diff --git a/MdePkg/Include/Base.h b/MdePkg/Include/Base.h
index 02140a5ac2eea335d6aa330d0e4c4b113424c229..4fd5161f507cb5290e68d2fb9400a8356b96c80c 100644 (file)
--- a/MdePkg/Include/Base.h
+++ b/MdePkg/Include/Base.h
@@ -552,21 +552,24 @@ struct _LIST_ENTRY {
 #define  BASE_8EB    0x8000000000000000ULL\r
 \r
 //\r
-//  Support for variable length argument lists using the ANSI standard.\r
+//  Support for variable argument lists in freestanding edk2 modules.\r
 //\r
-//  Since we are using the ANSI standard we used the standard naming and\r
-//  did not follow the coding convention\r
+//  For modules that use the ISO C library interfaces for variable\r
+//  argument lists, refer to "StdLib/Include/stdarg.h".\r
 //\r
 //  VA_LIST  - typedef for argument list.\r
 //  VA_START (VA_LIST Marker, argument before the ...) - Init Marker for use.\r
 //  VA_END (VA_LIST Marker) - Clear Marker\r
-//  VA_ARG (VA_LIST Marker, var arg size) - Use Marker to get an argument from\r
-//    the ... list. You must know the size and pass it in this macro.\r
+//  VA_ARG (VA_LIST Marker, var arg type) - Use Marker to get an argument from\r
+//    the ... list. You must know the type and pass it in this macro.  Type\r
+//    must be compatible with the type of the actual next argument (as promoted\r
+//    according to the default argument promotions.)\r
 //  VA_COPY (VA_LIST Dest, VA_LIST Start) - Initialize Dest as a copy of Start.\r
 //\r
-//  example:\r
+//  Example:\r
 //\r
 //  UINTN\r
+//  EFIAPI\r
 //  ExampleVarArg (\r
 //    IN UINTN  NumberOfArgs,\r
 //    ...\r
@@ -582,15 +585,21 @@ struct _LIST_ENTRY {
 //    VA_START (Marker, NumberOfArgs);\r
 //    for (Index = 0, Result = 0; Index < NumberOfArgs; Index++) {\r
 //      //\r
-//      // The ... list is a series of UINTN values, so average them up.\r
+//      // The ... list is a series of UINTN values, so sum them up.\r
 //      //\r
 //      Result += VA_ARG (Marker, UINTN);\r
 //    }\r
 //\r
 //    VA_END (Marker);\r
-//    return Result\r
+//    return Result;\r
 //  }\r
 //\r
+//  Notes:\r
+//  - Functions that call VA_START() / VA_END() must have a variable\r
+//    argument list and must be declared EFIAPI.\r
+//  - Functions that call VA_COPY() / VA_END() must be declared EFIAPI.\r
+//  - Functions that only use VA_LIST and VA_ARG() need not be EFIAPI.\r
+//\r
 \r
 /**\r
   Return the size of argument that has been aligned to sizeof (UINTN).\r