sync comments.

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

19 files changed, 77 insertions, 77 deletions

diff --git a/MdePkg/Library/BaseLib/Ia32/DisablePaging32.S b/MdePkg/Library/BaseLib/Ia32/DisablePaging32.S
index ee8efc62ef..d7aeec50cf 100644
--- a/MdePkg/Library/BaseLib/Ia32/DisablePaging32.S
+++ b/MdePkg/Library/BaseLib/Ia32/DisablePaging32.S
@@ -38,15 +38,15 @@ ASM_PFX(InternalX86DisablePaging32):
     movl    8(%esp), %ecx

     movl    12(%esp), %edx

     pushfl

-    pop     %edi

+    pop     %edi                        # save EFLAGS to edi

     cli

     movl    %cr0, %eax

     btrl    $31, %eax

     movl    16(%esp), %esp

     movl    %eax, %cr0

     push    %edi

-    popfl

+    popfl                               # restore EFLAGS from edi

     push    %edx

     push    %ecx

     call    *%ebx

-    jmp     .

+    jmp     .                           # EntryPoint() should not return

diff --git a/MdePkg/Library/BaseLib/Ia32/DivU64x32.S b/MdePkg/Library/BaseLib/Ia32/DivU64x32.S
index ca2ca192f9..c3f13960cc 100644
--- a/MdePkg/Library/BaseLib/Ia32/DivU64x32.S
+++ b/MdePkg/Library/BaseLib/Ia32/DivU64x32.S
@@ -34,8 +34,8 @@ ASM_PFX(InternalMathDivU64x32):
     movl    12(%esp), %ecx
     xorl    %edx, %edx
     divl    %ecx
-    push    %eax
+    push    %eax                    # save quotient on stack
     movl    8(%esp), %eax
     divl    %ecx
-    pop     %edx
+    pop     %edx                    # restore high-order dword of the quotient
     ret
diff --git a/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.S b/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.S
index e543fed321..87ca05357a 100644
--- a/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.S
+++ b/MdePkg/Library/BaseLib/Ia32/DivU64x32Remainder.S
@@ -31,16 +31,16 @@
 #   );

 #------------------------------------------------------------------------------

 ASM_PFX(InternalMathDivRemU64x32):

-    movl    12(%esp), %ecx

-    movl    8(%esp), %eax

+    movl    12(%esp), %ecx          # ecx <- divisor

+    movl    8(%esp), %eax           # eax <- dividend[32..63]

     xorl    %edx, %edx

-    divl    %ecx

+    divl    %ecx                    # eax <- quotient[32..63], edx <- remainder

     push    %eax

-    movl    8(%esp), %eax

-    divl    %ecx

-    movl    20(%esp), %ecx

-    jecxz   L1

+    movl    8(%esp), %eax           # eax <- dividend[0..31]

+    divl    %ecx                    # eax <- quotient[0..31]

+    movl    20(%esp), %ecx          # ecx <- Remainder

+    jecxz   L1                      # abandon remainder if Remainder == NULL

     movl    %edx, (%ecx)

 L1:

-    pop     %edx

+    pop     %edx                    # edx <- quotient[32..63]

     ret

diff --git a/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.S b/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.S
index f779e39159..b78697c73e 100644
--- a/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.S
+++ b/MdePkg/Library/BaseLib/Ia32/DivU64x64Remainder.S
@@ -32,13 +32,13 @@
 #   );

 #------------------------------------------------------------------------------

 ASM_PFX(InternalMathDivRemU64x64):

-    movl    16(%esp), %ecx

+    movl    16(%esp), %ecx              # ecx <- divisor[32..63]

     testl   %ecx, %ecx

-    jnz     Hard

+    jnz     Hard                        # call _@DivRemU64x64 if Divisor > 2^32

     movl    20(%esp), %ecx

     jecxz   L1

-    and     $0, 4(%ecx)

-    movl    %ecx, 16(%esp)

+    and     $0, 4(%ecx)                 # zero high dword of remainder

+    movl    %ecx, 16(%esp)              # set up stack frame to match DivRemU64x32

 L1:

     jmp     ASM_PFX(InternalMathDivRemU64x32)

 Hard:

@@ -46,10 +46,10 @@ Hard:
     push    %esi

     push    %edi

     mov     20(%esp), %edx

