AsmJit

Low-Latency Machine Code Generation

Docs

Interactive Parser

Support

GitHub

API Reference

Index Class List Build Instructions Breaking Changes Core Assembler Builder Compiler Function Logging Error Handling Instruction DB Virtual Memory Zone Memory Utilities X86 Backend ARM Commons AArch64 Backend

Index

API Reference

AsmJit C++ API reference documentation generated by Doxygen.

AsmJit library uses one global namespace called asmjit, which provides the whole functionality. Core functionality is within asmjit namespace and architecture specific functionality is always in its own namespace. For example asmjit::x86 provides both 32-bit and 64-bit X86 code generation.

Documentation Groups

AsmJit documentation is structured into groups. Groups can be followed in order to learn AsmJit, but knowledge from multiple groups is required to use AsmJit properly:

• Build Instructions - Build instructions, supported environments, and feature selection
• Breaking Changes - Documentation of breaking changes
• Core - Globals, code storage, and emitter interface
• Assembler - Assembler interface and operands
• Builder - Builder interface, nodes, and passes
• Compiler - Compiler interface
• Function - Function definitions
• Logging - Logging and formatting
• Error Handling - Error handling
• Instruction DB - Instruction database (introspection, read/write, validation, ...)
• Virtual Memory - Virtual memory management
• Zone Memory - Zone memory allocator and containers
• Utilities - Utility classes and functions
• X86 Backend - X86/X64 backend
• ARM Commons - ARM commons shared between AArch32 and AArch64
• AArch64 Backend - AArch64 backend

Note

It's important to understand that in order to learn AsmJit all groups are important. Some groups can be omitted if a particular tool is out of interest - for example Assembler users don't need to know about Builder, but it's not the opposite. Builder users should know about Assembler as it also uses operands, labels, and other concepts. Similarly Compiler users should know how both Assembler and Builder tools work.

Where To Start

AsmJit Core provides the following two classes that are essential from the code generation perspective:

• CodeHolder provides functionality to temporarily hold the generated code. It stores all the necessary information about the code - code buffers, sections, labels, symbols, and information about relocations.
• BaseEmitter provides interface used by emitter implementations. The interface provides basic building blocks that are then implemented by BaseAssembler, BaseBuilder, and BaseCompiler.

Code emitters:

• Assembler - provides direct machine code generation.
• Builder - provides intermediate code generation that can be processed before it's serialized to BaseAssembler.
• Compiler - provides high-level code generation with built-in register allocation.
• FuncNode - provides insight into how function looks from the Compiler perspective and how it's stored in a node-list.

Recommendations

The following steps are recommended for all AsmJit users:

• Make sure that you use Logger, see Logging.
• Make sure that you use ErrorHandler, see Error Handling.
• Instruction validation in your debug builds can reveal problems too. AsmJit provides validation at instruction level that can be enabled via BaseEmitter::addDiagnosticOptions(). See DiagnosticOptions for more details.
• If you are a Compiler user, use diagnostic options and read carefully if anything suspicious pops out. Diagnostic options can be enabled via BaseEmitter::addDiagnosticOptions(). If unsure which ones to use, enable annotations and all debug options: DiagnosticOptions::kRAAnnotate | DiagnosticOptions::kRADebugAll.
• Make sure you put a breakpoint into DebugUtils::errored() function if you have a problem with AsmJit returning errors during instruction encoding or register allocation. Having an active breakpoint there can help to reveal the origin of the error, to inspect variables and other conditions that caused it.

The reason for using Logger and ErrorHandler is that they provide a very useful information about what's happening inside emitters. In many cases the information provided by these two is crucial to quickly identify and fix issues that happen during development (for example wrong instruction, address, or register used). In addition, output from Logger is always necessary when filling bug reports. In other words, using logging and proper error handling can save a lot of time during the development and can also save users from submitting issues.

Other Pages

• Class List - List of classes sorted alphabetically
• AsmJit Namespace - List of symbols provided by asmjit namespace

© 2018-2024 AsmJit Authors | GitHub | Chat | Blog

AsmJit and AsmTK libraries are open source software released under the Zlib license and can be used safely in any open-source or commercial product, statically or dynamically linked, and without having to advertise the use of the libraries. Code snippets and examples are released into public domain, see Unlicense for more details.