1. Added comments to ASM files

[mirror_edk2.git] / MdePkg / Library / BaseLib / X64 / Thunk16.asm

diff --git a/MdePkg/Library/BaseLib/X64/Thunk16.asm b/MdePkg/Library/BaseLib/X64/Thunk16.asm
index 642310869b6fe6ec6574f56ed387f054dd9cab03..556a8b47e37d0d0820f14c176bcf46dfd3dc30a9 100644 (file)
--- a/MdePkg/Library/BaseLib/X64/Thunk16.asm
+++ b/MdePkg/Library/BaseLib/X64/Thunk16.asm
@@ -66,6 +66,14 @@ SavedGdt    LABEL   FWORD
 ; by user code. It will be shadowed to somewhere in memory below 1MB.\r
 ;------------------------------------------------------------------------------\r
 _BackFromUserCode   PROC\r
+    ;\r
+    ; The order of saved registers on the stack matches the order they appears\r
+    ; in IA32_REGS structure. This facilitates wrapper function to extract them\r
+    ; into that structure.\r
+    ;\r
+    ; Some instructions for manipulation of segment registers have to be written\r
+    ; in opcode since 64-bit MASM prevents accesses to those registers.\r
+    ;\r
     DB      16h                         ; push ss\r
     DB      0eh                         ; push cs\r
     DB      66h\r
@@ -115,7 +123,7 @@ SavedCr4    DD      ?
     ;\r
     ; rdi in the instruction below is indeed bx in 16-bit code\r
     ;\r
-    DB      66h, 2eh\r
+    DB      66h, 2eh                    ; 2eh is "cs:" segment override\r
     lgdt    fword ptr [rdi + (SavedGdt - @Base)]\r
     DB      66h\r
     mov     ecx, 0c0000080h\r
@@ -129,9 +137,8 @@ SavedCr0    DD      ?
 @64Eip      DD      ?\r
 SavedCs     DW      ?\r
 @64BitCode:\r
-    DB      48h, 0b8h                   ; mov rax, imm64\r
-SavedRip    DQ      ?\r
-    jmp     rax                         ; return to caller\r
+    mov     rsp, r8                     ; restore stack\r
+    ret\r
 _BackFromUserCode   ENDP\r
 \r
 _EntryPoint DD      _ToUserCode - m16Start\r
@@ -160,14 +167,14 @@ _ToUserCode PROC
     mov     cr4, rbp\r
     mov     ss, esi                     ; set up 16-bit stack segment\r
     mov     sp, bx                      ; set up 16-bit stack pointer\r
-    DB      66h\r
+    DB      66h                         ; make the following call 32-bit\r
     call    @Base                       ; push eip\r
 @Base:\r
     pop     bp                          ; ebp <- address of @Base\r
     push    [esp + sizeof (IA32_REGS) + 2]\r
-    lea     eax, [rsi + (@RealMode - @Base)]\r
+    lea     eax, [rsi + (@RealMode - @Base)]    ; rsi is "bp" in 16-bit code\r
     push    rax\r
-    retf\r
+    retf                                ; execution begins at next instruction\r
 @RealMode:\r
     DB      66h, 2eh                    ; CS and operand size override\r
     lidt    fword ptr [rsi + (_16Idtr - @Base)]\r
@@ -178,7 +185,7 @@ _ToUserCode PROC
     pop     gs\r
     popf                                ; popfd\r
     lea     sp, [esp + 4]               ; skip high order 32 bits of EFlags\r
-    DB      66h\r
+    DB      66h                         ; make the following retf 32-bit\r
     retf                                ; transfer control to user code\r
 _ToUserCode ENDP\r
 \r
@@ -220,8 +227,8 @@ GDT_SIZE = $ - _NullSeg
 ;   );\r
 ;------------------------------------------------------------------------------\r
 InternalAsmThunk16  PROC    USES    rbp rbx rsi rdi\r
-    mov     r10d, ds\r
-    mov     r11d, es\r
+    mov     r10d, ds                    ; r9 ~ r11 are not accessible in 16-bit\r
+    mov     r11d, es                    ; so use them for saving seg registers\r
     mov     r9d, ss\r
     push    fs\r
     push    gs\r
@@ -238,8 +245,8 @@ InternalAsmThunk16  PROC    USES    rbp rbx rsi rdi
     lea     ecx, [rdx + (SavedCr4 - m16Start)]\r
     mov     eax, edx                    ; eax <- transition code address\r
     and     edx, 0fh\r
-    shl     eax, 12\r
-    lea     ax, [rdx + (_BackFromUserCode - m16Start)]\r
+    shl     eax, 12                     ; segment address in high order 16 bits\r
+    lea     ax, [rdx + (_BackFromUserCode - m16Start)]  ; offset address\r
     stosd                               ; [edi] <- return address of user code\r
     sgdt    fword ptr [rcx + (SavedGdt - SavedCr4)]\r
     sidt    fword ptr [rsp + 38h]       ; save IDT stack in argument space\r
@@ -257,13 +264,12 @@ InternalAsmThunk16  PROC    USES    rbp rbx rsi rdi
     pushfq\r
     lea     edx, [rdx + DATA16 - DATA32]\r
     lea     r8, @RetFromRealMode\r
-    mov     [rcx + (SavedRip - SavedCr4)], r8\r
+    push    r8\r
     mov     r8d, cs\r
     mov     [rcx + (SavedCs - SavedCr4)], r8w\r
     mov     r8, rsp\r
     jmp     fword ptr [rcx + (_EntryPoint - SavedCr4)]\r
 @RetFromRealMode:\r
-    mov     rsp, r8\r
     popfq\r
     lidt    fword ptr [rsp + 38h]       ; restore protected mode IDTR\r
     lea     eax, [rbp - sizeof (IA32_REGS)]\r