-    mov     16(%esp), %eax

+    mov     16(%esp), %eax              # edx:eax <- dividend

     movl    %edx, %edi

-    movl    %eax, %esi

-    mov     24(%esp), %ebx

+    movl    %eax, %esi                  # edi:esi <- dividend

+    mov     24(%esp), %ebx              # ecx:ebx <- divisor

 L2:

     shrl    %edx

     rcrl    $1, %eax

@@ -57,32 +57,32 @@ L2:
     shrl    %ecx

     jnz     L2

     divl    %ebx

-    movl    %eax, %ebx

-    movl    28(%esp), %ecx

-    mull    24(%esp)

-    imull   %ebx, %ecx

-    addl    %ecx, %edx

-    mov     32(%esp), %ecx

-    jc      TooLarge

-    cmpl    %edx, %edi

-    ja      Correct

-    jb      TooLarge

-    cmpl    %eax, %esi

-    jae     Correct

+    movl    %eax, %ebx                  # ebx <- quotient                     

+    movl    28(%esp), %ecx              # ecx <- high dword of divisor        

+    mull    24(%esp)                    # edx:eax <- quotient * divisor[0..31]

+    imull   %ebx, %ecx                  # ecx <- quotient * divisor[32..63]   

+    addl    %ecx, %edx                  # edx <- (quotient * divisor)[32..63] 

+    mov     32(%esp), %ecx              # ecx <- addr for Remainder           

+    jc      TooLarge                    # product > 2^64                      

+    cmpl    %edx, %edi                  # compare high 32 bits                

+    ja      Correct                                                           

+    jb      TooLarge                    # product > dividend                  

+    cmpl    %eax, %esi                                                        

+    jae     Correct                     # product <= dividend                 

 TooLarge:

-    decl    %ebx

-    jecxz   Return

-    sub     24(%esp), %eax

-    sbb     28(%esp), %edx

+    decl    %ebx                        # adjust quotient by -1              

+    jecxz   Return                      # return if Remainder == NULL        

+    sub     24(%esp), %eax                                                   

+    sbb     28(%esp), %edx              # edx:eax <- (quotient - 1) * divisor

 Correct:

     jecxz   Return

     subl    %eax, %esi

-    sbbl    %edx, %edi

+    sbbl    %edx, %edi                  # edi:esi <- remainder

     movl    %esi, (%ecx)

     movl    %edi, 4(%ecx)

 Return:

-    movl    %ebx, %eax

-    xorl    %edx, %edx

+    movl    %ebx, %eax                  # eax <- quotient         

+    xorl    %edx, %edx                  # quotient is 32 bits long

     pop     %edi

     pop     %esi

     pop     %ebx

diff --git a/MdePkg/Library/BaseLib/Ia32/EnablePaging32.S b/MdePkg/Library/BaseLib/Ia32/EnablePaging32.S
index 858755508a..caecf8b0df 100644
--- a/MdePkg/Library/BaseLib/Ia32/EnablePaging32.S
+++ b/MdePkg/Library/BaseLib/Ia32/EnablePaging32.S
@@ -38,14 +38,14 @@ ASM_PFX(InternalX86EnablePaging32):
     movl    8(%esp), %ecx

     movl    12(%esp), %edx

     pushfl

-    pop     %edi

+    pop     %edi                        # save flags in edi

     cli

     movl    %cr0, %eax

     btsl    $31, %eax

     movl    16(%esp), %esp

     movl    %eax, %cr0

     push    %edi

-    popfl

+    popfl                               # restore flags

     push    %edx

     push    %ecx

     call    *%ebx

diff --git a/MdePkg/Library/BaseLib/Ia32/EnablePaging64.S b/MdePkg/Library/BaseLib/Ia32/EnablePaging64.S
index 45ae2f306b..ce9d3eb2d9 100644
--- a/MdePkg/Library/BaseLib/Ia32/EnablePaging64.S
+++ b/MdePkg/Library/BaseLib/Ia32/EnablePaging64.S
@@ -36,7 +36,7 @@
 #------------------------------------------------------------------------------

 ASM_PFX(InternalX86EnablePaging64):

     cli

-    movl    $LongStart, (%esp)

