Introduction

AsmJit is a lightweight library for machine code generation written in C++ language. It can generate machine code for x86 and x64 architectures with the support for the whole x86/x64 instruction set - from legacy MMX to the newest AVX512 and AMX. It has a type-safe API that allows C++ compiler to do semantic checks at compile-time even before the assembled code is generated or executed. It also provides an optional register allocator that makes it easy to generate complex code without a significant development effort.

GitHub Projects

AsmJit project, as the name implies, started as a library to allow JIT code generation and execution. However, AsmJit evolved and now contains features that are far beyond the initial scope. AsmJit now consists of multiple projects:

  • AsmJit - AsmJit library, the main project.
  • AsmTK - AsmTK library, toolkit that implements some functionality on top of AsmJit, for example assembler parser.
  • AsmDB - Assembler database in JSON format, used to generate AsmJit tables.

Online Tools

  • AsmGrid - A grid view of assembler instructions (AsmDB) and their latencies (generated by CULT tool).

AsmJit Example

The example below demonstrates how AsmJit separates concepts used during code generation. Check out AsmJit's documentation for more details and examples.

#include <asmjit/asmjit.h>
#include <stdio.h>

using namespace asmjit;

// Signature of the generated function.
typedef int (*Func)(void);

int main(int argc, char* argv[]) {
  JitRuntime rt;                          // Runtime designed for JIT code execution.

  CodeHolder code;                        // Holds code and relocation information.
  code.init(rt.environment());            // Initialize CodeHolder to match JIT environment.

  x86::Assembler a(&code);                // Create and attach x86::Assembler to `code`.
  a.mov(x86::eax, 1);                     // Move one to 'eax' register.
  a.ret();                                // Return from function.
  // ----> x86::Assembler is no longer needed from here and can be destroyed <----

  Func fn;
  Error err = rt.add(&fn, &code);         // Add the generated code to the runtime.
  if (err) return 1;                      // Handle a possible error returned by AsmJit.
  // ----> CodeHolder is no longer needed from here and can be destroyed <----

  int result = fn();                      // Execute the generated code.
  printf("%d\n", result);                 // Print the resulting "1".

  // All classes use RAII, all resources will be released before `main()` returns,
  // the generated function can be, however, released explicitly if you intend to
  // reuse or keep the runtime alive, which you should in a production-ready code.
  rt.release(fn);

  return 0;
}

Use Cases

AsmJit has been used in various projects that required high performance code generation. Most of the time it's about generating specialized functions that implement calculations based on inputs that can change - this also includes scripting languages, recompilers, and machine learning. AsmJit has been the preferred choice for many people and companies because of its size and features.

Highlights

  • Lightweight - 250-300kB compiled binary with all built-in features depending on compiler and optimization level.
  • Modular - Unneeded features can be disabled at compile-time to make the library smaller.
  • Zero dependencies - No external libraries nor STL containers are used, easy to embed and/or link statically.
  • No exceptions & RTTI - AsmJit doesn't use exceptions, but allows to attach a throwable error handler if required.

Key Features

  • Complete X86/X64 instruction set - MMX, SSE+, BMI+, AVX+, FMA+, AVX-512+, AMX, privileged instructions, and other recently added ISA extensions are supported.
  • Dynamic architecture that allows users to construct instructions and operands at runtime - to inspect them, to validate them, and to emit them.
  • Different emitters providing various abstraction levels - Assembler, Builder, and Compiler.
  • Support for sections that can be used to separate code and data or to use separate buffers during code generation.
  • Built-in logging (includes formatting) and user-friendly error handling.
  • JIT memory allocator with malloc-like API for JIT code generation and execution.
  • Compiler can be used to emit large chunks of code with the help of a built-in register allocator.

Open Source Using AsmJit

  • Blend2D - A high performance 2D vector graphics engine written in C++.
  • CULT - A tool that can be used to measure instruction latencies in user-space.
  • FBGEMM - Facebook GEneral Matrix Multiplication library.
  • GZDoom - Doom engine, which uses AsmJit for JIT compilation of ZScript code.
  • MathPresso - Mathematical expression parser and JIT compiler (example of using AsmJit).
  • X64dbg - An open-source x64/x32 debugger for Windows.
  • This is not a complete list, there are many other projects using AsmJit.