From: bxing <bxing@6f19259b-4bc3-4df7-8a09-765794883524>
Date: Wed, 10 Jan 2007 06:57:04 +0000 (+0000)
Subject: 1. Added comments to ASM files
X-Git-Tag: edk2-stable201903~23671
X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=a9a812a0ed4ab3d83941fdc6da281aebdb9bb296

1. Added comments to ASM files
2. Fixed a bug in 64-bit AsmDisablePaging64(), which may cause a #GP exception.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@2206 6f19259b-4bc3-4df7-8a09-765794883524
---

diff --git a/MdePkg/Library/BaseLib/Ia32/CpuFlushTlb.asm b/MdePkg/Library/BaseLib/Ia32/CpuFlushTlb.asm
index 367412403e..4f0c4f9944 100644
--- a/MdePkg/Library/BaseLib/Ia32/CpuFlushTlb.asm
+++ b/MdePkg/Library/BaseLib/Ia32/CpuFlushTlb.asm
@@ -33,7 +33,7 @@
 ;------------------------------------------------------------------------------
 CpuFlushTlb PROC
     mov     eax, cr3
-    mov     cr3, eax
+    mov     cr3, eax                    ; moving to CR3 flushes TLB
     ret
 CpuFlushTlb ENDP
 
diff --git a/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.asm b/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.asm
index a836e22d0d..e025b22c2d 100644
--- a/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.asm
+++ b/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.asm
@@ -33,18 +33,18 @@
 ;   );
 ;------------------------------------------------------------------------------
 InternalMathDivRemU64x32    PROC
-    mov     ecx, [esp + 12]
-    mov     eax, [esp + 8]
+    mov     ecx, [esp + 12]         ; ecx <- divisor
+    mov     eax, [esp + 8]          ; eax <- dividend[32..63]
     xor     edx, edx
-    div     ecx
+    div     ecx                     ; eax <- quotient[32..63], edx <- remainder
     push    eax
-    mov     eax, [esp + 8]
-    div     ecx
-    mov     ecx, [esp + 20]
+    mov     eax, [esp + 8]          ; eax <- dividend[0..31]
+    div     ecx                     ; eax <- quotient[0..31]
+    mov     ecx, [esp + 20]         ; ecx <- Remainder
     jecxz   @F                      ; abandon remainder if Remainder == NULL
     mov     [ecx], edx
 @@:
-    pop     edx
+    pop     edx                     ; edx <- quotient[32..63]
     ret
 InternalMathDivRemU64x32    ENDP
 
diff --git a/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.asm b/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.asm
index 61a53d1e3a..95e57efac1 100644
--- a/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.asm
+++ b/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.asm
@@ -36,13 +36,13 @@ EXTERN  InternalMathDivRemU64x32:PROC
 ;   );
 ;------------------------------------------------------------------------------
 InternalMathDivRemU64x64    PROC
-    mov     ecx, [esp + 16]
+    mov     ecx, [esp + 16]             ; ecx <- divisor[32..63]
     test    ecx, ecx
     jnz     _@DivRemU64x64              ; call _@DivRemU64x64 if Divisor > 2^32
     mov     ecx, [esp + 20]
     jecxz   @F
-    and     dword ptr [ecx + 4], 0
-    mov     [esp + 16], ecx
+    and     dword ptr [ecx + 4], 0      ; zero high dword of remainder
+    mov     [esp + 16], ecx             ; set up stack frame to match DivRemU64x32
 @@:
     jmp     InternalMathDivRemU64x32
 InternalMathDivRemU64x64    ENDP
@@ -61,11 +61,11 @@ _@DivRemU64x64  PROC    USES    ebx esi edi
     jnz     @B
     div     ebx
     mov     ebx, eax                    ; ebx <- quotient
-    mov     ecx, [esp + 28]
-    mul     dword ptr [esp + 24]
-    imul    ecx, ebx
-    add     edx, ecx
-    mov     ecx, dword ptr [esp + 32]
+    mov     ecx, [esp + 28]             ; ecx <- high dword of divisor
+    mul     dword ptr [esp + 24]        ; edx:eax <- quotient * divisor[0..31]
+    imul    ecx, ebx                    ; ecx <- quotient * divisor[32..63]
+    add     edx, ecx                    ; edx <- (quotient * divisor)[32..63]
+    mov     ecx, dword ptr [esp + 32]   ; ecx <- addr for Remainder
     jc      @TooLarge                   ; product > 2^64
     cmp     edi, edx                    ; compare high 32 bits
     ja      @Correct
@@ -76,7 +76,7 @@ _@DivRemU64x64  PROC    USES    ebx esi edi
     dec     ebx                         ; adjust quotient by -1
     jecxz   @Return                     ; return if Remainder == NULL
     sub     eax, dword ptr [esp + 24]