+    movl    $LongStart, (%esp)          # offset for far retf, seg is the 1st arg

     movl    %cr4, %eax

     orb     $0x20, %al

     movl    %eax, %cr4                  # enable PAE

@@ -45,11 +45,11 @@ ASM_PFX(InternalX86EnablePaging64):
     orb     $1, %ah                     # set LME

     wrmsr

     movl    %cr0, %eax

-    btsl    $31, %eax

+    btsl    $31, %eax                   # set PG

     movl    %eax, %cr0                  # enable paging

-    lret

+    lret                                # topmost 2 dwords hold the address

 LongStart:                              # long mode starts here

-    .byte   0x67, 0x48

+    .byte   0x67, 0x48                  # 32-bit address size, 64-bit operand size

     movl    (%esp), %ebx                # mov rbx, [esp]

     .byte   0x67, 0x48

     movl    8(%esp), %ecx               # mov rcx, [esp + 8]

@@ -58,6 +58,6 @@ LongStart:                              # long mode starts here
     .byte   0x67, 0x48

     movl    0x18(%esp), %esp            # mov rsp, [esp + 18h]

     .byte   0x48

-    addl    $0x-0x20, %esp                # add rsp, -20h

+    addl    $0x-0x20, %esp              # add rsp, -20h

     call    *%ebx                       # call rbx

-    jmp     .

+    jmp     .                           # no one should get here

diff --git a/MdePkg/Library/BaseLib/Ia32/FxRestore.S b/MdePkg/Library/BaseLib/Ia32/FxRestore.S
index 600b1d7cc8..bda14dd15e 100644
--- a/MdePkg/Library/BaseLib/Ia32/FxRestore.S
+++ b/MdePkg/Library/BaseLib/Ia32/FxRestore.S
@@ -31,6 +31,6 @@
 #   );

 #------------------------------------------------------------------------------

 ASM_PFX(InternalX86FxRestore):

-    movl    4(%esp), %eax

+    movl    4(%esp), %eax               # Buffer must be 16-byte aligned

     fxrstor (%eax)

     ret

diff --git a/MdePkg/Library/BaseLib/Ia32/FxSave.S b/MdePkg/Library/BaseLib/Ia32/FxSave.S
index 81360846d9..b5c107f3ba 100644
--- a/MdePkg/Library/BaseLib/Ia32/FxSave.S
+++ b/MdePkg/Library/BaseLib/Ia32/FxSave.S
@@ -31,6 +31,6 @@
 #   );

 #------------------------------------------------------------------------------

 ASM_PFX(InternalX86FxSave):

-    movl    4(%esp), %eax

+    movl    4(%esp), %eax               # Buffer must be 16-byte aligned

     fxsave  (%eax)

     ret

diff --git a/MdePkg/Library/BaseLib/Ia32/LRotU64.S b/MdePkg/Library/BaseLib/Ia32/LRotU64.S
index 42bb22f131..615ff8146a 100644
--- a/MdePkg/Library/BaseLib/Ia32/LRotU64.S
+++ b/MdePkg/Library/BaseLib/Ia32/LRotU64.S
@@ -38,7 +38,7 @@ ASM_PFX(InternalMathLRotU64):
     shldl   %cl, %eax, %edx

     rorl    %cl, %ebx

     shldl   %cl, %ebx, %eax

-    testb   $32, %cl

+    testb   $32, %cl                    # Count >= 32?

     cmovnz  %eax, %ecx

     cmovnz  %edx, %eax

     cmovnz  %ecx, %edx

diff --git a/MdePkg/Library/BaseLib/Ia32/LShiftU64.S b/MdePkg/Library/BaseLib/Ia32/LShiftU64.S
index 9a9c2f68ae..e9ddf6f131 100644
--- a/MdePkg/Library/BaseLib/Ia32/LShiftU64.S
+++ b/MdePkg/Library/BaseLib/Ia32/LShiftU64.S
@@ -33,7 +33,7 @@ ASM_PFX(InternalMathLShiftU64):
     movb    12(%esp), %cl
     xorl    %eax, %eax
     movl    4(%esp), %edx
-    testb   $32, %cl
+    testb   $32, %cl                    # Count >= 32?
     cmovz   %edx, %eax
     cmovz   0x8(%esp), %edx
     shld    %cl, %eax, %edx
