Racket

Racket Unicorn🔗ℹ

dannypsnl

(require racket-unicorn)

package: racket-unicorn

Racket FFI bindings for the Unicorn CPU emulator.

1 Constants🔗ℹ

1.1 Architecture Types🔗ℹ

value
UC_ARCH_ARM64 : exact-integer?

ARM64 architecture.

value
UC_ARCH_X86 : exact-integer?

X86 architecture.

value
UC_ARCH_RISCV : exact-integer?

RISC-V architecture.

1.2 Mode Types🔗ℹ

value
UC_MODE_ARM : exact-integer?

ARM mode.

value
UC_MODE_LITTLE_ENDIAN : exact-integer?

Little-endian mode.

value
UC_MODE_64 : exact-integer?

64-bit mode (for x86).

value
UC_MODE_RISCV32 : exact-integer?

32-bit RISC-V mode.

value
UC_MODE_RISCV64 : exact-integer?

64-bit RISC-V mode.

1.3 Error Codes🔗ℹ

value
UC_ERR_OK : exact-integer?

No error (success).

1.4 Memory Permissions🔗ℹ

value
UC_PROT_NONE : exact-integer?

No permissions.

value
UC_PROT_READ : exact-integer?

Read permission.

value
UC_PROT_WRITE : exact-integer?

Write permission.

value
UC_PROT_EXEC : exact-integer?

Execute permission.

value
UC_PROT_ALL : exact-integer?

All permissions (read, write, execute).

1.5 ARM64 General Purpose Registers🔗ℹ

value
UC_ARM64_REG_INVALID : exact-integer?

Invalid register.

value
UC_ARM64_REG_X0 : exact-integer?
value
UC_ARM64_REG_X1 : exact-integer?
value
UC_ARM64_REG_X2 : exact-integer?
value
UC_ARM64_REG_X3 : exact-integer?
value
UC_ARM64_REG_X4 : exact-integer?
value
UC_ARM64_REG_X5 : exact-integer?
value
UC_ARM64_REG_X6 : exact-integer?
value
UC_ARM64_REG_X7 : exact-integer?
value
UC_ARM64_REG_X8 : exact-integer?
value
UC_ARM64_REG_X9 : exact-integer?
value
UC_ARM64_REG_X10 : exact-integer?
value
UC_ARM64_REG_X11 : exact-integer?
value
UC_ARM64_REG_X12 : exact-integer?
value
UC_ARM64_REG_X13 : exact-integer?
value
UC_ARM64_REG_X14 : exact-integer?
value
UC_ARM64_REG_X15 : exact-integer?
value
UC_ARM64_REG_X16 : exact-integer?
value
UC_ARM64_REG_X17 : exact-integer?
value
UC_ARM64_REG_X18 : exact-integer?
value
UC_ARM64_REG_X19 : exact-integer?
value
UC_ARM64_REG_X20 : exact-integer?
value
UC_ARM64_REG_X21 : exact-integer?
value
UC_ARM64_REG_X22 : exact-integer?
value
UC_ARM64_REG_X23 : exact-integer?
value
UC_ARM64_REG_X24 : exact-integer?
value
UC_ARM64_REG_X25 : exact-integer?
value
UC_ARM64_REG_X26 : exact-integer?
value
UC_ARM64_REG_X27 : exact-integer?
value
UC_ARM64_REG_X28 : exact-integer?

ARM64 general purpose registers X0 through X28.

value
UC_ARM64_REG_X29 : exact-integer?

Frame pointer (FP) register.

value
UC_ARM64_REG_X30 : exact-integer?

Link register (LR).

value
UC_ARM64_REG_SP : exact-integer?

Stack pointer register.

value
UC_ARM64_REG_PC : exact-integer?

Program counter register.

1.6 ARM64 SIMD Registers🔗ℹ

