diff options
author | Zenith432 <zenith432@users.sourceforge.net> | 2017-12-12 18:12:11 +0100 |
---|---|---|
committer | Laszlo Ersek <lersek@redhat.com> | 2017-12-12 18:16:22 +0100 |
commit | e3e40c83fd2c6739512e8545a09848165facc0fb (patch) | |
tree | 3e3c26b9ae734e9c5df4063d2ece1ca61ac91704 /MdePkg/Include/Base.h | |
parent | 73d777329f84b5f4acdbc4369b56c0670e873cff (diff) | |
download | edk2-e3e40c83fd2c6739512e8545a09848165facc0fb.tar.gz edk2-e3e40c83fd2c6739512e8545a09848165facc0fb.tar.bz2 edk2-e3e40c83fd2c6739512e8545a09848165facc0fb.zip |
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>
Diffstat (limited to 'MdePkg/Include/Base.h')
-rw-r--r-- | MdePkg/Include/Base.h | 25 |
1 files changed, 17 insertions, 8 deletions
diff --git a/MdePkg/Include/Base.h b/MdePkg/Include/Base.h index 02140a5ac2..4fd5161f50 100644 --- a/MdePkg/Include/Base.h +++ b/MdePkg/Include/Base.h @@ -552,21 +552,24 @@ struct _LIST_ENTRY { #define BASE_8EB 0x8000000000000000ULL
//
-// Support for variable length argument lists using the ANSI standard.
+// Support for variable argument lists in freestanding edk2 modules.
//
-// Since we are using the ANSI standard we used the standard naming and
-// did not follow the coding convention
+// For modules that use the ISO C library interfaces for variable
+// argument lists, refer to "StdLib/Include/stdarg.h".
//
// VA_LIST - typedef for argument list.
// VA_START (VA_LIST Marker, argument before the ...) - Init Marker for use.
// VA_END (VA_LIST Marker) - Clear Marker
-// VA_ARG (VA_LIST Marker, var arg size) - Use Marker to get an argument from
-// the ... list. You must know the size and pass it in this macro.
+// VA_ARG (VA_LIST Marker, var arg type) - Use Marker to get an argument from
+// the ... list. You must know the type and pass it in this macro. Type
+// must be compatible with the type of the actual next argument (as promoted
+// according to the default argument promotions.)
// VA_COPY (VA_LIST Dest, VA_LIST Start) - Initialize Dest as a copy of Start.
//
-// example:
+// Example:
//
// UINTN
+// EFIAPI
// ExampleVarArg (
// IN UINTN NumberOfArgs,
// ...
@@ -582,15 +585,21 @@ struct _LIST_ENTRY { // VA_START (Marker, NumberOfArgs);
// for (Index = 0, Result = 0; Index < NumberOfArgs; Index++) {
// //
-// // The ... list is a series of UINTN values, so average them up.
+// // The ... list is a series of UINTN values, so sum them up.
// //
// Result += VA_ARG (Marker, UINTN);
// }
//
// VA_END (Marker);
-// return Result
+// return Result;
// }
//
+// Notes:
+// - Functions that call VA_START() / VA_END() must have a variable
+// argument list and must be declared EFIAPI.
+// - Functions that call VA_COPY() / VA_END() must be declared EFIAPI.
+// - Functions that only use VA_LIST and VA_ARG() need not be EFIAPI.
+//
/**
Return the size of argument that has been aligned to sizeof (UINTN).
|