diff --git a/MdePkg/Library/BaseLib/Ia32/LongJump.S b/MdePkg/Library/BaseLib/Ia32/LongJump.S
index a280fe0241..11f8bd0f99 100644
--- a/MdePkg/Library/BaseLib/Ia32/LongJump.S
+++ b/MdePkg/Library/BaseLib/Ia32/LongJump.S
@@ -30,12 +30,12 @@
 #   );
 #------------------------------------------------------------------------------
 ASM_PFX(InternalLongJump):
-    pop     %eax
-    pop     %edx
-    pop     %eax
+    pop     %eax                        # skip return address
+    pop     %edx                        # edx <- JumpBuffer
+    pop     %eax                        # eax <- Value
     movl    (%edx), %ebx
     movl    4(%edx), %esi
     movl    8(%edx), %edi
     movl    12(%edx), %ebp
     movl    16(%edx), %esp
-    jmp     *20(%edx)
+    jmp     *20(%edx)                   # restore "eip"
diff --git a/MdePkg/Library/BaseLib/Ia32/Monitor.S b/MdePkg/Library/BaseLib/Ia32/Monitor.S
index d34b8c107b..48a87a1985 100644
--- a/MdePkg/Library/BaseLib/Ia32/Monitor.S
+++ b/MdePkg/Library/BaseLib/Ia32/Monitor.S
@@ -36,5 +36,5 @@ ASM_PFX(AsmMonitor):
     movl    4(%esp), %eax

     movl    8(%esp), %ecx

     movl    12(%esp), %edx

-    monitor %eax, %ecx, %edx

+    monitor %eax, %ecx, %edx            # monitor

     ret

diff --git a/MdePkg/Library/BaseLib/Ia32/MultU64x32.S b/MdePkg/Library/BaseLib/Ia32/MultU64x32.S
index 581f23e4ba..16cf86c0dc 100644
--- a/MdePkg/Library/BaseLib/Ia32/MultU64x32.S
+++ b/MdePkg/Library/BaseLib/Ia32/MultU64x32.S
@@ -35,7 +35,7 @@
 ASM_PFX(InternalMathMultU64x32):
     movl    12(%esp), %ecx
     movl    %ecx, %eax
-    imull   8(%esp), %ecx
+    imull   8(%esp), %ecx               # overflow not detectable
     mull    0x4(%esp)
     addl    %ecx, %edx
     ret
diff --git a/MdePkg/Library/BaseLib/Ia32/MultU64x64.S b/MdePkg/Library/BaseLib/Ia32/MultU64x64.S
index 0aae90c6cc..8dbae8b1a9 100644
--- a/MdePkg/Library/BaseLib/Ia32/MultU64x64.S
+++ b/MdePkg/Library/BaseLib/Ia32/MultU64x64.S
@@ -30,15 +30,15 @@
 #   );

 #------------------------------------------------------------------------------

 ASM_PFX(InternalMathMultU64x64):

-    push    %ebx

-    movl    8(%esp), %ebx

-    movl    16(%esp), %edx

-    movl    %ebx, %ecx

-    movl    %edx, %eax

-    imull   20(%esp), %ebx

-    imull   12(%esp), %edx

-    addl    %edx, %ebx

-    mull    %ecx

-    addl    %ebx, %edx

+    push    %ebx                                     

+    movl    8(%esp), %ebx             # ebx <- M1[0..31]                

+    movl    16(%esp), %edx            # edx <- M2[0..31]                                   

+    movl    %ebx, %ecx                                                  

+    movl    %edx, %eax                

+    imull   20(%esp), %ebx            # ebx <- M1[0..31] * M2[32..63]   

+    imull   12(%esp), %edx            # edx <- M1[32..63] * M2[0..31]   

+    addl    %edx, %ebx                # carries are abandoned           

+    mull    %ecx                      # edx:eax <- M1[0..31] * M2[0..31]

+    addl    %ebx, %edx                # carries are abandoned           

     pop     %ebx

     ret

