[PATCH v2 1/4] UefiCpuPkg/ResetVector/Vtf0: document segment register setup

[Laszlo Ersek <lersek@redhat.com>]

"Main.asm" calls TransitionFromReal16To32BitFlat (and does some other
things) before it jumps to the platform's SEC entry point.

TransitionFromReal16To32BitFlat enters big real mode, and sets the DS, ES,
FS, GS, and SS registers to offset ("selector") LINEAR_SEL in the GDT
(defined in "UefiCpuPkg/ResetVector/Vtf0/Ia16/Real16ToFlat32.asm"). The
GDT entry ("segment descriptor") at LINEAR_SEL defines a segment covering
the full 32-bit address space, meant for "read/write data".

Document this fact for all the affected segment registers, as output
parameters for TransitionFromReal16To32BitFlat, saying "Selector allowing
flat access to all addresses".

For 64-bit SEC, "Main.asm" calls Transition32FlatTo64Flat in addition,
between calling TransitionFromReal16To32BitFlat and jumping to the SEC
entry point. Transition32FlatTo64Flat enters long mode. In long mode,
segmentation is largely ignored:

- all segments are considered flat (covering the whole 64-bit address
  space),

- with the (possible) exception of FS and GS, whose bases can still be
  changed, albeit with new methods, not through the GDT. (Through the
  IA32_FS_BASE and IA32_GS_BASE Model Specific Registers, and/or the
  WRFSBASE, WRGSBASE and SWAPGS instructions.)

Thus, document the segment registers with the same "Selector allowing flat
access to all addresses" language on the "Main.asm" level too, since that
is valid for both 32-bit and 64-bit modes.

(Technically, "Main.asm" does not return, but RBP/EBP, passed similarly to
the SEC entry point, is already documented as an output parameter.)

Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Eric Dong <eric.dong@intel.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Suggested-by: Jordan Justen <jordan.l.justen@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---

Notes:
    v2:
    - new patch [Jordan]

 UefiCpuPkg/ResetVector/Vtf0/Ia16/Real16ToFlat32.asm | 6 ++++++
 UefiCpuPkg/ResetVector/Vtf0/Main.asm                | 5 +++++
 2 files changed, 11 insertions(+)

diff --git a/UefiCpuPkg/ResetVector/Vtf0/Ia16/Real16ToFlat32.asm b/UefiCpuPkg/ResetVector/Vtf0/Ia16/Real16ToFlat32.asm
index 146df600a63b..bc68c8dd749a 100644
--- a/UefiCpuPkg/ResetVector/Vtf0/Ia16/Real16ToFlat32.asm
+++ b/UefiCpuPkg/ResetVector/Vtf0/Ia16/Real16ToFlat32.asm
@@ -21,6 +21,12 @@ BITS    16
 ;
 ; Modified:  EAX, EBX
 ;
+; @param[out]     DS       Selector allowing flat access to all addresses
+; @param[out]     ES       Selector allowing flat access to all addresses
+; @param[out]     FS       Selector allowing flat access to all addresses
+; @param[out]     GS       Selector allowing flat access to all addresses
+; @param[out]     SS       Selector allowing flat access to all addresses
+;
 TransitionFromReal16To32BitFlat:
 
     debugShowPostCode POSTCODE_16BIT_MODE
diff --git a/UefiCpuPkg/ResetVector/Vtf0/Main.asm b/UefiCpuPkg/ResetVector/Vtf0/Main.asm
index ebfb9015d49c..57f080688b6f 100644
--- a/UefiCpuPkg/ResetVector/Vtf0/Main.asm
+++ b/UefiCpuPkg/ResetVector/Vtf0/Main.asm
@@ -24,6 +24,11 @@ BITS    16
 ; @param[in,out]  DI       'BP': boot-strap processor, or
 ;                          'AP': application processor
 ; @param[out]     RBP/EBP  Address of Boot Firmware Volume (BFV)
+; @param[out]     DS       Selector allowing flat access to all addresses
+; @param[out]     ES       Selector allowing flat access to all addresses
+; @param[out]     FS       Selector allowing flat access to all addresses
+; @param[out]     GS       Selector allowing flat access to all addresses
+; @param[out]     SS       Selector allowing flat access to all addresses
 ;
 ; @return         None  This routine jumps to SEC and does not return
 ;
-- 
2.14.1.3.gb7cf6e02401b