value
UC_ARM64_REG_V0 : exact-integer?
value
UC_ARM64_REG_V1 : exact-integer?
value
UC_ARM64_REG_V2 : exact-integer?
value
UC_ARM64_REG_V3 : exact-integer?
value
UC_ARM64_REG_V4 : exact-integer?
value
UC_ARM64_REG_V5 : exact-integer?
value
UC_ARM64_REG_V6 : exact-integer?
value
UC_ARM64_REG_V7 : exact-integer?
value
UC_ARM64_REG_V8 : exact-integer?
value
UC_ARM64_REG_V9 : exact-integer?
value
UC_ARM64_REG_V10 : exact-integer?
value
UC_ARM64_REG_V11 : exact-integer?
value
UC_ARM64_REG_V12 : exact-integer?
value
UC_ARM64_REG_V13 : exact-integer?
value
UC_ARM64_REG_V14 : exact-integer?
value
UC_ARM64_REG_V15 : exact-integer?
value
UC_ARM64_REG_V16 : exact-integer?
value
UC_ARM64_REG_V17 : exact-integer?
value
UC_ARM64_REG_V18 : exact-integer?
value
UC_ARM64_REG_V19 : exact-integer?
value
UC_ARM64_REG_V20 : exact-integer?
value
UC_ARM64_REG_V21 : exact-integer?
value
UC_ARM64_REG_V22 : exact-integer?
value
UC_ARM64_REG_V23 : exact-integer?
value
UC_ARM64_REG_V24 : exact-integer?
value
UC_ARM64_REG_V25 : exact-integer?
value
UC_ARM64_REG_V26 : exact-integer?
value
UC_ARM64_REG_V27 : exact-integer?
value
UC_ARM64_REG_V28 : exact-integer?
value
UC_ARM64_REG_V29 : exact-integer?
value
UC_ARM64_REG_V30 : exact-integer?
value
UC_ARM64_REG_V31 : exact-integer?

ARM64 NEON/SIMD 128-bit registers V0 through V31.

1.7 X86-64 Registers🔗ℹ

value
UC_X86_REG_INVALID : exact-integer?

Invalid register.

value
UC_X86_REG_RAX : exact-integer?
value
UC_X86_REG_RBX : exact-integer?
value
UC_X86_REG_RCX : exact-integer?
value
UC_X86_REG_RDX : exact-integer?
value
UC_X86_REG_RSI : exact-integer?
value
UC_X86_REG_RDI : exact-integer?
value
UC_X86_REG_RSP : exact-integer?
value
UC_X86_REG_RBP : exact-integer?
value
UC_X86_REG_R8 : exact-integer?
value
UC_X86_REG_R9 : exact-integer?
value
UC_X86_REG_R10 : exact-integer?
value
UC_X86_REG_R11 : exact-integer?
value
UC_X86_REG_R12 : exact-integer?
value
UC_X86_REG_R13 : exact-integer?
value
UC_X86_REG_R14 : exact-integer?
value
UC_X86_REG_R15 : exact-integer?
value
UC_X86_REG_RIP : exact-integer?

X86-64 general purpose and instruction pointer registers.

1.8 RISC-V General Purpose Registers🔗ℹ

value
UC_RISCV_REG_INVALID : exact-integer?

Invalid register.

value
UC_RISCV_REG_X0 : exact-integer?
value
UC_RISCV_REG_X1 : exact-integer?
value
UC_RISCV_REG_X2 : exact-integer?
value
UC_RISCV_REG_X3 : exact-integer?
value
UC_RISCV_REG_X4 : exact-integer?
value
UC_RISCV_REG_X5 : exact-integer?
value
UC_RISCV_REG_X6 : exact-integer?
value
UC_RISCV_REG_X7 : exact-integer?
value
UC_RISCV_REG_X8 : exact-integer?
value
UC_RISCV_REG_X9 : exact-integer?
value
UC_RISCV_REG_X10 : exact-integer?
value
UC_RISCV_REG_X11 : exact-integer?
value
UC_RISCV_REG_X12 : exact-integer?
value
UC_RISCV_REG_X13 : exact-integer?
value
UC_RISCV_REG_X14 : exact-integer?
value
UC_RISCV_REG_X15 : exact-integer?
value
UC_RISCV_REG_X16 : exact-integer?
value
UC_RISCV_REG_X17 : exact-integer?
value
UC_RISCV_REG_X18 : exact-integer?
value
UC_RISCV_REG_X19 : exact-integer?
value
UC_RISCV_REG_X20 : exact-integer?
value
UC_RISCV_REG_X21 : exact-integer?
value
UC_RISCV_REG_X22 : exact-integer?
value
UC_RISCV_REG_X23 : exact-integer?
value
UC_RISCV_REG_X24 : exact-integer?
value
UC_RISCV_REG_X25 : exact-integer?
value
UC_RISCV_REG_X26 : exact-integer?
value
UC_RISCV_REG_X27 : exact-integer?
value
UC_RISCV_REG_X28 : exact-integer?
value
UC_RISCV_REG_X29 : exact-integer?
value
UC_RISCV_REG_X30 : exact-integer?
value
UC_RISCV_REG_X31 : exact-integer?

