MdePkg/BaseLib: add PatchInstructionX86()

[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index 05eb4e33a086abf1498b18ea35d2b7a4bc12eda9..eb2899f8524e7a8e1856d68f0c25ced58c4253fb 100644 (file)
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -1119,7 +1119,7 @@ StrnCpy (
   IN      CONST CHAR16              *Source,\r
   IN      UINTN                     Length\r
   );\r
-#endif\r
+#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
 \r
 /**\r
   Returns the length of a Null-terminated Unicode string.\r
@@ -1338,7 +1338,7 @@ StrnCat (
   IN      CONST CHAR16              *Source,\r
   IN      UINTN                     Length\r
   );\r
-#endif\r
+#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
 \r
 /**\r
   Returns the first occurrence of a Null-terminated Unicode sub-string\r
@@ -1811,7 +1811,7 @@ UnicodeStrToAsciiStr (
   OUT     CHAR8                     *Destination\r
   );\r
 \r
-#endif\r
+#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
 \r
 /**\r
   Convert a Null-terminated Unicode string to a Null-terminated\r
@@ -1985,7 +1985,7 @@ AsciiStrnCpy (
   IN      CONST CHAR8               *Source,\r
   IN      UINTN                     Length\r
   );\r
-#endif\r
+#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
 \r
 /**\r
   Returns the length of a Null-terminated ASCII string.\r
@@ -2229,7 +2229,7 @@ AsciiStrnCat (
   IN      CONST CHAR8               *Source,\r
   IN      UINTN                     Length\r
   );\r
-#endif\r
+#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
 \r
 /**\r
   Returns the first occurrence of a Null-terminated ASCII sub-string\r
@@ -2670,7 +2670,7 @@ AsciiStrToUnicodeStr (
   OUT     CHAR16                    *Destination\r
   );\r
 \r
-#endif\r
+#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)\r
 \r
 /**\r
   Convert one Null-terminated ASCII string to a Null-terminated\r
@@ -4903,6 +4903,7 @@ MemoryFence (
   @retval 0 Indicates a return from SetJump().\r
 \r
 **/\r
+RETURNS_TWICE\r
 UINTN\r
 EFIAPI\r
 SetJump (\r
@@ -6494,7 +6495,7 @@ AsmPalCall (
   IN UINT64  Arg3,\r
   IN UINT64  Arg4\r
   );\r
-#endif\r
+#endif // defined (MDE_CPU_IPF)\r
 \r
 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)\r
 ///\r
@@ -6729,7 +6730,7 @@ typedef union {
 } IA32_TSS_DESCRIPTOR;\r
 #pragma pack ()\r
 \r
-#endif\r
+#endif // defined (MDE_CPU_IA32)\r
 \r
 #if defined (MDE_CPU_X64)\r
 ///\r
@@ -6791,7 +6792,7 @@ typedef union {
 } IA32_TSS_DESCRIPTOR;\r
 #pragma pack ()\r
 \r
-#endif\r
+#endif // defined (MDE_CPU_X64)\r
 \r
 ///\r
 /// Byte packed structure for an FP/SSE/SSE2 context.\r
@@ -6880,6 +6881,20 @@ typedef struct {
 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15   0x00000002\r
 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004\r
 \r
+///\r
+/// Type definition for representing labels in NASM source code that allow for\r
+/// the patching of immediate operands of IA32 and X64 instructions.\r
+///\r
+/// While the type is technically defined as a function type (note: not a\r
+/// pointer-to-function type), such labels in NASM source code never stand for\r
+/// actual functions, and identifiers declared with this function type should\r
+/// never be called. This is also why the EFIAPI calling convention specifier\r
+/// is missing from the typedef, and why the typedef does not follow the usual\r
+/// edk2 coding style for function (or pointer-to-function) typedefs. The VOID\r
+/// return type and the VOID argument list are merely artifacts.\r
+///\r
+typedef VOID (X86_ASSEMBLY_PATCH_LABEL) (VOID);\r
+\r
 /**\r
   Retrieves CPUID information.\r
 \r
@@ -9067,7 +9082,47 @@ AsmWriteTr (
   IN UINT16 Selector\r
   );\r
 \r
-#endif\r
-#endif\r
+/**\r
+  Patch the immediate operand of an IA32 or X64 instruction such that the byte,\r
+  word, dword or qword operand is encoded at the end of the instruction's\r
+  binary representation.\r
+\r
+  This function should be used to update object code that was compiled with\r
+  NASM from assembly source code. Example:\r
+\r
+  NASM source code:\r
 \r
+        mov     eax, strict dword 0 ; the imm32 zero operand will be patched\r
+    ASM_PFX(gPatchCr3):\r
+        mov     cr3, eax\r
+\r
+  C source code:\r
+\r
+    X86_ASSEMBLY_PATCH_LABEL gPatchCr3;\r
+    PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);\r
+\r
+  @param[out] InstructionEnd  Pointer right past the instruction to patch. The\r
+                              immediate operand to patch is expected to\r
+                              comprise the trailing bytes of the instruction.\r
+                              If InstructionEnd is closer to address 0 than\r
+                              ValueSize permits, then ASSERT().\r
+\r
+  @param[in] PatchValue       The constant to write to the immediate operand.\r
+                              The caller is responsible for ensuring that\r
+                              PatchValue can be represented in the byte, word,\r
+                              dword or qword operand (as indicated through\r
+                              ValueSize); otherwise ASSERT().\r
+\r
+  @param[in] ValueSize        The size of the operand in bytes; must be 1, 2,\r
+                              4, or 8. ASSERT() otherwise.\r
+**/\r
+VOID\r
+EFIAPI\r
+PatchInstructionX86 (\r
+  OUT X86_ASSEMBLY_PATCH_LABEL *InstructionEnd,\r
+  IN  UINT64                   PatchValue,\r
+  IN  UINTN                    ValueSize\r
+  );\r
 \r
+#endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)\r
+#endif // !defined (__BASE_LIB__)\r