Synchronize BaseLib h files to c files.

[mirror_edk2.git] / MdePkg / Library / BaseLib / X86Thunk.c

diff --git a/MdePkg/Library/BaseLib/X86Thunk.c b/MdePkg/Library/BaseLib/X86Thunk.c
index 7bcde8389d1a553cf796acad3b774bcc5aaba39a..019524b6053c22aea56e42c054b63a70fc0265e7 100644 (file)
--- a/MdePkg/Library/BaseLib/X86Thunk.c
+++ b/MdePkg/Library/BaseLib/X86Thunk.c
@@ -185,11 +185,47 @@ AsmPrepareThunk16 (
   Transfers control to a 16-bit real mode entry point and returns the results.\r
 \r
   Transfers control to a 16-bit real mode entry point and returns the results.\r
-  AsmPrepareThunk16() must be called with ThunkContext before this function is\r
-  used. This function must be called with interrupts disabled.\r
-\r
+  AsmPrepareThunk16() must be called with ThunkContext before this function is used.\r
+  This function must be called with interrupts disabled.\r
+\r
+  The register state from the RealModeState field of ThunkContext is restored just prior \r
+  to calling the 16-bit real mode entry point.  This includes the EFLAGS field of RealModeState, \r
+  which is used to set the interrupt state when a 16-bit real mode entry point is called.\r
+  Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.\r
+  The stack is initialized to the SS and ESP fields of RealModeState.  Any parameters passed to \r
+  the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.  \r
+  The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,\r
+  so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment \r
+  and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry \r
+  point must exit with a RETF instruction. The register state is captured into RealModeState immediately \r
+  after the RETF instruction is executed.\r
+  \r
+  If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, \r
+  or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure \r
+  the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode. \r
+  \r
+  If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, \r
+  then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.  \r
+  This includes the base vectors, the interrupt masks, and the edge/level trigger mode.\r
+  \r
+  If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code \r
+  is invoked in big real mode.  Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.\r
+  \r
+  If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in \r
+  ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to \r
+  disable the A20 mask.\r
+  \r
+  If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in \r
+  ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask.  If this INT 15 call fails, \r
+  then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.\r
+  \r
+  If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in \r
+  ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.\r
+    \r
   If ThunkContext is NULL, then ASSERT().\r
   If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().\r
+  If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in \r
+  ThunkAttributes, then ASSERT().\r
 \r
   @param  ThunkContext  A pointer to the context structure that describes the\r
                         16-bit real mode code to call.\r
@@ -225,10 +261,9 @@ AsmThunk16 (
   caller only need to perform a single 16-bit real mode thunk, then this\r
   service should be used. If the caller intends to make more than one 16-bit\r
   real mode thunk, then it is more efficient if AsmPrepareThunk16() is called\r
-  once and AsmThunk16() can be called for each 16-bit real mode thunk. This\r
-  function must be called with interrupts disabled.\r
+  once and AsmThunk16() can be called for each 16-bit real mode thunk.\r
 \r
-  If ThunkContext is NULL, then ASSERT().\r
+  See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.\r
 \r
   @param  ThunkContext  A pointer to the context structure that describes the\r
                         16-bit real mode code to call.\r