RISC-V general purpose registers X0 through X31.

1.9 RISC-V Floating-Point Registers🔗ℹ

value
UC_RISCV_REG_F0 : exact-integer?
value
UC_RISCV_REG_F1 : exact-integer?
value
UC_RISCV_REG_F2 : exact-integer?
value
UC_RISCV_REG_F3 : exact-integer?
value
UC_RISCV_REG_F4 : exact-integer?
value
UC_RISCV_REG_F5 : exact-integer?
value
UC_RISCV_REG_F6 : exact-integer?
value
UC_RISCV_REG_F7 : exact-integer?
value
UC_RISCV_REG_F8 : exact-integer?
value
UC_RISCV_REG_F9 : exact-integer?
value
UC_RISCV_REG_F10 : exact-integer?
value
UC_RISCV_REG_F11 : exact-integer?
value
UC_RISCV_REG_F12 : exact-integer?
value
UC_RISCV_REG_F13 : exact-integer?
value
UC_RISCV_REG_F14 : exact-integer?
value
UC_RISCV_REG_F15 : exact-integer?
value
UC_RISCV_REG_F16 : exact-integer?
value
UC_RISCV_REG_F17 : exact-integer?
value
UC_RISCV_REG_F18 : exact-integer?
value
UC_RISCV_REG_F19 : exact-integer?
value
UC_RISCV_REG_F20 : exact-integer?
value
UC_RISCV_REG_F21 : exact-integer?
value
UC_RISCV_REG_F22 : exact-integer?
value
UC_RISCV_REG_F23 : exact-integer?
value
UC_RISCV_REG_F24 : exact-integer?
value
UC_RISCV_REG_F25 : exact-integer?
value
UC_RISCV_REG_F26 : exact-integer?
value
UC_RISCV_REG_F27 : exact-integer?
value
UC_RISCV_REG_F28 : exact-integer?
value
UC_RISCV_REG_F29 : exact-integer?
value
UC_RISCV_REG_F30 : exact-integer?
value
UC_RISCV_REG_F31 : exact-integer?

RISC-V floating-point registers F0 through F31.

value
UC_RISCV_REG_PC : exact-integer?

RISC-V program counter register.

1.10 RISC-V ABI Name Aliases (GP Registers)🔗ℹ

value
UC_RISCV_REG_ZERO : exact-integer?
value
UC_RISCV_REG_RA : exact-integer?
value
UC_RISCV_REG_SP : exact-integer?
value
UC_RISCV_REG_GP : exact-integer?
value
UC_RISCV_REG_TP : exact-integer?
value
UC_RISCV_REG_T0 : exact-integer?
value
UC_RISCV_REG_T1 : exact-integer?
value
UC_RISCV_REG_T2 : exact-integer?
value
UC_RISCV_REG_S0 : exact-integer?
value
UC_RISCV_REG_FP : exact-integer?
value
UC_RISCV_REG_S1 : exact-integer?
value
UC_RISCV_REG_A0 : exact-integer?
value
UC_RISCV_REG_A1 : exact-integer?
value
UC_RISCV_REG_A2 : exact-integer?
value
UC_RISCV_REG_A3 : exact-integer?
value
UC_RISCV_REG_A4 : exact-integer?
value
UC_RISCV_REG_A5 : exact-integer?
value
UC_RISCV_REG_A6 : exact-integer?
value
UC_RISCV_REG_A7 : exact-integer?
value
UC_RISCV_REG_S2 : exact-integer?
value
UC_RISCV_REG_S3 : exact-integer?
value
UC_RISCV_REG_S4 : exact-integer?
value
UC_RISCV_REG_S5 : exact-integer?
value
UC_RISCV_REG_S6 : exact-integer?
value
UC_RISCV_REG_S7 : exact-integer?
value
UC_RISCV_REG_S8 : exact-integer?
value
UC_RISCV_REG_S9 : exact-integer?
value
UC_RISCV_REG_S10 : exact-integer?
value
UC_RISCV_REG_S11 : exact-integer?
value
UC_RISCV_REG_T3 : exact-integer?
value
UC_RISCV_REG_T4 : exact-integer?
value
UC_RISCV_REG_T5 : exact-integer?
value
UC_RISCV_REG_T6 : exact-integer?

