Insert instruction patch, lang="C" via copy-and-micropatch strategy

README.md

@@ -51,14 +51,15 @@ General documentation and API reference for Patcherex2 can be found at [pursecla
 
 |           | Linux x86 | Linux amd64 | Linux arm | Linux aarch64 | Linux PowerPC (32bit) | Linux PowerPC (64bit) | Linux PowerPCle (64bit) | Linux MIPS (32bit) | Linux MIPS (64bit) | Linux MIPSEL<br>​(32bit) | Linux MIPSEL<br>(64bit) | SPARCv8 (LEON3) | PowerPC (VLE) (IHEX)
 |-|-|-|-|-|-|-|-|-|-|-|-|-|-|
-InsertDataPatch         | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-RemoveDataPatch         | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-ModifyDataPatch         | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-InsertInstructionPatch  | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-RemoveInstructionPatch  | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-ModifyInstructionPatch  | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-InsertFunctionPatch     | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
-ModifyFunctionPatch     | 🟨 | 🟩 | 🟩 | 🟩 | 🟨 | 🟨 | 🟨 | 🟨 | 🟨 | 🟨 | 🟨 | ⬜ | ⬜ |
+InsertDataPatch              | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+RemoveDataPatch              | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+ModifyDataPatch              | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+InsertInstructionPatch (ASM) | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+InsertInstructionPatch (C)   | 🟥 | 🟩 | 🟥 | 🟨 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 | 🟥 |
+RemoveInstructionPatch       | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+ModifyInstructionPatch       | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+InsertFunctionPatch          | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | 🟩 | ⬜ | ⬜ |
+ModifyFunctionPatch          | 🟨 | 🟩 | 🟩 | 🟩 | 🟨 | 🟨 | 🟨 | 🟨 | 🟨 | 🟨 | 🟨 | ⬜ | ⬜ |
 
 🟩 Fully Functional, 🟨 Limited Functionality, 🟥 Not Working, ⬜ Not Tested, 🟪 Work in Progress
 

examples/insert_instruction_patch_c/add.c

@@ -0,0 +1,10 @@
+#include <stdio.h>
+
+int add(int a, int b) {
+    return a + b;
+}
+
+int main() {
+    printf("2 + 3 = %d\n", add(2, 3));
+    return 0;
+}

examples/insert_instruction_patch_c/patch.py

@@ -0,0 +1,57 @@
+from patcherex2 import *
+import logging
+
+logger = logging.getLogger("patcherex2.patches.instruction_patches")
+logger.setLevel(logging.INFO)
+
+p = Patcherex("add", target_opts={"compiler": "clang19"})
+
+c_forward_header = """
+// This string will be inserted outside the micropatch function. It will be inserted before your code.
+// This is how you can define types and function forward declarations used by your C micropatch
+#include <stdio.h>
+"""
+
+# The asm_header is inserted in the main body of the patch before the C code. This header is primarily
+# useful for gaining access to the stack pointer, which is a register that is unavailable in our C
+# code. In this example we have moved rsp to the r12 register, which is a register that is accessible.
+# This means that inside the C code we can access variables on the stack by using the r10 variable.
+# There is also an asm_footer
+asm_header = "mov r12, rsp"
+
+# We can access assembly registers directly by using their name, while still using high level C constructs
+# as well as intermediate variables. Note that you can use a return statement anywhere in your C micropatch
+# to jump back to the next instruction after the micropatch insertion point.
+c_str = """
+rdi += rdi;
+rdi += 5;
+// Print out rsp as it was before the patch was started
+printf("%p\\n", (void *) r12);
+"""
+
+# It is generally a good idea to mark some registers as scratch to give the compiler
+# breathing room for allocating registers to use for intermediate variables in your micropatch
+# All of the registers that we mark as scratch can be freely clobbered by the compiler
+# Note that you can still read from scratch registers stored in the variables. What the scratch
+# register denotation will indicate however is that the register can be re-used after the variable
+# is no longer live.
+c_scratch_regs = [
+    'r8', 'r9', 'r10', 'r11', 'r13', 'r14', 'r15'
+    'xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7', 'xmm9', 'xmm10', 'xmm11', 'xmm12', 'xmm13', 'xmm14', 'xmm15'
+]
+
+# By default floating point registers will have the 'float' type. We can use c_float_types to override
+# certain registers so they hold different types. In this example we denote that xmm8 is of type double
+c_float_types = {'xmm8': 'double'}
+
+config = InsertInstructionPatch.CConfig(
+    c_forward_header = c_forward_header,
+    scratch_regs=c_scratch_regs,
+    float_types=c_float_types,
+    asm_header=asm_header
+)
+
+p.patches.append(InsertInstructionPatch(0x114d, c_str, language="C", c_config=config))
+p.apply_patches()
+
+p.binfmt_tool.save_binary()

src/patcherex2/components/archinfo/aarch64.py

@@ -4,6 +4,7 @@ class Aarch64Info:
     jmp_asm = "b {dst}"
     jmp_size = 4
     alignment = 4
+    bits = 64
     is_variable_length_isa = False
     instr_size = 4
     call_asm = "bl {dst}"
@@ -46,3 +47,51 @@ class Aarch64Info:
         ldr x30, [sp, #0xf0]
         add sp, sp, #0x1f0
     """
+
+    cc = {
+        'default': ['x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7'],
+        'defaultPreserveNone': None # TODO once aarch64 support lands in LLVM for preserve_none
+    }
+    callee_saved = {
+        'default': ['x19', 'x20', 'x21', 'x22', 'x23', 'x24', 'x25', 'x26', 'x27', 'x28', 'x29', 'x30']
+    }
+    cc_float = {
+        'default': ['v0', 'v1', 'v2', 'v3', 'v4', 'v5', 'v6', 'v7']
+    }
+    callee_saved_float = {
+        'default': ['v8', 'v9', 'v10', 'v11', 'v12', 'v13', 'v14', 'v15']
+    }
+
+    float_types = {
+        32: 'float',
+        64: 'double',
+        128: 'long double'
+    }
+
+    @property
+    def regs(self):
+        return list(self.subregisters.keys())
+
+    @property
+    def regs_float(self):
+        return list(self.subregisters_float.keys())
+
+    subregisters = {
+        'x{}'.format(i):
+            {
+                64: ['x{}'.format(i)],
+                32: ['w{}'.format(i)]
+            }
+        for i in range(0, 30 + 1)
+    }
+
+    subregisters_float = {
+        'v{}'.format(i): {
+            128: ['v{}'.format(i)],
+            64: ['d{}'.format(i)],
+            32: ['s{}'.format(i)],
+            16: ['h{}'.format(i)],
+            8: ['b{}'.format(i)]
+        }
+        for i in range(0, 30 + 1)
+    }

src/patcherex2/components/archinfo/amd64.py

@@ -4,6 +4,7 @@ class Amd64Info:
     jmp_asm = "jmp {dst}"
     jmp_size = 6
     alignment = 4
+    bits = 64
     is_variable_length_isa = True
     instr_size = -1  # variable length
     call_asm = "call {dst}"
@@ -44,3 +45,142 @@ class Amd64Info:
     pop rbx
     pop rax
     """
+
+    cc = {
+        'Linux': ['rdi', 'rsi', 'rdx', 'rcx', 'r8', 'r9'],
+        'LinuxPreserveNone': ['r12', 'r13', 'r14', 'r15', 'rdi', 'rsi', 'rdx', 'rcx', 'r8', 'r9', 'r11', 'rax'],
+        'Windows': ['rcx', 'rdx', 'r8', 'r9']
+    }
+    callee_saved = {
+        'Linux': ['r12', 'r13', 'r14', 'r15', 'rbx', 'rsp', 'rbp']
+    }
+    cc_float = {
+        'Linux': ['xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7']
+    }
+    callee_saved_float = {
+        'Linux': []
+    }
+
+    float_types = {
+        32: 'float',
+        64: 'double',
+        128: '__float128'
+    }
+
+    @property
+    def regs(self):
+        return list(self.subregisters.keys())
+
+    @property
+    def regs_float(self):
+        return list(self.subregisters_float.keys())
+
+    subregisters = {
+        'rax': {
+            64: ['rax'],
+            32: ['eax'],
+            16: ['ax'],
+            # Note that the order of the children registers is important. Only the 0th
+            # element of this list (al) is used when determining the calling convention.
+            # That is, we can only use the following argument 'uint8_t al' in the
+            # calling convention at the rax position. 'uint8_t ah' is NOT allowed.
+            8: ['al', 'ah']
+        },
+        'rbx': {
+            64: ['rbx'],
+            32: ['ebx'],
+            16: ['bx'],
+            8: ['bl', 'bh']
+        },
+        'rcx': {
+            64: ['rcx'],
+            32: ['ecx'],
+            16: ['cx'],
+            8: ['cl', 'ch']
+        },
+        'rdx': {
+            64: ['rdx'],
+            32: ['edx'],
+            16: ['dx'],
+            8: ['dl', 'dh']
+        },
+        'rsi': {
+            64: ['rsi'],
+            32: ['esi'],
+            16: ['si'],
+            8: ['sil']
+        },
+        'rdi': {
+            64: ['rdi'],
+            32: ['edi'],
+            16: ['di'],
+            8: ['dil']
+        },
+        'rbp': {
+            64: ['rbp'],
+            32: ['ebp'],
+            16: ['bp'],
+            8: ['bpl']
+        },
+        'rsp': {
+            64: ['rsp'],
+            32: ['esp'],
+            16: ['sp'],
+            8: ['spl']
+        },
+        'r8': {
+            64: ['r8'],
+            32: ['r8d'],
+            16: ['r8w'],
+            8: ['r8b']
+        },
+        'r9': {
+            64: ['r9'],
+            32: ['r9d'],
+            16: ['r9w'],
+            8: ['r9b']
+        },
+        'r10': {
+            64: ['r10'],
+            32: ['r10d'],
+            16: ['r10w'],
+            8: ['r10b']
+        },
+        'r11': {
+            64: ['r11'],
+            32: ['r11d'],
+            16: ['r11w'],
+            8: ['r11b']
+        },
+        'r12': {
+            64: ['r12'],
+            32: ['r12d'],
+            16: ['r12w'],
+            8: ['r12b']
+        },
+        'r13': {
+            64: ['r13'],
+            32: ['r13d'],
+            16: ['r13w'],
+            8: ['r13b']
+        },
+        'r14': {
+            64: ['r14'],
+            32: ['r14d'],
+            16: ['r14w'],
+            8: ['r14b']
+        },
+        'r15': {
+            64: ['r15'],
+            32: ['r15d'],
+            16: ['r15w'],
+            8: ['r15b']
+        }
+    }
+
+    subregisters_float = {
+        'xmm{}'.format(i): {
+            128: ['xmm{}'.format(i)]
+        }
+        for i in range(0, 15 + 1)
+    }

src/patcherex2/components/archinfo/arm.py

@@ -4,6 +4,7 @@ class ArmInfo:
     jmp_asm = "b {dst}"
     jmp_size = 4
     alignment = 4
+    bits = 32
     is_variable_length_isa = False
     instr_size = 4  # TODO: thumb 2
     call_asm = "bl {dst}"

src/patcherex2/components/archinfo/mips.py

@@ -5,6 +5,7 @@ class MipsInfo:
     # NOTE: keystone will always add nop for branch delay slot, so include it in size
     jmp_size = 8
     alignment = 4
+    bits = 32
     is_variable_length_isa = False
     instr_size = 4
     call_asm = "jal {dst}"

src/patcherex2/components/archinfo/mips64.py

@@ -5,6 +5,7 @@ class Mips64Info:
     # NOTE: keystone will aldays add nop for branch delay slot, so include it in size
     jmp_size = 8
     alignment = 4
+    bits = 64
     is_variable_length_isa = False
     instr_size = 4
     call_asm = "jal {dst}"

src/patcherex2/components/archinfo/ppc.py

@@ -4,6 +4,7 @@ class PpcInfo:
     jmp_asm = "b {dst}"
     jmp_size = 4
     alignment = 4
+    bits = 32
     is_variable_length_isa = False
     instr_size = 4
     call_asm = "bl {dst}"

src/patcherex2/components/archinfo/ppc64.py

@@ -4,6 +4,7 @@ class Ppc64Info:
     jmp_asm = "b {dst}"
     jmp_size = 4
     alignment = 4
+    bits = 64
     is_variable_length_isa = False
     instr_size = 4
     call_asm = "bl {dst}"

src/patcherex2/components/archinfo/ppc_vle.py

@@ -4,6 +4,7 @@ class PpcVleInfo:
     jmp_asm = "b {dst}"
     jmp_size = 4
     alignment = 4
+    bits = 32
     is_variable_length_isa = True
     instr_size = -1  # variable length
     call_asm = "bl {dst}"

src/patcherex2/components/archinfo/x86.py

@@ -4,6 +4,7 @@ class X86Info:
     jmp_asm = "jmp {dst}"
     jmp_size = 5
     alignment = 4
+    bits = 32
     is_variable_length_isa = True
     instr_size = -1  # variable length
     call_asm = "call {dst}"

src/patcherex2/components/assemblers/assembler.py

@@ -26,6 +26,8 @@ def _pre_assemble_hook(self, code: str, base=0) -> None:
         return code
 
     def assemble(self, code: str, base=0, symbols=None, **kwargs) -> None:
+        if code == "":
+            return bytes()
         if symbols is None:
             symbols = {}
         logger.debug(f"Assembling `{code}` at {hex(base)}")

src/patcherex2/components/compilers/clang.py

@@ -12,6 +12,8 @@ def __init__(
         self, p, clang_version=15, compiler_flags: list[str] | None = None
     ) -> None:
         super().__init__(p)
+        if clang_version >= 19:
+            self.preserve_none = True
         if compiler_flags is None:
             compiler_flags = []
         self._compiler = f"clang-{clang_version}"

src/patcherex2/components/compilers/compiler.py

@@ -14,6 +14,9 @@
 class Compiler:
     def __init__(self, p) -> None:
         self.p = p
+        # preserve_none is a special attribute flag to allow us to control more registers as input to a C function
+        # This feature is used for a C instruction patch
+        self.preserve_none = False
 
     def compile(
         self,