Request for documenting the EFI_{ENTRY,EXIT} functions

[Heinrich Schuchardt]

On 4/10/21 2:35 PM, Sughosh Ganu wrote:
> hi Heinrich,
> For the last one day, i was debugging an issue which i encountered when
> I tried to print the uefi env variables. This was seen both on arm64 and
> arm32 platforms. I have sent a patch for this fix[1].
>
> However, the reason i am writing to you is that, while i was debugging,
> i was looking at the functionality of the EFI_CALL macro, along with
> EFI_ENTRY AND EFI_EXIT. And i must admit that looking at the function
> names and symbol names was a bit confusing. This is because it is kind
> of difficult to guess the reference from which these symbols and
> functions are named.
>
> One example is the EFI_CALL macro, in which before the function is
> called, there is an assert check for __efi_exit_check. Once the function
> call returns, the assert check is for __efi_entry_check. This seems a
> bit counter-intuitive -- the call made at EFI_CALL beginning is named
> __efi_exit* and the one after the function return is named __efi_entry*.
> Same goes for the pointer names used for holding the gd values. There is
> an app_gd, and efi_gd. It is not very clear as to which is used where.

EFI_ENTRY() is used wherever an API call enters the firmware.
EFI_EXIT() is used wherever the firmware is left into the UEFI world.
EFI_CALL() replaces the sequence EFI_EXIT, function invocation, EFI_ENTRY.

app_gd is register r9/x18 of the UEFI world.
efi_gd is register r9/x18 of U-Boot.

>
> I see that you are the original author of the EFI_MACRO call, and thus

EFI_CALL() was introduced by Rob Clark in a095aadffa9.

> would be having a pretty good understanding of the nomenclature as well.
> So, given how much you trouble me during code review(pun intended :P), I
> was thinking to ask you for a favour. I was thinking if we can have a
> document which explains these macros, api's and gd pointers in a little
> detail. Can you please write such a document whenever you get time so
> that it would be useful for people like me. Thanks for your time and
> dedication to the u-boot project.
>
> -sughosh
> [1] - https://lists.denx.de/pipermail/u-boot/2021-April/446948.html
> <https://lists.denx.de/pipermail/u-boot/2021-April/446948.html>

I can create such a document.

Best regards

Heinrich