Assembler library for Kotlin
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Kasm

Kasm is a runtime assembler library for Kotlin. It allows to assemble and execute machine code at runtime.

Features

  • x86-64 up to AVX2 (no FPU)
  • Allows save code execution, handling segmentation faults and zero divisions etc.
  • Support for automatic CPU feature detection (see CpuId)
  • Contains a Kotlin DSL (see Assembler)
  • Supports disassembling (through Capstone)
  • Full control over encoding (see EncodingOptions):
    • Encode with or without SIB (if possible)
    • Force REX prefix
    • Use long or short VEX prefix
    • Set unused bits in Mod.RM/REX/VEX
    • Legacy prefix order

Installation

$ git clone --recursive https://github.com/evoasm/kasm

The project does currently come without any build files. It is recommended that you import the project into IntelliJ IDEA.

Requirements

  • Kotlin/JVM
  • Capstone for disassembling (optional).
  • POSIX-compliant OS (Linux and Mac OS X should both work).
  • CMake (see below, optional)

If you want support for code execution and disassembling (through Capstone) you must build the corresponding native modules

$ cd kasm-native/lib
$ mkdir build
$ cd build
$ cmake ..

Shared libraries are output to kasm-native/lib. If you get a UnsatisfiedLinkError exception add -Djava.library.path=../kasm-native/lib to your VM options.

Examples

Assembler

val buffer = NativeBuffer(1024)
  
Assembler(buffer).emitStackFrame {
  mov(RBX, 0)
  mov(RAX, 0)
  divRdxRax(RBX)
}
  
buffer.execute() // will throw kasm.ZeroDivisionException
Assembler(buffer).emitStackFrame {
  mov(RBX, Address(0x0))
}
  
buffer.execute() // will throw kasm.SegmentationFaultException

Instruction

val buffer = NativeBuffer(1024)
  
// add eax, [ebx]
AddR32Rm32.encode(buffer, EAX, Address32(EBX))
  
// add [ebx], eax
AddRmR32.encode(buffer, Address32(EBX), EAX)

CpuId

println(CpuId.features) // [SEP, CLFSH, DS, ACPI, SSE, SSE2, SS, ...

EncodingOptions

AddRm32Imm32.encode(buffer, EAX, 0x10, options = EncodingOptions(rexX = 0x0, forceRex = true))
println(buffer.toByteString()) //40 81 C0 10 00 00 00
  
AddRm32Imm32.encode(buffer, EAX, 0x10, options = EncodingOptions(rexX = 0x1, forceRex = true))
println(buffer.toByteString()) //42 81 C0 10 00 00 00

License

MPL-2.0