-    sbb     edx, dword ptr [esp + 28]
+    sbb     edx, dword ptr [esp + 28]   ; edx:eax <- (quotient - 1) * divisor
 @Correct:
     jecxz   @Return
     sub     esi, eax
@@ -85,7 +85,7 @@ _@DivRemU64x64  PROC    USES    ebx esi edi
     mov     [ecx + 4], edi
 @Return:
     mov     eax, ebx                    ; eax <- quotient
-    xor     edx, edx
+    xor     edx, edx                    ; quotient is 32 bits long
     ret
 _@DivRemU64x64  ENDP
 
diff --git a/MdePkg/Library/BaseLib/Ia32/EnablePaging32.asm b/MdePkg/Library/BaseLib/Ia32/EnablePaging32.asm
index cf6f2fe458..ae98b93285 100644
--- a/MdePkg/Library/BaseLib/Ia32/EnablePaging32.asm
+++ b/MdePkg/Library/BaseLib/Ia32/EnablePaging32.asm
@@ -40,14 +40,14 @@ InternalX86EnablePaging32 PROC
     mov     ecx, [esp + 8]
     mov     edx, [esp + 12]
     pushfd
-    pop     edi
+    pop     edi                         ; save flags in edi
     cli
     mov     eax, cr0
     bts     eax, 31
     mov     esp, [esp + 16]
     mov     cr0, eax
     push    edi
-    popfd
+    popfd                               ; restore flags
     push    edx
     push    ecx
     call    ebx
diff --git a/MdePkg/Library/BaseLib/Ia32/EnablePaging64.asm b/MdePkg/Library/BaseLib/Ia32/EnablePaging64.asm
index 354d1fe603..435bb39105 100644
--- a/MdePkg/Library/BaseLib/Ia32/EnablePaging64.asm
+++ b/MdePkg/Library/BaseLib/Ia32/EnablePaging64.asm
@@ -47,11 +47,11 @@ InternalX86EnablePaging64 PROC
     or      ah, 1                       ; set LME
     wrmsr
     mov     eax, cr0
-    bts     eax, 31
+    bts     eax, 31                     ; set PG
     mov     cr0, eax                    ; enable paging
-    retf
+    retf                                ; topmost 2 dwords hold the address
 @@:                                     ; long mode starts here
-    DB      67h, 48h
+    DB      67h, 48h                    ; 32-bit address size, 64-bit operand size
     mov     ebx, [esp]                  ; mov rbx, [esp]
     DB      67h, 48h
     mov     ecx, [esp + 8]              ; mov rcx, [esp + 8]
@@ -62,7 +62,7 @@ InternalX86EnablePaging64 PROC
     DB      48h
     add     esp, -20h                   ; add rsp, -20h
     call    ebx                         ; call rbx
-    jmp     $
+    hlt                                 ; no one should get here
 InternalX86EnablePaging64 ENDP
 
     END
diff --git a/MdePkg/Library/BaseLib/Ia32/FxRestore.asm b/MdePkg/Library/BaseLib/Ia32/FxRestore.asm
index 9bcc6ac885..5def311700 100644
--- a/MdePkg/Library/BaseLib/Ia32/FxRestore.asm
+++ b/MdePkg/Library/BaseLib/Ia32/FxRestore.asm
@@ -34,7 +34,7 @@
 ;   );
 ;------------------------------------------------------------------------------
 InternalX86FxRestore  PROC
-    mov     eax, [esp + 4]
+    mov     eax, [esp + 4]              ; Buffer must be 16-byte aligned
     fxrstor [eax]
     ret
 InternalX86FxRestore  ENDP
diff --git a/MdePkg/Library/BaseLib/Ia32/FxSave.asm b/MdePkg/Library/BaseLib/Ia32/FxSave.asm
index 7d5ea45ffb..d3a9f9cd48 100644
--- a/MdePkg/Library/BaseLib/Ia32/FxSave.asm
+++ b/MdePkg/Library/BaseLib/Ia32/FxSave.asm
@@ -34,7 +34,7 @@
 ;   );
 ;------------------------------------------------------------------------------
 InternalX86FxSave PROC
-    mov     eax, [esp + 4]
+    mov     eax, [esp + 4]              ; Buffer must be 16-byte aligned
     fxsave  [eax]
     ret
 InternalX86FxSave ENDP
diff --git a/MdePkg/Library/BaseLib/Ia32/LongJump.asm b/MdePkg/Library/BaseLib/Ia32/LongJump.asm
index a634c4599c..0309f6ae71 100644
--- a/MdePkg/Library/BaseLib/Ia32/LongJump.asm
+++ b/MdePkg/Library/BaseLib/Ia32/LongJump.asm
@@ -40,7 +40,7 @@ InternalLongJump    PROC
     mov     edi, [edx + 8]
     mov     ebp, [edx + 12]
     mov     esp, [edx + 16]