RISC-V ABI name aliases for general purpose registers. UC_RISCV_REG_ZERO is the hard-wired zero register, UC_RISCV_REG_RA is the return address, UC_RISCV_REG_SP is the stack pointer, UC_RISCV_REG_GP is the global pointer, UC_RISCV_REG_TP is the thread pointer, UC_RISCV_REG_S0/UC_RISCV_REG_FP is the frame pointer, UC_RISCV_REG_A0 through UC_RISCV_REG_A7 are argument registers, UC_RISCV_REG_S0 through UC_RISCV_REG_S11 are saved registers, and UC_RISCV_REG_T0 through UC_RISCV_REG_T6 are temporary registers.

1.11 RISC-V ABI Name Aliases (FP Registers)🔗ℹ

value
UC_RISCV_REG_FT0 : exact-integer?
value
UC_RISCV_REG_FT1 : exact-integer?
value
UC_RISCV_REG_FT2 : exact-integer?
value
UC_RISCV_REG_FT3 : exact-integer?
value
UC_RISCV_REG_FT4 : exact-integer?
value
UC_RISCV_REG_FT5 : exact-integer?
value
UC_RISCV_REG_FT6 : exact-integer?
value
UC_RISCV_REG_FT7 : exact-integer?
value
UC_RISCV_REG_FS0 : exact-integer?
value
UC_RISCV_REG_FS1 : exact-integer?
value
UC_RISCV_REG_FA0 : exact-integer?
value
UC_RISCV_REG_FA1 : exact-integer?
value
UC_RISCV_REG_FA2 : exact-integer?
value
UC_RISCV_REG_FA3 : exact-integer?
value
UC_RISCV_REG_FA4 : exact-integer?
value
UC_RISCV_REG_FA5 : exact-integer?
value
UC_RISCV_REG_FA6 : exact-integer?
value
UC_RISCV_REG_FA7 : exact-integer?
value
UC_RISCV_REG_FS2 : exact-integer?
value
UC_RISCV_REG_FS3 : exact-integer?
value
UC_RISCV_REG_FS4 : exact-integer?
value
UC_RISCV_REG_FS5 : exact-integer?
value
UC_RISCV_REG_FS6 : exact-integer?
value
UC_RISCV_REG_FS7 : exact-integer?
value
UC_RISCV_REG_FS8 : exact-integer?
value
UC_RISCV_REG_FS9 : exact-integer?
value
UC_RISCV_REG_FS10 : exact-integer?
value
UC_RISCV_REG_FS11 : exact-integer?
value
UC_RISCV_REG_FT8 : exact-integer?
value
UC_RISCV_REG_FT9 : exact-integer?
value
UC_RISCV_REG_FT10 : exact-integer?
value
UC_RISCV_REG_FT11 : exact-integer?

RISC-V ABI name aliases for floating-point registers. UC_RISCV_REG_FA0 through UC_RISCV_REG_FA7 are floating-point argument registers, UC_RISCV_REG_FS0 through UC_RISCV_REG_FS11 are saved floating-point registers, and UC_RISCV_REG_FT0 through UC_RISCV_REG_FT11 are temporary floating-point registers.

2 Core API🔗ℹ

value
uc-engine : ctype?

An opaque pointer type representing a Unicorn engine instance, corresponding to uc_engine* in the C API.

procedure
(uc-open arch mode) →
exact-integer? uc-engine
arch : exact-integer?
mode : exact-integer?

Creates a new Unicorn emulator instance for the given arch and mode. Returns two values: an error code and a pointer to the engine. Use UC_ERR_OK to check for success.

procedure
(uc-close uc) → exact-integer?
uc : uc-engine

Closes and frees an emulator instance. Returns an error code.

procedure
(uc-mem-map uc address size perms) → exact-integer?
  uc : uc-engine
  address : exact-nonnegative-integer?
  size : exact-nonnegative-integer?
  perms : exact-nonnegative-integer?

Maps a memory region at address with the given size and perms. Returns an error code.

