[PATCH 0/5] MdeModulePkg/EbcDxe: add ARM support

[Pete Batard <pete@akeo.ie>]

(This e-mail is fairly lengthy, so an Executive Summary is provided, for 
those who don't want to go through a wall of text).

0. Executive Summary
====================

0.1 Preamble
------------

One of the most vexing aspect of EFI Byte Code (EBC) proposal from the 
UEFI specs is that its EDK2 implementation has somewhat fallen short of 
its implicit goal of universality, due to the non availability of an EBC 
VM for all supported architectures.

As a consequence, we feel that this has resulted in major backtracking 
on EBC, such as EBC not being made a mandatory part of UEFI firmware 
implementations (in the same way as FAT) or not having a default 
provision for EBC bootloaders (e.g. /efi/boot/bootebc.arm).

Shortly after Ard Biesheuvel provided an EBC implementation for ARM64, 
last August, questions were raised with regards to being able to do the 
same for ARM due to issues with trying to work with the calling 
convention on that platform, and more specifically, with the 64-bit 
parameter marshalling that is required there. At the time, these 
problems were deemed difficult to tackle without the collaboration of 
third parties (such as external toolchain developers) or without having 
to restrict the scope of what EBC applications could do (such as 
limiting their access to only "known" EDK2 interfaces, for which 
parameter marshalling specifics would have been added).

This series of patches attempts to remedy all that, by proposing an ARM 
EBC implementation that solves the issues mentioned above in a generic 
and entirely self contained manner (i.e. within the EDK2). With this, 
the EDK2 should finally enable the execution of the same EBC binary 
across ALL supported UEFI architectures, and thus complete the implicit 
goal of EBC.

0.2 Solution Overview
---------------------

The gist of our marshalling solution can be summarized with being able 
to access a 16-bit value, at runtime, for native <-> EBC layer 
transition calls, that indicates which of (up to) 16 function call 
parameters is 64-bit. In turn, this enables the ARM EBC VM to "realign" 
said parameters to a 64-bit boundary as needed.

Hereafter, we will refer to these 16-bit values as a "call signatures".

Now, whereas this solution is self-contained, it does entail a minor 
change to the UEFI EBC specs, that mandates the insertion of call 
signatures at compilation time into the unused part of the 64-bit 
function pointer data object used by BREAK 5 (see 3.3).

However, this non breaking change is both backward and forward 
compatible. Especially, once the specs change is effected, and for *ALL* 
current EBC archs (IA32, IA64, X64, AARCH64):

a) EBC executables that were produced with the older version of the 
specs will run exactly as they did on EBC VMs that comply with the newer 
version of the specs

b) EBC executables that are produced with the newer version of the specs 
will run and perform the same, on EBC VMs that comply with either the 
older or newer version of the specs.

Also, and specifically for ARM (since other platforms are unaffected by 
such concerns), this whole proposal makes it possible for:

- Existing EBC binaries, that do not invoke BREAK 5 (i.e. no native to 
EBC calls) to run onto the proposed ARM EBC VM without any changes. 
Especially, these applications can perform EBC to native calls, on ARM, 
with no adverse effects.

- Existing EBC binaries, that do invoke BREAK 5, but that don't include 
signatures, to partially run on ARM. In this case, the ARM EBC VM will 
return an error status for calls issued from native to the EBC, allowing 
a native app to acknowledge incompatibility issues and potentially let 
the developer know that the adding of signature is needed.

- Existing EBC binaries, that do invoke BREAK 5, to be (relatively 
easily) patched for ARM EBC compatibility. This, for instance, is 
demonstrated with the EDK2 FAT EBC binary in 4.3.

- The updated EDK2 EBC toolchain to produce EBC applications that run on 
*ALL* EBC VMs, including the newly added ARM, as well as other VMs.

0.3 Patch Overview
------------------

The patch series is broken down into 5 parts:

- 1/5 relates to preliminary changes, within the common EBC code, that 
enable VmReadIndex##() functions to optionally return the decoded Const 
and Natural parts, as we need this data for our proposed Stack Tracker. 
It is done by adding an optional pointer to a {Const, Natural} struct, 
that is to be filled when the pointer is not NULL. With the introduction 
of this change, the patch sets all of the new optional pointers to NULL, 
so no actual behavioural change occurs.

- 2/5 introduces the basic ARM EBC VM, as was proposed by Ard as a PoC 
port of the ARRCH64 version. Note that this change alone is enough to 
get standalone EBC code to run on ARM, but may result in the parameter 
marshalling issues we mentioned above, for any call that transitions 
between ARM native and EBC, due to potential "misaligned" 64-bit parameters.

- 3/5 fixes the issue of calling from EBC into native ARM, in a 
completely self contained manner, through the addition of a "Stack 
Tracker". This Stack Tracker is enough to dynamically resolve, at call 
time, whether a specific parameter is 64-bit or not, and thus whether it 
needs to be realigned. This is done through a buffer that starts at 
1/64th of the stack size and is grown dynamically if needed. We 
currently estimate that most EBC applications should not need to use 
more than this initially allocated space, as, in most cases, the stack 
tracker should require less than 1.5 bits to track every 32 bits of 
stack data.

- 4/5 fixes the mirror issue of calling from native into EBC. This is 
the part that requires a specs change, as the thunking code for the ARM 
platform must have some knowledge about the parameter signature of the 
function being called into, to re-align 64-bit parameters. This specific 
section adds handling and processing of call signatures at runtime. It 
should be noted that this patch also bumps the global version of the EBC 
VM from 1.0 to 1.1 as a means to indicate whether an EBC VM is compliant 
with the new specs (though this really only affects ARM, and none of the 
other archs).