-    jmp     dword ptr [edx + 20]
+    jmp     dword ptr [edx + 20]        ; restore "eip"
 InternalLongJump    ENDP
 
     END
diff --git a/MdePkg/Library/BaseLib/Ia32/MultU64x64.asm b/MdePkg/Library/BaseLib/Ia32/MultU64x64.asm
index 377aa51972..f3679548f1 100644
--- a/MdePkg/Library/BaseLib/Ia32/MultU64x64.asm
+++ b/MdePkg/Library/BaseLib/Ia32/MultU64x64.asm
@@ -32,15 +32,15 @@
 ;   );
 ;------------------------------------------------------------------------------
 InternalMathMultU64x64  PROC    USES    ebx
-    mov     ebx, [esp + 8]
-    mov     edx, [esp + 16]
+    mov     ebx, [esp + 8]              ; ebx <- M1[0..31]
+    mov     edx, [esp + 16]             ; edx <- M2[0..31]
     mov     ecx, ebx
     mov     eax, edx
-    imul    ebx, [esp + 20]
-    imul    edx, [esp + 12]
-    add     ebx, edx
-    mul     ecx
-    add     edx, ebx
+    imul    ebx, [esp + 20]             ; ebx <- M1[0..31] * M2[32..63]
+    imul    edx, [esp + 12]             ; edx <- M1[32..63] * M2[0..31]
+    add     ebx, edx                    ; carries are abandoned
+    mul     ecx                         ; edx:eax <- M1[0..31] * M2[0..31]
+    add     edx, ebx                    ; carries are abandoned
     ret
 InternalMathMultU64x64  ENDP
 
diff --git a/MdePkg/Library/BaseLib/Ia32/RRotU64.asm b/MdePkg/Library/BaseLib/Ia32/RRotU64.asm
index 4c58878ace..fe13abc0d5 100644
--- a/MdePkg/Library/BaseLib/Ia32/RRotU64.asm
+++ b/MdePkg/Library/BaseLib/Ia32/RRotU64.asm
@@ -40,7 +40,7 @@ InternalMathRRotU64 PROC    USES    ebx
     rol     ebx, cl
     shrd    edx, ebx, cl
     test    cl, 32                      ; Count >= 32?
-    cmovnz  ecx, eax
+    cmovnz  ecx, eax                    ; switch eax & edx if Count >= 32
     cmovnz  eax, edx
     cmovnz  edx, ecx
     ret
diff --git a/MdePkg/Library/BaseLib/Ia32/RShiftU64.asm b/MdePkg/Library/BaseLib/Ia32/RShiftU64.asm
index 793a8f988f..faa4e96771 100644
--- a/MdePkg/Library/BaseLib/Ia32/RShiftU64.asm
+++ b/MdePkg/Library/BaseLib/Ia32/RShiftU64.asm
@@ -32,10 +32,10 @@
 ;   );
 ;------------------------------------------------------------------------------
 InternalMathRShiftU64   PROC
-    mov     cl, [esp + 12]
+    mov     cl, [esp + 12]              ; cl <- Count
     xor     edx, edx
     mov     eax, [esp + 8]
-    test    cl, 32
+    test    cl, 32                      ; Count >= 32?
     cmovz   edx, eax
     cmovz   eax, [esp + 4]
     shrd    eax, edx, cl
diff --git a/MdePkg/Library/BaseLib/Ia32/ReadDr4.asm b/MdePkg/Library/BaseLib/Ia32/ReadDr4.asm
index d1fffe4ec0..606f26fe2a 100644
--- a/MdePkg/Library/BaseLib/Ia32/ReadDr4.asm
+++ b/MdePkg/Library/BaseLib/Ia32/ReadDr4.asm
@@ -33,6 +33,13 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadDr4  PROC
+    ;
+    ; DR4 is alias to DR6 only if DE (in CR4) is cleared. Otherwise, reading
+    ; this register will cause a #UD exception.
+    ;
+    ; MS assembler doesn't support this instruction since no one would use it
+    ; under normal circustances. Here opcode is used.
+    ;
     DB      0fh, 21h, 0e0h
     ret
 AsmReadDr4  ENDP
diff --git a/MdePkg/Library/BaseLib/Ia32/ReadDr5.asm b/MdePkg/Library/BaseLib/Ia32/ReadDr5.asm
index bba8b602ba..091792dab9 100644
--- a/MdePkg/Library/BaseLib/Ia32/ReadDr5.asm
+++ b/MdePkg/Library/BaseLib/Ia32/ReadDr5.asm
@@ -33,6 +33,13 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadDr5  PROC
+    ;
+    ; DR5 is alias to DR7 only if DE (in CR4) is cleared. Otherwise, reading
+    ; this register will cause a #UD exception.
+    ;
+    ; MS assembler doesn't support this instruction since no one would use it
+    ; under normal circustances. Here opcode is used.
+    ;
     DB      0fh, 21h, 0e8h
     ret
 AsmReadDr5  ENDP