procedure
(uc-mem-write uc address bytes size) → exact-integer?
  uc : uc-engine
  address : exact-nonnegative-integer?
  bytes : bytes?
  size : exact-nonnegative-integer?

Writes bytes to the emulator’s memory at address. Returns an error code.

procedure
(uc-mem-read uc address bytes size) → exact-integer?
  uc : uc-engine
  address : exact-nonnegative-integer?
  bytes : bytes?
  size : exact-nonnegative-integer?

Reads from the emulator’s memory at address into bytes. Returns an error code.

procedure
(uc-reg-write uc regid value) → exact-integer?
  uc : uc-engine
  regid : exact-integer?
  value : cpointer?

Writes a value to a register identified by regid. The value must be a pointer to the data to write. Returns an error code.

procedure
(uc-reg-read uc regid value) → exact-integer?
  uc : uc-engine
  regid : exact-integer?
  value : cpointer?

Reads a value from a register identified by regid into value. Returns an error code.

procedure
(uc-emu-start uc begin until timeout count) → exact-integer?
  uc : uc-engine
  begin : exact-nonnegative-integer?
  until : exact-nonnegative-integer?
  timeout : exact-nonnegative-integer?
  count : exact-nonnegative-integer?

Starts emulation from begin address until until address. timeout specifies duration in microseconds (0 for no limit). count specifies the number of instructions to emulate (0 for no limit). Returns an error code.

procedure
(uc-strerror code) → string?
code : exact-integer?

Returns a human-readable error message for the given error code.

3 Helper Functions🔗ℹ

procedure
(uc-create-arm64) → uc-engine

Creates a new ARM64 emulator instance. Raises an error on failure.

procedure
(uc-create-x64) → uc-engine

Creates a new x86-64 emulator instance. Raises an error on failure.

procedure
(uc-create-riscv32) → uc-engine

Creates a new RISC-V 32-bit emulator instance. Raises an error on failure.

procedure
(uc-create-riscv64) → uc-engine

Creates a new RISC-V 64-bit emulator instance. Raises an error on failure.

procedure
(uc-reg-write-u64 uc regid value) → void?
  uc : uc-engine
  regid : exact-integer?
  value : exact-nonnegative-integer?

Writes an unsigned 64-bit value to a register. Raises an error on failure.

procedure
(uc-reg-write-s64 uc regid value) → void?
  uc : uc-engine
  regid : exact-integer?
  value : exact-integer?

Writes a signed 64-bit value to a register. Raises an error on failure.

procedure
(uc-reg-read-u64 uc regid) → exact-nonnegative-integer?
uc : uc-engine
regid : exact-integer?

Reads an unsigned 64-bit value from a register. Raises an error on failure.

procedure
(uc-reg-write-u32 uc regid value) → void?
  uc : uc-engine
  regid : exact-integer?
  value : exact-nonnegative-integer?

Writes an unsigned 32-bit value to a register. Raises an error on failure.

procedure
(uc-reg-read-u32 uc regid) → exact-nonnegative-integer?
uc : uc-engine
regid : exact-integer?

Reads an unsigned 32-bit value from a register. Raises an error on failure.

procedure
(uc-reg-write-u128 uc regid bytes) → void?
  uc : uc-engine
  regid : exact-integer?
  bytes : bytes?

Writes a 128-bit value to a SIMD register (e.g., V0-V31). bytes must be exactly 16 bytes long. Raises an error on failure.

procedure
(uc-reg-read-u128 uc regid) → bytes?
uc : uc-engine
regid : exact-integer?

Reads a 128-bit value from a SIMD register. Returns a 16-byte bytes value. Raises an error on failure.

procedure
(uc-map-memory uc address size) → void?
  uc : uc-engine
  address : exact-nonnegative-integer?
  size : exact-nonnegative-integer?

Maps a memory region with read-write-execute permissions (UC_PROT_ALL). Raises an error on failure.

procedure
(uc-write-code uc address code-bytes) → void?
  uc : uc-engine
  address : exact-nonnegative-integer?
  code-bytes : bytes?

Writes machine code code-bytes to memory at address. Raises an error on failure.

procedure
(uc-emulate uc start-addr end-addr) → void?
  uc : uc-engine
  start-addr : exact-nonnegative-integer?
  end-addr : exact-nonnegative-integer?

Emulates code from start-addr to end-addr with no timeout and no instruction count limit. Raises an error on failure.