diff --git a/MdePkg/Library/BaseLib/Ia32/Mwait.S b/MdePkg/Library/BaseLib/Ia32/Mwait.S
index 862dd41b09..9fd1efd0c9 100644
--- a/MdePkg/Library/BaseLib/Ia32/Mwait.S
+++ b/MdePkg/Library/BaseLib/Ia32/Mwait.S
@@ -34,5 +34,5 @@
 ASM_PFX(AsmMwait):

     movl    4(%esp), %eax

     movl    8(%esp), %ecx

-    mwait   %eax, %ecx

+    mwait   %eax, %ecx                  # mwait

     ret

diff --git a/MdePkg/Library/BaseLib/Ia32/RRotU64.S b/MdePkg/Library/BaseLib/Ia32/RRotU64.S
index 4b987478a0..cc5807648a 100644
--- a/MdePkg/Library/BaseLib/Ia32/RRotU64.S
+++ b/MdePkg/Library/BaseLib/Ia32/RRotU64.S
@@ -38,8 +38,8 @@ ASM_PFX(InternalMathRRotU64):
     shrdl   %cl, %edx, %eax

     roll    %cl, %ebx

     shrdl   %cl, %ebx, %edx

-    testb   $32, %cl

-    cmovnz  %eax, %ecx

+    testb   $32, %cl                    # Count >= 32?

+    cmovnz  %eax, %ecx                  # switch eax & edx if Count >= 32

     cmovnz  %edx, %eax

     cmovnz  %ecx, %edx

     pop     %ebx

diff --git a/MdePkg/Library/BaseLib/Ia32/RShiftU64.S b/MdePkg/Library/BaseLib/Ia32/RShiftU64.S
index f2a49cb9c0..ecb67e1552 100644
--- a/MdePkg/Library/BaseLib/Ia32/RShiftU64.S
+++ b/MdePkg/Library/BaseLib/Ia32/RShiftU64.S
@@ -33,10 +33,10 @@
 #   );
 #------------------------------------------------------------------------------
 ASM_PFX(InternalMathRShiftU64):
-    movb    12(%esp), %cl
+    movb    12(%esp), %cl               # cl <- Count
     xorl    %edx, %edx
     movl    8(%esp), %eax
-    testb   $32, %cl
+    testb   $32, %cl                    # Count >= 32?
     cmovz   %eax, %edx
     cmovz   0x4(%esp), %eax
     shrdl   %cl, %edx, %eax
diff --git a/MdePkg/Library/BaseLib/Ia32/SetJump.S b/MdePkg/Library/BaseLib/Ia32/SetJump.S
index acb2b95e25..dc7f048003 100644
--- a/MdePkg/Library/BaseLib/Ia32/SetJump.S
+++ b/MdePkg/Library/BaseLib/Ia32/SetJump.S
@@ -30,15 +30,15 @@
 #------------------------------------------------------------------------------

 ASM_PFX(SetJump):

     pushl   0x4(%esp)

-    call    ASM_PFX(InternalAssertJumpBuffer)

-    pop     %ecx

+    call    ASM_PFX(InternalAssertJumpBuffer)               # To validate JumpBuffer

     pop     %ecx

+    pop     %ecx                                            # ecx <- return address

     movl    (%esp), %edx

     movl    %ebx, (%edx)

     movl    %esi, 4(%edx)

     movl    %edi, 8(%edx)

     movl    %ebp, 12(%edx)

     movl    %esp, 16(%edx)

-    movl    %ecx, 20(%edx)

+    movl    %ecx, 20(%edx)                                  # eip value to restore in LongJump

     xorl    %eax, %eax

     jmp     *%ecx

diff --git a/MdePkg/Library/BaseLib/Ia32/SwapBytes64.S b/MdePkg/Library/BaseLib/Ia32/SwapBytes64.S
index 8c3864d864..f08177d97b 100644
--- a/MdePkg/Library/BaseLib/Ia32/SwapBytes64.S
+++ b/MdePkg/Library/BaseLib/Ia32/SwapBytes64.S
@@ -31,8 +31,8 @@
 #------------------------------------------------------------------------------
 .globl ASM_PFX(InternalMathSwapBytes64)
 ASM_PFX(InternalMathSwapBytes64):
-    movl    8(%esp), %eax
-    movl    4(%esp), %edx
+    movl    8(%esp), %eax               # eax <- upper 32 bits
+    movl    4(%esp), %edx               # edx <- lower 32 bits
     bswapl  %eax
     bswapl  %edx
     ret