diff --git a/MdePkg/Library/BaseLib/Ia32/SetJump.asm b/MdePkg/Library/BaseLib/Ia32/SetJump.asm
index 4d745e29ac..4b7b40c47a 100644
--- a/MdePkg/Library/BaseLib/Ia32/SetJump.asm
+++ b/MdePkg/Library/BaseLib/Ia32/SetJump.asm
@@ -34,16 +34,16 @@ InternalAssertJumpBuffer    PROTO   C
 ;------------------------------------------------------------------------------
 SetJump     PROC
     push    [esp + 4]
-    call    InternalAssertJumpBuffer
-    pop     ecx
+    call    InternalAssertJumpBuffer    ; To validate JumpBuffer
     pop     ecx
+    pop     ecx                         ; ecx <- return address
     mov     edx, [esp]
     mov     [edx], ebx
     mov     [edx + 4], esi
     mov     [edx + 8], edi
     mov     [edx + 12], ebp
     mov     [edx + 16], esp
-    mov     [edx + 20], ecx
+    mov     [edx + 20], ecx             ; eip value to restore in LongJump
     xor     eax, eax
     jmp     ecx
 SetJump     ENDP
diff --git a/MdePkg/Library/BaseLib/Ia32/SwapBytes64.asm b/MdePkg/Library/BaseLib/Ia32/SwapBytes64.asm
index 186d094eee..7647880202 100644
--- a/MdePkg/Library/BaseLib/Ia32/SwapBytes64.asm
+++ b/MdePkg/Library/BaseLib/Ia32/SwapBytes64.asm
@@ -33,8 +33,8 @@
 ;   );
 ;------------------------------------------------------------------------------
 InternalMathSwapBytes64 PROC
-    mov     eax, [esp + 8]
-    mov     edx, [esp + 4]
+    mov     eax, [esp + 8]              ; eax <- upper 32 bits
+    mov     edx, [esp + 4]              ; edx <- lower 32 bits
     bswap   eax
     bswap   edx
     ret
diff --git a/MdePkg/Library/BaseLib/Ia32/Thunk16.asm b/MdePkg/Library/BaseLib/Ia32/Thunk16.asm
index 5e35799127..5c9bc81a2b 100644
--- a/MdePkg/Library/BaseLib/Ia32/Thunk16.asm
+++ b/MdePkg/Library/BaseLib/Ia32/Thunk16.asm
@@ -75,6 +75,11 @@ SavedGdt    LABEL   FWORD
 ; by user code. It will be shadowed to somewhere in memory below 1MB.
 ;------------------------------------------------------------------------------
 _BackFromUserCode   PROC
+    ;
+    ; The order of saved registers on the stack matches the order they appears
+    ; in IA32_REGS structure. This facilitates wrapper function to extract them
+    ; into that structure.
+    ;
     push    ss
     push    cs
     DB      66h
@@ -104,6 +109,11 @@ _ThunkAttr  DD      ?
     mov     eax, ss
     DB      67h
     lea     bp, [esp + sizeof (IA32_REGS)]
+    ;
+    ; esi's in the following 2 instructions are indeed bp in 16-bit code. Fact
+    ; is "esi" in 32-bit addressing mode has the same encoding of "bp" in 16-
+    ; bit addressing mode.
+    ;
     mov     word ptr (IA32_REGS ptr [esi - sizeof (IA32_REGS)])._ESP, bp
     mov     ebx, (IA32_REGS ptr [esi - sizeof (IA32_REGS)])._EIP
     shl     ax, 4                       ; shl eax, 4
@@ -167,7 +177,7 @@ _ToUserCode PROC
     pop     fs
     pop     gs
     popf                                ; popfd
-    DB      66h
+    DB      66h                         ; Use 32-bit addressing for "retf" below
     retf                                ; transfer control to user code
 _ToUserCode ENDP
 
@@ -197,7 +207,7 @@ GdtEnd          LABEL   QWORD
 ;   );
 ;------------------------------------------------------------------------------
 InternalAsmThunk16  PROC    USES    ebp ebx esi edi ds  es  fs  gs
-    mov     esi, [esp + 36]             ; esi <- RegSet
+    mov     esi, [esp + 36]             ; esi <- RegSet, the 1st parameter
     movzx   edx, (IA32_REGS ptr [esi])._SS
     mov     edi, (IA32_REGS ptr [esi])._ESP
     add     edi, - (sizeof (IA32_REGS) + 4) ; reserve stack space