- 5/5 adds the insertion of call signatures into EBC binaries at EDK2 
compilation time, in compliance with the proposed specs change. This is 
done by introducing the 2 new python tools: one that works around the 
intel EBC compiler (iec) to parse a C source and generates an optional 
signature data for this source, and one that processes these signature 
files, at link time, to patch the final binary with the signature data 
that will be required at runtime. Eventually, we expect the generation 
of signature data to become part of the iec, thus rendering the first 
tool obsolete.


1. A refresher of the ARM calling convention issue
==================================================

As reminder, the major issue we face when trying to implement an EBC VM 
on ARM has to do with the marshalling of 64-bit parameters from EBC to 
native and from native to EBC.

This is because, as per the AAPCS (Procedure Call Standard for the ARM 
Architecture), ARM has the requirement that any 64-bit function call 
parameters must be aligned to a 64-bit boundary (or an even register, 
for register parameters), whereas, by its nature, the EBC call stack on 
ARM is packed to 32-bit, and therefore 64-bit parameters are not 
guaranteed to be aligned

Without counter-measures, this results in code, such as one calling from 
EBC into a simple (UINT32, UINT64) native function, or calling from 
native into a (VOID*, INT64) EBC function, that ends up with garbage 
parameter data.

The one solution we see to work around this is through the use of call 
signatures, that tell us, at call time, where 64-bit arguments are 
located so that we can realign them. However, as we demonstrate in this 
proposal, the provision of call signatures does not need to be intrusive 
with regards to the development flow.


2. EBC to native marshalling: The Stack Tracker
===============================================

2.1. Overview
-------------

On any architecture other than EBC, the idea of using a stack tracker to 
determine the size of a call parameter would sound like a simplistic 
approach. After all, how can one tell if a sequence of 32-bit values 
being pushed onstack is meant to be used as two 32-bit parameters, or a 
single 64-bit parameter, with the low and high words being pushed 
separately.

However, a careful reading of the EBC specs (UEFI 2.6, section 21.9.3) 
enables us to conclude the following: On an EBC platform, any non-64-bit 
call parameter will be enqueued as a natural.

Furthermore, because EBC naturals can only be enqueued in an atomic 
manner (in other words, it is not possible to use a combination of 
shorter PUSHes or MOV's to add a natural onstack), then, by tracking 
natural operations, which we can easily do in the VM, it is possible to 
determine where non 64-bit parameters have been enqueued, and therefore 
also deduce where 64-bit parameters are located.

 From there, we devise that we can add a "stack tracker" on ARM, to 
monitor the EBC executable's stack operations for which, in order to 
minimize the amount of data required for tracking, we will use sets of 2 
bit sequences, using the following encoding:
- 01b -> a natural has been enqueued on stack
- 00b -> a contiguous set of (non-natural) 64-bit data is present on stack
- 1xb -> start of dual 2-bit sequence (4-bits). x along with the the 
next 2 bits indicates the number of contiguous bytes of data that have 
been enqueued (as non natural data). For instance a 10b 01b sequence may 
be used to indicate that a PUSH8 equivalent operation has been effected.

The dual 2-bit sequences are needed as an application may be enqueuing 
non-natural parameters with the aim of constructing a (potential) 64-bit 
parameter.

For instance, if we have a sequence of 4 MOVIw @R0, ..., we want the 
stack tracker to be able to ultimately resolve the enqueued data as a 
bona-fide 64-bit parameter if needed so that, as data is being enqueued, 
we see the stack tracker being updated as such:

10b 10b (16 bits of data enqueued)
11b 00b (32 bits of data)
11b 10b (48 bits of data)
00b     (64-bit of data -> the dual 2-bit sequence is now collapsed into 
a single 2-bit sequence)

The use of 2 bit for an actual 64-bit "stride" of data, vs. 4 bits for 
other lengths, is of course intended as a form of basic compression to 
reduce the amount of space required for stack tracking, since we expect 
the frequency of 64-bit and natural stack elements to be a lot higher 
than smaller sized elements.

2.2 Call time usage
-------------------

With this in effect, at call time, we can look into the stack tracer to 
determine whether each (potential) parameter is either natural or 
64-bit, and then construct a 16-bit call signature. Note that, as per 
the ARM calling convention, both register and non register 64-bit 
parameters must to be aligned, which, for register parameters, that 
means r0 or r2 must be used as the first word of the 64-bit argument.

Also, in case this needs to be clarified, please note that, even as we 
state that there are only 2 types of parameters that an EBC VM can use 
for an EBC to native call (Natural or 64-bit), this does not imply that 
an EBC application cannot call into a native function that, say, takes a 
BYTE as a parameter. Only that, if it does so, the EBC specs requires 
that it must reserve space for a Natural onstack.

Now, one element we cannot determine is just how many parameters the 
target call takes. However this is something that can be safely ignored, 
as there are no issues associated with passing a larger parameter call 
stack than what is actually needed. The extra (potential) parameters we 
enqueue will simply be ignored.

In our implementation we therefore set the maximum number of parameters 
that a native function call may deal with to 16, which means that we 
always assume that the function call might take 16 arguments. This is 
based on what we've seen other VMs do, as well as what we consider safe 
for the official UEFI interface calls. Currently, we are not aware of 
any calls in the EDK2 taking more than 16 parameters, and we also don't 
expect user applications to pass more than 16 parameters.

Finally, it should be pointed out that, because we don't know the actual 
number of parameters for a call, we may still attempt to process some 
dual 2-bit sequences as part of our 16-bit call signature creation. 
However, if we do, we know that they cannot apply to a formal parameter, 
so we can either choose to ignore them, or just let the implementation 
toggle call signature bits indiscriminately (as we do in our proposal).

2.3 Space considerations
------------------------

The stack tracker is designed to grow dynamically and is currently 
allocated to 1/64th of the total stack space on startup (as a buffer 
that is separate from the stack. We initially considered reserving the 
stack tracker as part of the the stack buffer, but dismissed that 
approach). Currently, each time a reallocation is needed, the stack 
tracker is set to double in space.

For typical executables then, even those who tend to err towards high 
stack usage, we don't expect the initial bufferspace to outgrow the 
1/32th (total stack space) mark, especially as a large part of the stack 
will be reserved for what the stack tracker sees as contiguous sways of 
64-bit elements, which will be stored in 1/32th.

However, we still need to consider the theoretical worst case scenario, 
where someone create an EBC application that consists only of:
PUSHn ...
MOV(I)b @R0, ....
PUSHn ...
for as much stack space as is available (R0 being the EBC stack pointer).

In this case, the stack tracker will allocate 2 bits for each PUSHn and 
4 for each MOV (because they equate to pushing a byte), but none of the 
4 bit sequences will ever be collapsable into a 2-bit one (once we have 
accumulated enough bytes to form a 64-bit) which means that 32 bits + 32 
bits of actual stack data (because while 8 bits are pushed, they are 
aligned to 32 on the next PUSHn) = 64 bits are encoded into 6 bits in 
the stack tracker, or ~1/10th of stack space. And since we double the 
stack tracker size each time it needs to be reallocated, this means that 
the very worst case scenario we can see in terms of space would be a 
stack tracker that needs to occupy 1/8th of the stack data at worst.

Even if that was a realistic scenario, we don't consider that the 
drawback of having to (potentially) reserve an extra 1/8th outweighs the 
advantages of allowing ARM users, to benefit from an EBC VM. Still, we 
will point out that this is not a scenario we ever expect to see in a 
practical application. Instead the worst scenario we expect for an 
exceedingly stack heavy EBC executable, that enqueues a lot of <= 32 bit 
elements, would be 1/16th of stack space (or 64KB, since the default 
stack buffer is ~1MB), which we think is very reasonable, even on ARM. 
Furthermore, we consider it a fair estimate that 99% of applications 
will never need more than the initial 1/64th (or 16KB) allocated for 
stack tracking.

2.4 Additional considerations
-----------------------------

2.4.1 Local variables onstack

Typically, at the beginning of a subroutine, a MOV R0, R0(0,-n) will be 
used by the compiler to reserve space for local variables.

For instance, a compiler may insert MOV R0, R0(0,-1024) to reserve space 
for 1024 bytes onstack. And while developers and users can reasonably 
expect this to be a near-instantaneous operation, if our stack tracker 
is going to read that operation as a set of 128 x 64-bit longwords being 
allocated, and then perform 128 x {read byte; modify 2 bits; write byte} 
operations, one may have misgivings about the performance impact of 
tracking the stack.

However, the stack tracker is designed to recognize operations 
pertaining to repeated sequences of data, and optimize them. In short, 
in the current implementation, the sequence above will typically result 
in the stack tracker simply zeroing a set of 128 bytes in one go, 
instead of trying to repeatedly update individual 2-bit sequences.

Note that this holds true even if there is a need to propagate a dual 
2-bit sequence as part of tracking a large set of 64-bit longwords.

To confirm this, and as part of our test suite, we also have a test 
where half the stack is reserved and then released for local data, 10 
times in a row, and we see that the execution of this test is near 
instantaneous in QEMU, confirming that there should be no performance 
bottleneck (see 4.1 -> Realloc).

2.4.2) Stack buffer switching

