From e3e40c83fd2c6739512e8545a09848165facc0fb Mon Sep 17 00:00:00 2001 From: Zenith432 Date: Tue, 12 Dec 2017 18:12:11 +0100 Subject: [PATCH] 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 Reviewed-by: Laszlo Ersek Reviewed-by: Liming Gao [lersek@redhat.com: reconstruct commit from patch pasted into email] Signed-off-by: Laszlo Ersek --- MdePkg/Include/Base.h | 25 +++++++++++++++++-------- 1 file 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). -- 2.39.2