@@ -227,11 +237,11 @@ InternalAsmThunk16  PROC    USES    ebp ebx esi edi ds  es  fs  gs
     push    10h
     pop     ecx                         ; ecx <- selector for data segments
     lgdt    fword ptr [edx + (_16Gdtr - SavedCr0)]
-    pushfd
+    pushfd                              ; Save df/if indeed
     call    fword ptr [edx + (_EntryPoint - SavedCr0)]
     popfd
     lidt    fword ptr [esp + 36]        ; restore protected mode IDTR
-    lea     eax, [ebp - sizeof (IA32_REGS)]
+    lea     eax, [ebp - sizeof (IA32_REGS)] ; eax <- the address of IA32_REGS
     ret
 InternalAsmThunk16  ENDP
 
diff --git a/MdePkg/Library/BaseLib/Ia32/WriteDr4.asm b/MdePkg/Library/BaseLib/Ia32/WriteDr4.asm
index ca9a839f70..9c10305b4d 100644
--- a/MdePkg/Library/BaseLib/Ia32/WriteDr4.asm
+++ b/MdePkg/Library/BaseLib/Ia32/WriteDr4.asm
@@ -34,6 +34,13 @@
 ;------------------------------------------------------------------------------
 AsmWriteDr4 PROC
     mov     eax, [esp + 4]
+    ;
+    ; DR4 is alias to DR6 only if DE (in CR4) is cleared. Otherwise, writing to
+    ; this register will cause a #UD exception.
+    ;
+    ; MS assembler doesn't support this instruction since no one would use it
+    ; under normal circustances. Here opcode is used.
+    ;
     DB      0fh, 23h, 0e0h
     ret
 AsmWriteDr4 ENDP
diff --git a/MdePkg/Library/BaseLib/Ia32/WriteDr5.asm b/MdePkg/Library/BaseLib/Ia32/WriteDr5.asm
index c6def6820c..e10434ef3d 100644
--- a/MdePkg/Library/BaseLib/Ia32/WriteDr5.asm
+++ b/MdePkg/Library/BaseLib/Ia32/WriteDr5.asm
@@ -34,6 +34,13 @@
 ;------------------------------------------------------------------------------
 AsmWriteDr5 PROC
     mov     eax, [esp + 4]
+    ;
+    ; DR5 is alias to DR7 only if DE (in CR4) is cleared. Otherwise, writing to
+    ; this register will cause a #UD exception.
+    ;
+    ; MS assembler doesn't support this instruction since no one would use it
+    ; under normal circustances. Here opcode is used.
+    ;
     DB      0fh, 23h, 0e8h
     ret
 AsmWriteDr5 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/DisablePaging64.asm b/MdePkg/Library/BaseLib/X64/DisablePaging64.asm
index 2609c941aa..518137ddc9 100644
--- a/MdePkg/Library/BaseLib/X64/DisablePaging64.asm
+++ b/MdePkg/Library/BaseLib/X64/DisablePaging64.asm
@@ -36,15 +36,14 @@
 ;------------------------------------------------------------------------------
 InternalX86DisablePaging64    PROC
     cli
-    shl     rcx, 32
+    shl     rcx, 32                     ; rcx[32..47] <- Cs
     lea     eax, @F
-    mov     ecx, eax
-    push    rcx
-    mov     ebx, edx
     mov     esi, r8d
+    or      rcx, rax                    ; rcx[0..47] <- Cs:@F
     mov     edi, r9d
-    mov     eax, [rsp + 28h]
-    retf
+    mov     eax, [rsp + 28h]            ; eax <- New Stack
+    push    rcx
+    retf                                ; switch to compatibility mode
 @@:
     mov     esp, eax                    ; set up new stack
     mov     rax, cr0
@@ -57,10 +56,10 @@ InternalX86DisablePaging64    PROC
     mov     rax, cr4
     and     al, NOT (1 SHL 5)           ; clear PAE
     mov     cr4, rax
-    push    rdi
-    push    rsi
-    call    rbx
-    jmp     $
+    push    rdi                         ; push Context2
+    push    rsi                         ; push Context1
+    call    rdx                         ; transfer control to EntryPoint
+    hlt                                 ; no one should get here
 InternalX86DisablePaging64    ENDP
 
     END
diff --git a/MdePkg/Library/BaseLib/X64/EnablePaging64.asm b/MdePkg/Library/BaseLib/X64/EnablePaging64.asm
index 459120a886..c54843008a 100644
--- a/MdePkg/Library/BaseLib/X64/EnablePaging64.asm
+++ b/MdePkg/Library/BaseLib/X64/EnablePaging64.asm
@@ -36,7 +36,7 @@
 ;------------------------------------------------------------------------------
 InternalX86EnablePaging64 PROC
     cli