First, we must point out that, per our testing, NONE of the current EBC 
VM implementations from the EDK2 currently allow the EBC stack buffer to 
be switched to a different buffer by an EBC application at runtime. 
Especially the following EBC assembly code will freeze execution on 
MOVREL, on all current VMs:

EfiMain:
   MOV       R6, R0
   MOVREL    R0, StackTop
   MOV       R0, R6
   RET

section '.data' data readable writeable
   StackBuf: dq 255
   StackTop: dq 1

Nonetheless, in case this ever becomes a possibility, our stack tracking 
proposal does have provision for stack buffer switching. The only 
limitation we have (and this is really the only limitation we see for 
the whole proposal), is that it can only handle one level of switching. 
In other words, provided stack switching was possible (which currently 
isn't the case) the stack tracker wouldn't be able to properly track 
parameters if a second stack buffer switching occurs within code that 
executes against a stack buffer that was already switched. However, the 
proposal should still be fine if only a single level of stack switching 
occurs (i.e. we should be able to track switch/restore, no matter how 
many times such switching is repeated during the execution of an 
application).

Thus, considering that:
1. It does not currently seem possible to switch stack buffer on any arch
2. The EBC compiler does not offer the ability to manipulate the stack 
pointer directly in the first place
3. Stack switching only becomes an issue if done recursively

We consider that this one limitation of our implementation can be 
dismissed as too unrealistic and cannot be construed as a showstopper.

2.4.3 Delta stack pointer updates

Outside of the obvious PUSH/POP operations, the stack tracker does track 
mathematical/logical modification of R0, by computing the delta from the 
previous R0 value. Most of the time this delta would only have a const 
component, which we then try to resolve to a complete or partial set of 
64-bit consecutive values. However, there also exist instances, such as 
MOV R0, R0(+n,+c), where we will have both a constant and a natural part 
to track.

While updating the stack tracker itself with such data is not 
technically an issue, one may wonder if the order in which natural and 
constants are processed might have an effect on our ability to determine 
where 64-bit parameters are located.

However, when one looks more closely at the validity of such concerns, 
the conclusion will be drawn that such an operation can never be used to 
fill actual call parameters (which would have to be optional in the 
first place, since it is of course impossible, with the current EBC 
specs, to use such an operation to pass actual data), as neither the 
specs nor the VM make any promise as to the order in which constant and 
natural parameters are processed. Therefore a programmer cannot assume 
how its call parameter stack will be set from invoking such an 
operation. Thus, as far as tracking data to determine if a parameter is 
natural or 64-bit, the order induced by the operation above is 
irrelevant, and we are therefore free to pick whichever order makes most 
sense for our implementation.

2.4.4 "Cloaked" stack operations

"Cloaked" stack operation are stack operations that are not effected 
using R0 as the stack pointer. For instance, someone may copy R0 into 
R1, then alter the data pointed by either R0 or R1, and then copy R1 
(which may or may not have been modified) back to R0 . And whereas stack 
switching (i.e. trying to have R0 point to an address that isn't within 
the current stack buffer) currently break VM execution, moving R0 within 
the stack buffer, even in a cloaked manner, is something that the EBC VM 
can and does perform without issues.

Ultimately, there are two types if cloaking that may come into effect, 
which we'll call positive and negative cloaking.

Positive cloaking (dequeuing) is a non issue. This basically intervenes 
when the restored R0 is at a higher address than the original one. Since 
stacks grow downwards, this means that dequeueing of data has been 
issued, which we can handle with relative ease by going through our 
existing tracker data, and removing natural and const elements, 
according to their size, until we match the R0 address delta.

Negative cloaking (enqueuing) could be seen as more problematic, as one 
may consider that, since we're not tracking anything but R0, someone may 
use something like an R1 index manipulation to enqueue natural and const 
call parameters, before eventually assigning R1 to R0, which would 
defeat our tracking ability.

However, for all purposes, negative cloaked stack pointer updates should 
never be used to enqueue call arguments. Especially, by NOT explicitly 
declaring whether an argument is a natural or a 64 bit, through a direct 
stack operation, one would be deliberately misinterpreting the intent of 
the specs, which states (21.9.3) that "Parameters are pushed on the VM 
stack" and pretty much implies direct stack operation. At the very 
least, we do not expect C applications to use negative cloaking (as C 
does not have provisions for anything like this), and furthermore, 
should we believe that specs may be misinterpreted, we could add a 
"directly" qualifier, so that all ambiguity is removed.

2.5 Code changes overview
-------------------------

The stack tracker is introduced with PATCH 3/5, and contains the 
following code changes:

2.5.1: In EbcVmTest.h we add a new pointer to an optional, opaque and 
arch-specific structure. This is the structure that will be used for our 
Stack Tracker on ARM. It is important to note that, in the common code, 
we use the presence or absence of this pointer (whether the pointer is 
NULL) to determine whether stack tracking is in operation. We preferred 
this approach to using #ifdef MDE_ARM in the code, as we believe it is 
cleaner.

2.5.2: In EbcExecute.c we add stack tracking for any instruction that 
may require it. This is done for anything that deal with accessing the 
content pointed by R0 (the stack tracker) or manipulating R0 directly, 
including mathematical operations on R0, as well as (obviously) PUSH and 
POP operations.
Depending on whether VmPtr->StackTracker is NULL (currently, only ARM) 
and whether the instructions affects R0, we then invoke one of 
UpdateStackTracker() or UpdateStackTrackerFromDelta().

2.5.3: Since we introduce the 2 functions above, we also add a blank 
EbcStackTracker.c, at the top level, to be used on any arch that doesn't 
require stack tracking. Calls are defined as empty functions there.

2.5.4: For ARM alone, we add Arm/EbcStackTracker.c which contains the 
definition for the 2 functions above, as well as any other stack tracker 
support function, such as the ones that deal with stack tracker buffer 
allocation/release.

2.5.6: In Arm/EbcSupport.c, we add the necessary calls for stack tracker 
allocation/release as well as modify EbcLLCALLEX() to use a new 
EbcLLCALLEXNativeArm() which takes an extra argument for the current 
argument layout as returned by the stack tracked.

2.5.7: in Arm/EbcLowLevel.S, we define the EbcLLCALLEXNativeArm, which 
takes care of properly aligning up to 16 64-bit parameters, according to 
the argument layout.


3. Native to EBC native marshalling: Internal call signatures
=============================================================

3.1 Overview
------------

Once again, we start from the principle that a call signature is needed, 
at layer transition time (native -> EBC invocation), so that we can 
realign 64-bit call parameters as needed.

In this case, since the application performing the call request is 
native, we cannot use anything like a stack tracker (which wouldn't work 
for native code anyway) and instead, need to ensure that we can have the 
call signature at our disposal when we perform thunking.

Two elements that works to our advantage for this part are that:
- The code for which we need signature awareness is the EBC code itself, 
in other words, code that should be produced using the EKD2 EBC toolchain.
- Every single function call for which we need a signature must also be 
function call for which thunking will be set using BREAK 5.

 From there, it's easy to devise a solution that consists of modifying 
the EBC generation toolchain, so that it adds a 16-bit call signature 
into the 64-bits offsets used by BREAK 5 (which only ever use a 32-bit 
payload), to make signatures available when thunking is invoked.

3.2 Implementation
------------------

After having confirmed that, as per specs, all of the current EBC VM 
implementations do ignore the high 32-bit part of the 64-bit used by 
BREAK 5 (which means that we can alter this existing data without 
incurring any drawbacks), we identify it as the best place to store the 
16-bit signature, along with an extra 16-bit marker, which we'll then 
use to detect EBC binaries that were compiled without signatures.
The other reasons that make us want to use this element are that:
- This is space that is already available in an EBC binary (i.e. no need 
to add extra data/instructions)
- This can enable the patching of existing EBC binaries.
- It makes logical sense to have it there, since the call signatures are 
related to functions that requires BREAK 5 invocation.

When BREAK 5 is invoked, we should therefore be able to copy this 
signature (if available) into the EBC_INSTRUCTION_BUFFER structure, and 
subsequently use that data during call thunking, to align 64-bit parameter.

Of course, while we will now require EBC binaries to be decorated with 
additional signature data, we don't want EBC developers to have to go 
through the process of inserting these signatures manually. Instead, we 
automate the signature insertion so that it will run at compilation 
time. To that effect, we introduce 2 Python scripts in BaseTools:
- GenEbcSignature, invoked after each object generation, parses a 
preprocessed C source, along with the object file, to create the 
signature data, which is then stored into a corresponding .sig files.
- PatchEbcSignature, invoked at final application link time, processes 
the .sig files as well as the .map data and .efi binary, and inserts the 
signatures at the relevant location in the final binary

Currently, and because we expect the intel EBC compiler to be updated to 
follow the new specs (since it is really the best place to perform such 
processing, as it has access to the C parser, lexer as well as the full 
preprocessed source, and can more easily determine the nature of 
function call arguments), we see GenEbcSignature as a stopgap solution 
until said compiler is updated.

Therefore, GenEbcSignature was designed to be very basic with regards to 
the ability to properly detect 64-bit parameters. For instance, it 
expects the processed source to follow the EDK coding conventions and it 
also requires straight INT64 or UINT64 parameters to be used (i.e. no 
redefinitions of these basic types). Of course, since any aspect of the 
signature generation and insertion can be amended, we are ready to 
modify the proposal according to what intel sees as the best course of 
action with regards to iec integration.

On the other hand, we expect PatchEbcSignature to remain part of the EBC 
toolchain in one form or another, as signature insertion intervenes post 
linking, and the EBC linker is not something that was written 
specifically for EBC (regular Microsoft linker) and there isn't much 
performance/optimization to be had for not having an extra step here.

Finally, both scripts currently rely on the intel EBC compiler 
referencing externally callable functions with a "_plabel" suffix, which 
is what we empirically identified as intel's marker for such calls. Of 
course, not knowing the internals of the iec, it is possible that this 
assertion does not hold, in which case, there again, we can work with 
intel iec developers to refine it...

3.3 Proposed specs change
-------------------------

UEFI Specs Version 2.6 (January, 2016) are used for all the changes 
highlighted below.

Proposed alterations/insertions are to be found within brackets [ ]

* Section 21.8 -> BREAK -> BREAK 5:

"Create thunk. This causes the interpreter to create a thunk for the EBC 
entry point whose 32-bit IP-relative offset is stored in the low part of 
a 64-bit data address in VM register R7[, and whose call signature is 
stored in the high part. For details on how the signature should be 
generated, see section 21.12.10.2]. The interpreter then
replaces the contents of the memory location pointed to by R7 to point 
to the newly created thunk (...)"

* Section 21.12.10.2: Thunking Native Code to EBC

"Typical C code to install a generic protocol is shown below.
   EFI_STATUS Foo(UINT32 Arg1, UINT[64] Arg2);
   (...)

"To support thunking native code to EBC, the EBC compiler resolves (...)
  • Associated relocations[ and optional call parameter alignment] for 
the above

[In order to perform optional parameter alignment, the EBC toolchain is 
required to insert a 16-bit call signature, along with a 16-bit marker, 
in the high 32-bit word of the 64-bit function pointer data object.

A bit of the call signature is set to 1 if a parameter is 64-bit or 0 
otherwise, with the first parameter at bit 0. If a function call uses 
less than 16 parameters, any unused bit should be set to 0. EBC function 
calls with more than 16 parameters are not supported.

The 16-bit signature should then be written into bits 32 to 47 of the 
64-bit function pointer data object, and bits 48 to 63 set to 0x2EBC.

Thus, for the (UINT32, UINT64) function call above, the 64-bit function 
pointer data object that the EBC toolchain would need to store at 
Foo_pointer is:

(Foo - Foo_pointer - 4) + (0x0002 << 32) + (0x2EBC << 48)]

3.4 Code changes overview
-------------------------

o PATCH 4/5:

3.4.1: In EbcVmTest.h we bump the VM version minor from 0 to 1. This is 
because, while there isn't any actual incompatibility being introduced 
for existing VMs, we feel that EBC developers may still want the ability 
to detect if the VM they are running against is call-signature 
compatible (v1.1) or not (v1.0) and possibly take action as a result.

3.4.2: In EbcInt.h we define the EBC_CALL_SIGNATURE marker, and 
introduce a new flag for the ARM create-thunk function, to indicate 
whether a call signature needs to be processed.

3.4.3: In EbcExecute.c we modify ExecuteBREAK() to read the call 
signature (if present) and then set pass that signature along with the 
FLAG_THUNK_SIGNATURE flag to the arch-specific EbcCreateThunks(). Note 
that, for any other arch than ARM, the flags were already ignored, so no 
changes are needed.

3.4.5: In Arm/EbcSupport.c, we modify EbcCreateThunks() so that it reads 
the new flag and signature, if provided, and store it into the private 
thunk data (InstructionBuffer.EbcCallSignature)

In EbcInterpret() we check whether the signature is present, and if so, 
align parameters as needed. If not, we return an 
EFI_INCOMPATIBLE_VERSION status.

3.4.6: Arm/EbcSupport.S is also modified to handle the new 
EbcCallSignature word of InstructionBuffer.

o PATCH 5/5:

3.4.7: BaseTools\Source\Python\GenEbcSignature\GenEbcSignature.py is the 
new call signature generation script. It is meant to be called after iec 
has generated an object file, and is set to take the preprocessed source 
on stdin (so that we can parse function call declarations from headers) 
along with the object file, and generates signature data (which, in its 
current form, is the python serialized data from a dictionary). 
Basically, we parse the COFF object and locate the symbol table, where 
we identify all the symbols that have a _plabel suffix. When then try to 
locate each symbol in the preprocessed source, as possible function 
calls, and, if we find one, detect whether it has [U]INT64 parameters 
(from either a function declaration or definition). We then use python's 
"pickle" functionality to serialize our call signature dictionary.

3.4.8: BaseTools\Source\Python\PatchEbcSignature\PatchEbcSignature.py is 
the call signature insertion script. This time, we process the .map file 
for the produced .efi to identify the address of _plable suffixed 
function calls. These will be the addresses we need to insert signatures 
into.
Then, we take a list of either .sig or .lib files (which we convert to 
.sig path), and unserialize them to build a full dictionary of call 
signatures.
Then, after a few sanity checks, we insert the signatures, along with 
the markers.

3.4.9: In BaseTools\Conf\build_rule.template, we add the step that call 
on GenEbc/PatchEbcSignature when EBC binaries are being produced.

Note that, as they are introduced in this proposal, these calls 
currently have the -v (verbose) flag set, so that additional information 
about the call signature generation and insertion is displayed during 
compilation. Eventually, we want to remove the -v flag.

3.4.10: In BaseTools\Conf\tools_def.template, we add 2 new variables for 
the new tools.

The rest of the changes should be explicit.


4. Test Suite
=============

A comprehensive validation test suite is provided, in order to 
demonstrate that the proposal does work as advertised. As may be 
expected, these tests are based on using the QEMU_ARM firmware that is 
generated from an EDK2 source tree where these patches have been applied.

For convenience, it will also be assumed that:
- Windows x64 is being used as the test platform
- QEMU 2.7.0 or later (64-bit version) is available and installed under 
C:\Program Files\qemu\ (NB: 2.7.x or 2.8.x should work fine for ARM, but 
I found that the 2.8.x precompiled Windows QEMU binary had issues with 
AARCH64)
- One has cloned the fasmg EBC Assembler [1] (which contains most of the 
test suite) into C:\fasmg-ebc\

4.1 EBC -> native ARM test suite
--------------------------------

The test suite for the stack tracker can be found in the EBC assembler, 
which is an Open Source EBC assembler [1], based on fasmg, that was 
developed in parallel to this proposal (but that isn't directly related 
to it). The use of an EBC assembler makes it convenient to both compile 
and validate/debug test applications (through the EBC Debugger). Also, 
some aspects of what we are testing (such as cloaked stack 
manipulations) would be difficult to test outside of assembly.

Besides the EBC test applications, we do require a native UEFI driver, 
that will install a set of native protocols, which we can call into for 
testing. This driver [2], which is also provided as part of the EBC 
assembler, is written in C (and compiled as a gnu-efi based VS2015 
solution, for convenience reasons). Both pre-compiled ARM and IA32 
driver binaries are provided if needed.

To run this part of the suite, whose prime purpose is to validate the 
stack tracker, one should navigate to the stack_stracker\ subdirectory 
of the EBC Assembler and run something like:

C:\fasmg-ebc\stack_tracker> make qemu

This will download the required files as needed (such as the latest 
fasmg assembler, or the QEMU ARM firmware), assemble the EBC test 
programs, and then run all the tests in an ARM QEMU environment.

The suite is comprised of:

- Matrix test [3], that tests every single of the 16 possible 
combinations for a 4-parameter native call. In other words, this 
validates that that every single parameter we pass, from (UINTN, UINTN, 
UINTN, UINTN) to (UINT64, UINT64, UINT64, UINT64), is received, without 
mangling, by the ARM native driver.

- Max test [4], that confirms that 16 parameters can be successfully 
received. We perform 3 sets of tests here: 16 native parameters, 16 
64-bit parameters and 16 intermixed.

- Cloaked test [5], that performs a set of stack operations using R1 
instead of R0 as the stack pointer, while interspersing the queuing of 
actual parameters for a native function call.

- Realloc test [6], that forces the stack tracker to grow (realloc) its 
buffer, by reserving half the stack as local space, and also that tests 
the speed at which the stack tracker is able to process half the stack 
being reserved/restored as a local space, by repeating the operation 10 
times in a row

Note that a Switch test was also written, that attempts to switch the 
stack buffer, but since this is an operation that does not work on ANY 
of the EBC VMs, it is left out of the suite.

Of course, if you don't want to use the pre-built QEMU_EFI_ARM.fd 
firmware, which will be downloaded from my servers, you can build and 
copy your own in the stack_tracker\ directory.

Needless to say, if the patch series has been properly applied, all of 
the tests above will report a "PASS" status, confirming that the stack 
tracker works.

4.2 Native ARM -> EBC test suite
--------------------------------

This time, we want to test the reverse operation of marshalling from ARM 
to EBC, so we need to create an EBC protocol driver (driver.asm - [7]), 
similar to the native C driver we created for the previous test, along 
with a native application (native.c in the native/ subdirectory [8]) 
that will call into the protocols installed by the EBC driver.

The native test application includes:

- A complete matrix test, similar to the one used to validate the stack 
tracker (i.e. 16 protocol calls taking 4 arguments that are all possible 
combinations of UINTN or UINT64)

- An additional set of protocol calls, that take 16 parameters in all.

It should also be noted that, since the fasmg-ebc assembler already has 
provision for the insertion of call signatures into the BREAK 5 data 
(through its 'EXPORT' macro), there is no need to patch the EBC binary.

Then, to run the test suite, one can simply run (in the fasmg-ebc root 
directory)

C:\fasmg-ebc> make driver qemu arm

To compile and install the EBC driver in qemu, and invoke the native 
test application.

You can also invoke the EBC debugger if you replace 'qemu' with 'debug' 
(a relevant debugger binary will be downloaded automatically). This test 
suite can also be run for other architectures that ARM by replacing 
'arm' with one of 'x64', 'ia32' or 'aa64' (again, the relevant firmware 
will be downloaded automatically if not already provided).

On particular note, if you try to run this test suite for IA32, you will 
see that the 'MaxParam64' test (which validates the ability for calls to 
take 16 64-bit parameters) does fail, as the IA32 EBC VM doesn't seem to 
currently have been designed to handle that many arguments.

4.3 Patching the EDK2's FAT EBC binary
--------------------------------------

Finally, we conclude this introductory note with a real-life example of 
how one can take an existing EBC binary and patch it, so that it will 
run in all VMs, including ARM. This also enables us to further validate 
this proposal, by demonstrating that a fairly complex existing EBC 
application can and does indeed run without issues on ARM.

One thing we need to be clear about from the onset, is that this step is 
NOT something that we expect any EBC developer to have to go through. 
Instead, they should just be able to recompile their code, with the 
patched version of the EBC toolchain, and when they do so, they will 
find that the required signatures have been automatically inserted in 
the resulting EBC binary.

This exercise is only to demonstrate that, if one really needs to, this 
proposal also makes is possible to insert signatures into existing EBC 
binaries, to allow them to run on the new ARM VM.

For this example, we will use the FAT EBC binary driver currently 
included in the EDK2 (under FatBinPkg/EnhancedFatDxe/Ebc/Fat.efi).

Because the proposed ARM VM already takes care of EBC -> native ARM 
handling (through the stack tracker), the only part we need to concern 
ourselves with are the call signatures for native ARM -> EBC invocations.

What we first need to identify then, are the 64-bit locations where the 
32-bit offsets that are used in conjunction with BREAK 5 are stored. 
Obviously, these the elements should be located in the data section, and 
furthermore, we can infer that they should be easily recognisable as 
32-bit negative data offsets (most likely in 0xFFFF.... or 0xFFFE.... 
since the executable isn't that large, and the code sections can be 
expected to be set before data sections), followed by 4 zeroed bytes.

We can also leverage some knowledge of the Microsoft linker with regards 
to how it generates DLL entrypoint addresses (which is what is really 
being used behind the scenes to generate the 32-bit BREAK 5 offsets) as 
it seems to always place these offsets padded to a 16-byte alignement. 
Therefore, we can easily identify that there exist 23 BREAK 5 data 
locations in the data section, with the first one being at address 
0x000109e0, and the last at 0x00010eb0. These mark the addresses at 
which we will need to add call signatures.

However, while it can easily help us find the locations we are after, 
the binary enough is not enough to help us determine the call signature 
data. In this specific case, we will consider that one also has access 
to a .map file that is generated, as part of the EDK2 EBC toolchain, 
during final linking (for us, that would be something like 
"edk2\Build\Fat\RELEASE_VS2015\EBC\FatPkg\EnhancedFatDxe\Fat\OUTPUT\Fat.map). 
If a map file is not available, one will of course need to use other 
means to "guess" what each of the BREAK5 data call is for. Also, it 
doesn't matter if that .map file isn't the exact one that was generated 
with the binary (and as a matter of fact, even as the FAT EBC binary was 
updated very recently, most of this procedure was conducted against the 
2015.08 version of the binary, using a map file that was more that one 
year more recent), as we just use it to get a list of calls, along with 
their expected order. This is because, if you look at the .map file you 
can find that all the EBC calls that may be invoked from native will be 
suffixed with a "_plabel".

 From there, we can deduce that the 23 addresses we have found, and in 
the order we found them, are respectively for:

00109e0 _DriverUnloadHandler()
0010c80 FatDriverBindingStop()
0010c90 FatDriverBindingStart()
0010ca0 FatDriverBindingSupported()
0010d20 FatComponentNameGetControllerName()
0010d30 FatComponentNameGetDriverName()
0010d50 FatOnAccessComplete()
0010d90 FatOpenVolume()
0010da0 FatFlushEx()
0010db0 FatWriteEx()
0010dc0 FatReadEx()
0010dd0 FatOpenEx()
0010de0 FatFlush()
0010df0 FatSetInfo()
0010e00 FatGetInfo()
0010e10 FatSetPosition()
0010e20 FatGetPosition()
0010e30 FatWrite()
0010e40 FatRead()
0010e50 FatDelete()
0010e60 FatClose()
0010e70 FatOpen()
0010eb0 InternalEmptyFunction()

Because the EBC FAT driver was updated recently, we may also find that 
the addresses we identified also match the ones from the .map file 
(minus an 0x1000000 offset), but, as we tried to point out, this is not 
an absolute requirement and one does not necessarily have to use the 
exact same .map file as the one generated for the binary they are trying 
to patch.

Now, looking at the source/headers (which can also be deduced from the 
.map), we find that, out of these 23, only 3 functions need to have a 
signature call that is non-zero (i.e. 3 calls actually use 64-bit 
parameters). Those are:

0010dd0 FatOpenEx(EFI_FILE_PROTOCOL*, EFI_FILE_PROTOCOL**, CHAR16*, 
UINT64, UINT64, EFI_FILE_IO_TOKEN*)
  -> 011000b
0010e10 FatSetPosition(EFI_FILE_PROTOCOL*, UINT64 Position)
  -> 10b
0010e70 FatOpen(EFI_FILE_PROTOCOL*, EFI_FILE_PROTOCOL**, CHAR16*, 
UINT64, UINT64)
  -> 11000b

 From there, we have everything required to insert the call signatures 
(along with their 0x2EBC marker) into the Fat.efi, a fully patched 
version of which can be found at [9]. If you diff this file with the one 
from the EDK2, you will be able to confirm that the code section is 
unchanged, and that the only minimal change that was applied is that 
signatures have been inserted in the data section.

This patched binary can then be used to confirm that the updated EBC 
driver runs as expected on ARM, as well as existing platforms.

This can be achieved using a QEMU firmware in which the native FAT 
driver had replaced with an NTFS driver, and then booting from an NTFS 
partition containing the patched FAT EBC driver produced by this 
procedure. Through this, would were able to demonstrated that data could 
be repeatedly accessed from a FAT partition without any issue. The only 
thing worth mentioning is that (at least on QEMU) the driver may 
sometimes be very slow to load as it accesses the FAT partition, but 
this is behaviour which we observed for both ARM and AARCH64, which we 
suspect has to do with the emulation layer(s).

If you want to run this test, under the same conditions as the ones we 
used (again, all the required files will be downloaded automatically), 
you can issue the following at the root of the EBC Assembler:

C:\fasmg-ebc> make hello qemu arm ntfs

You can also run a similar test against AARCH64 by replacing 'arm' with 
'aa64'.

A similar test was of course performed with the recompiled EBC FAT 
driver, as produced through the updated EBC toolchain, and no issues 
were observed there either.

The fact that one can patch the existing EBC FAT driver and run it 
without issues in the proposed ARM VM, or that the FAT driver produced 
from the EDK2 after this proposal has been applied can also be used in 
the ARM VM, will, we hope, be enough to convince that the proposal is 
sound and can be integrated.

Regards,

/Pete


[1] https://github.com/pbatard/fasmg-ebc
[2] 
https://github.com/pbatard/fasmg-ebc/blob/master/stack_tracker/driver/driver.c
[3] 
https://github.com/pbatard/fasmg-ebc/blob/master/stack_tracker/matrix.asm
[4] https://github.com/pbatard/fasmg-ebc/blob/master/stack_tracker/max.asm
[5] 
https://github.com/pbatard/fasmg-ebc/blob/master/stack_tracker/cloaked.asm
[6] 
https://github.com/pbatard/fasmg-ebc/blob/master/stack_tracker/realloc.asm
[7] https://github.com/pbatard/fasmg-ebc/blob/master/driver.asm
[8] https://github.com/pbatard/fasmg-ebc/blob/master/native/native.c
[9] http://efi.akeo.ie/EBC/FAT/Fat.efi

-----------------------------------------------------------------------
Ard Biesheuvel (1):
   MdeModulePkg/EbcDxe: add ARM support

Pete Batard (4):
   MdeModulePkg/EbcDxe: allow VmReadIndex##() to return a decoded index
   MdeModulePkg/EbcDxe: add a stack tracker for ARM EBC->native support
   MdeModulePkg/EbcDxe: add call signatures for ARM native->EBC support
   BaseTools: add scripts to generate EBC call signatures

  ArmVirtPkg/ArmVirt.dsc.inc                         |   6 +-
  ArmVirtPkg/ArmVirtQemuFvMain.fdf.inc               |  10 +-
  ArmVirtPkg/ArmVirtXen.fdf                          |  10 +-
  .../BinWrappers/WindowsLike/GenEbcSignature.bat    |   3 +
  .../BinWrappers/WindowsLike/PatchEbcSignature.bat  |   3 +
  BaseTools/Conf/build_rule.template                 |  72 ++-
  BaseTools/Conf/tools_def.template                  |  12 +
  .../Python/GenEbcSignature/GenEbcSignature.py      | 306 ++++++++++
  .../Source/Python/GenEbcSignature/__init__.py      |  15 +
  .../Python/PatchEbcSignature/PatchEbcSignature.py  | 226 ++++++++
  .../Source/Python/PatchEbcSignature/__init__.py    |  15 +
  MdeModulePkg/Include/Protocol/EbcVmTest.h          |   4 +-
  MdeModulePkg/MdeModulePkg.dsc                      |   4 +-
  MdeModulePkg/Universal/EbcDxe/Arm/EbcLowLevel.S    | 184 ++++++
  .../Universal/EbcDxe/Arm/EbcStackTracker.c         | 634 
+++++++++++++++++++++
  MdeModulePkg/Universal/EbcDxe/Arm/EbcSupport.c     | 599 
+++++++++++++++++++
  MdeModulePkg/Universal/EbcDxe/EbcDebugger.inf      |  10 +-
  .../EbcDxe/EbcDebugger/EdbDisasmSupport.h          |   4 +-
  .../Universal/EbcDxe/EbcDebuggerConfig.inf         |   2 +-
  MdeModulePkg/Universal/EbcDxe/EbcDxe.inf           |  10 +-
  MdeModulePkg/Universal/EbcDxe/EbcExecute.c         | 292 ++++++++--
  MdeModulePkg/Universal/EbcDxe/EbcExecute.h         |   8 +
  MdeModulePkg/Universal/EbcDxe/EbcInt.h             |   7 +-
  MdeModulePkg/Universal/EbcDxe/EbcStackTracker.c    |  65 +++
  24 files changed, 2425 insertions(+), 76 deletions(-)
  create mode 100644 BaseTools/BinWrappers/WindowsLike/GenEbcSignature.bat
  create mode 100644 BaseTools/BinWrappers/WindowsLike/PatchEbcSignature.bat
  create mode 100644 
BaseTools/Source/Python/GenEbcSignature/GenEbcSignature.py
  create mode 100644 BaseTools/Source/Python/GenEbcSignature/__init__.py
  create mode 100644 
BaseTools/Source/Python/PatchEbcSignature/PatchEbcSignature.py
  create mode 100644 BaseTools/Source/Python/PatchEbcSignature/__init__.py
  create mode 100644 MdeModulePkg/Universal/EbcDxe/Arm/EbcLowLevel.S
  create mode 100644 MdeModulePkg/Universal/EbcDxe/Arm/EbcStackTracker.c
  create mode 100644 MdeModulePkg/Universal/EbcDxe/Arm/EbcSupport.c
  create mode 100644 MdeModulePkg/Universal/EbcDxe/EbcStackTracker.c

--
2.9.3.windows.2