-    pop     rax
+    pop     rax                         ; skip the return address
     call    @Base
 @Base:
     add     dword ptr [rsp], @F - @Base ; offset for far retf, seg is the 1st arg
@@ -58,7 +58,7 @@ InternalX86EnablePaging64 PROC
     mov     rsp, [esp + 18h]
     add     rsp, -20h
     call    rbx
-    jmp     $                           ; halt processor if EntryPoint() returned
+    hlt                                 ; halt processor if EntryPoint() returned
 InternalX86EnablePaging64 ENDP
 
     END
diff --git a/MdePkg/Library/BaseLib/X64/LongJump.asm b/MdePkg/Library/BaseLib/X64/LongJump.asm
index 6ef5f964e0..38e5606081 100644
--- a/MdePkg/Library/BaseLib/X64/LongJump.asm
+++ b/MdePkg/Library/BaseLib/X64/LongJump.asm
@@ -39,7 +39,7 @@ InternalLongJump    PROC
     mov     r13, [rcx + 30h]
     mov     r14, [rcx + 38h]
     mov     r15, [rcx + 40h]
-    mov     rax, rdx
+    mov     rax, rdx                    ; set return value
     jmp     qword ptr [rcx + 48h]
 InternalLongJump    ENDP
 
diff --git a/MdePkg/Library/BaseLib/X64/Monitor.asm b/MdePkg/Library/BaseLib/X64/Monitor.asm
index 0140494d30..ec9c3f8d03 100644
--- a/MdePkg/Library/BaseLib/X64/Monitor.asm
+++ b/MdePkg/Library/BaseLib/X64/Monitor.asm
@@ -36,7 +36,7 @@ AsmMonitor  PROC
     mov     eax, ecx
     mov     ecx, edx
     mov     edx, r8d
-    DB      0fh, 1, 0c8h
+    DB      0fh, 1, 0c8h                ; monitor
     ret
 AsmMonitor  ENDP
 
diff --git a/MdePkg/Library/BaseLib/X64/Mwait.asm b/MdePkg/Library/BaseLib/X64/Mwait.asm
index 8f76d944f1..aae1d42758 100644
--- a/MdePkg/Library/BaseLib/X64/Mwait.asm
+++ b/MdePkg/Library/BaseLib/X64/Mwait.asm
@@ -34,7 +34,7 @@
 AsmMwait    PROC
     mov     eax, ecx
     mov     ecx, edx
-    DB      0fh, 1, 0c9h
+    DB      0fh, 1, 0c9h                ; mwait
     ret
 AsmMwait    ENDP
 
diff --git a/MdePkg/Library/BaseLib/X64/ReadDr4.asm b/MdePkg/Library/BaseLib/X64/ReadDr4.asm
index 97740016b3..2bed12928b 100644
--- a/MdePkg/Library/BaseLib/X64/ReadDr4.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadDr4.asm
@@ -31,6 +31,10 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadDr4  PROC
+    ;
+    ; There's no obvious reason to access this register, since it's aliased to
+    ; DR7 when DE=0 or an exception generated when DE=1
+    ;
     DB      0fh, 21h, 0e0h
     ret
 AsmReadDr4  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadDr5.asm b/MdePkg/Library/BaseLib/X64/ReadDr5.asm
index 0582502220..3bee3a56ec 100644
--- a/MdePkg/Library/BaseLib/X64/ReadDr5.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadDr5.asm
@@ -31,6 +31,10 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadDr5  PROC
+    ;
+    ; There's no obvious reason to access this register, since it's aliased to
+    ; DR7 when DE=0 or an exception generated when DE=1
+    ;
     DB      0fh, 21h, 0e8h
     ret
 AsmReadDr5  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm0.asm b/MdePkg/Library/BaseLib/X64/ReadMm0.asm
index a81d208298..0ed5c8f8ae 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm0.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm0.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm0  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0c0h
     ret
 AsmReadMm0  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm1.asm b/MdePkg/Library/BaseLib/X64/ReadMm1.asm
index 5da8c4f9e5..e24fcb5f9d 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm1.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm1.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm1  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0c8h
     ret
 AsmReadMm1  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm2.asm b/MdePkg/Library/BaseLib/X64/ReadMm2.asm
index 3b2b1e3af3..860326b375 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm2.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm2.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm2  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0d0h
     ret
 AsmReadMm2  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm3.asm b/MdePkg/Library/BaseLib/X64/ReadMm3.asm
index 6283c30285..aca6f3d2df 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm3.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm3.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm3  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0d8h
     ret
 AsmReadMm3  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm4.asm b/MdePkg/Library/BaseLib/X64/ReadMm4.asm
index a65f130283..dd52f99436 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm4.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm4.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm4  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0e0h
     ret
 AsmReadMm4  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm5.asm b/MdePkg/Library/BaseLib/X64/ReadMm5.asm
index 5295c38ae0..1f30e4bed4 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm5.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm5.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm5  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0e8h
     ret
 AsmReadMm5  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm6.asm b/MdePkg/Library/BaseLib/X64/ReadMm6.asm
index acdc99b888..4e1f2a824b 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm6.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm6.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm6  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0f0h
     ret
 AsmReadMm6  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/ReadMm7.asm b/MdePkg/Library/BaseLib/X64/ReadMm7.asm
index 7a1b4e6111..d871a9f8dc 100644
--- a/MdePkg/Library/BaseLib/X64/ReadMm7.asm
+++ b/MdePkg/Library/BaseLib/X64/ReadMm7.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmReadMm7  PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 7eh, 0f8h
     ret
 AsmReadMm7  ENDP
diff --git a/MdePkg/Library/BaseLib/X64/Thunk16.asm b/MdePkg/Library/BaseLib/X64/Thunk16.asm
index 642310869b..556a8b47e3 100644
--- 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.
 ;------------------------------------------------------------------------------
 _BackFromUserCode   PROC
+    ;
+    ; The order of saved registers on the stack matches the order they appears
+    ; in IA32_REGS structure. This facilitates wrapper function to extract them
+    ; into that structure.
+    ;
+    ; Some instructions for manipulation of segment registers have to be written
+    ; in opcode since 64-bit MASM prevents accesses to those registers.
+    ;
     DB      16h                         ; push ss
     DB      0eh                         ; push cs
     DB      66h
@@ -115,7 +123,7 @@ SavedCr4    DD      ?
     ;
     ; rdi in the instruction below is indeed bx in 16-bit code
     ;
-    DB      66h, 2eh
+    DB      66h, 2eh                    ; 2eh is "cs:" segment override
     lgdt    fword ptr [rdi + (SavedGdt - @Base)]
     DB      66h
     mov     ecx, 0c0000080h
@@ -129,9 +137,8 @@ SavedCr0    DD      ?
 @64Eip      DD      ?
 SavedCs     DW      ?
 @64BitCode:
-    DB      48h, 0b8h                   ; mov rax, imm64
-SavedRip    DQ      ?
-    jmp     rax                         ; return to caller
+    mov     rsp, r8                     ; restore stack
+    ret
 _BackFromUserCode   ENDP
 
 _EntryPoint DD      _ToUserCode - m16Start
@@ -160,14 +167,14 @@ _ToUserCode PROC
     mov     cr4, rbp
     mov     ss, esi                     ; set up 16-bit stack segment
     mov     sp, bx                      ; set up 16-bit stack pointer
-    DB      66h
+    DB      66h                         ; make the following call 32-bit
     call    @Base                       ; push eip
 @Base:
     pop     bp                          ; ebp <- address of @Base
     push    [esp + sizeof (IA32_REGS) + 2]
-    lea     eax, [rsi + (@RealMode - @Base)]
+    lea     eax, [rsi + (@RealMode - @Base)]    ; rsi is "bp" in 16-bit code
     push    rax
-    retf
+    retf                                ; execution begins at next instruction
 @RealMode:
     DB      66h, 2eh                    ; CS and operand size override
     lidt    fword ptr [rsi + (_16Idtr - @Base)]
@@ -178,7 +185,7 @@ _ToUserCode PROC
     pop     gs
     popf                                ; popfd
     lea     sp, [esp + 4]               ; skip high order 32 bits of EFlags
-    DB      66h
+    DB      66h                         ; make the following retf 32-bit
     retf                                ; transfer control to user code
 _ToUserCode ENDP
 
@@ -220,8 +227,8 @@ GDT_SIZE = $ - _NullSeg
 ;   );
 ;------------------------------------------------------------------------------
 InternalAsmThunk16  PROC    USES    rbp rbx rsi rdi
-    mov     r10d, ds
-    mov     r11d, es
+    mov     r10d, ds                    ; r9 ~ r11 are not accessible in 16-bit
+    mov     r11d, es                    ; so use them for saving seg registers
     mov     r9d, ss
     push    fs
     push    gs
@@ -238,8 +245,8 @@ InternalAsmThunk16  PROC    USES    rbp rbx rsi rdi
     lea     ecx, [rdx + (SavedCr4 - m16Start)]
     mov     eax, edx                    ; eax <- transition code address
     and     edx, 0fh
-    shl     eax, 12
-    lea     ax, [rdx + (_BackFromUserCode - m16Start)]
+    shl     eax, 12                     ; segment address in high order 16 bits
+    lea     ax, [rdx + (_BackFromUserCode - m16Start)]  ; offset address
     stosd                               ; [edi] <- return address of user code
     sgdt    fword ptr [rcx + (SavedGdt - SavedCr4)]
     sidt    fword ptr [rsp + 38h]       ; save IDT stack in argument space
@@ -257,13 +264,12 @@ InternalAsmThunk16  PROC    USES    rbp rbx rsi rdi
     pushfq
     lea     edx, [rdx + DATA16 - DATA32]
     lea     r8, @RetFromRealMode
-    mov     [rcx + (SavedRip - SavedCr4)], r8
+    push    r8
     mov     r8d, cs
     mov     [rcx + (SavedCs - SavedCr4)], r8w
     mov     r8, rsp
     jmp     fword ptr [rcx + (_EntryPoint - SavedCr4)]
 @RetFromRealMode:
-    mov     rsp, r8
     popfq
     lidt    fword ptr [rsp + 38h]       ; restore protected mode IDTR
     lea     eax, [rbp - sizeof (IA32_REGS)]
diff --git a/MdePkg/Library/BaseLib/X64/WriteDr4.asm b/MdePkg/Library/BaseLib/X64/WriteDr4.asm
index ad618f1089..188a9d4ddc 100644
--- a/MdePkg/Library/BaseLib/X64/WriteDr4.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteDr4.asm
@@ -31,6 +31,10 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteDr4 PROC
+    ;
+    ; There's no obvious reason to access this register, since it's aliased to
+    ; DR6 when DE=0 or an exception generated when DE=1
+    ;
     DB      0fh, 23h, 0e1h
     mov     rax, rcx
     ret
diff --git a/MdePkg/Library/BaseLib/X64/WriteDr5.asm b/MdePkg/Library/BaseLib/X64/WriteDr5.asm
index 91eeef20e3..86009c3287 100644
--- a/MdePkg/Library/BaseLib/X64/WriteDr5.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteDr5.asm
@@ -31,6 +31,10 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteDr5 PROC
+    ;
+    ; There's no obvious reason to access this register, since it's aliased to
+    ; DR7 when DE=0 or an exception generated when DE=1
+    ;
     DB      0fh, 23h, 0e9h
     mov     rax, rcx
     ret
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm0.asm b/MdePkg/Library/BaseLib/X64/WriteMm0.asm
index 0ad65e366d..7496362d86 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm0.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm0.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm0 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0c1h
     ret
 AsmWriteMm0 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm1.asm b/MdePkg/Library/BaseLib/X64/WriteMm1.asm
index 66425a43c2..a00f551f8a 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm1.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm1.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm1 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0c9h
     ret
 AsmWriteMm1 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm2.asm b/MdePkg/Library/BaseLib/X64/WriteMm2.asm
index bd0f0a0e1a..01db79007d 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm2.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm2.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm2 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0d1h
     ret
 AsmWriteMm2 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm3.asm b/MdePkg/Library/BaseLib/X64/WriteMm3.asm
index fa36ea64bb..59464641eb 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm3.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm3.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm3 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0d9h
     ret
 AsmWriteMm3 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm4.asm b/MdePkg/Library/BaseLib/X64/WriteMm4.asm
index d9bc46e16c..6848dbf7ec 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm4.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm4.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm4 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0e1h
     ret
 AsmWriteMm4 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm5.asm b/MdePkg/Library/BaseLib/X64/WriteMm5.asm
index f268bea8ec..fbe44ae078 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm5.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm5.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm5 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0e9h
     ret
 AsmWriteMm5 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm6.asm b/MdePkg/Library/BaseLib/X64/WriteMm6.asm
index cb32ea6dc3..cd5938828d 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm6.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm6.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm6 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0f1h
     ret
 AsmWriteMm6 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMm7.asm b/MdePkg/Library/BaseLib/X64/WriteMm7.asm
index f5713823bb..9636a4cd8d 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMm7.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMm7.asm
@@ -31,6 +31,9 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMm7 PROC
+    ;
+    ; 64-bit MASM doesn't support MMX instructions, so use opcode here
+    ;
     DB      48h, 0fh, 6eh, 0f9h
     ret
 AsmWriteMm7 ENDP
diff --git a/MdePkg/Library/BaseLib/X64/WriteMsr64.asm b/MdePkg/Library/BaseLib/X64/WriteMsr64.asm
index 6b8066f922..b7704b8185 100644
--- a/MdePkg/Library/BaseLib/X64/WriteMsr64.asm
+++ b/MdePkg/Library/BaseLib/X64/WriteMsr64.asm
@@ -32,8 +32,8 @@
 ;   );
 ;------------------------------------------------------------------------------
 AsmWriteMsr64   PROC
-    mov     rax, rdx
-    shr     rdx, 20h
+    mov     rax, rdx                    ; meanwhile, rax <- return value
+    shr     rdx, 20h                    ; edx:eax contains the value to write
     wrmsr
     ret
 AsmWriteMsr64   ENDP