Machine Code Generation for C++
X86/X64 assembler implementation.
x86::Assembler is a code emitter that emits machine code directly into the CodeBuffer. The assembler is capable of targeting both 32-bit and 64-bit instruction sets, the instruction set can be configured through CodeHolder.
The example should be self-explanatory. It shows how to work with labels, how to use operands, and how to emit instructions that can use different registers based on runtime selection. It implements 32-bit CDECL, WIN64, and SysV64 caling conventions and will work on most X86/X64 environments.
Although functions prologs / epilogs can be implemented manually, AsmJit provides utilities that can be used to create function prologs and epilogs automatically, see Function for more details.
Assembler prefers speed over strictness by default. The implementation checks the type of operands and fails if the signature of types is invalid, however, it does only basic checks regarding registers and their groups used in instructions. It's possible to pass operands that don't form any valid signature to the implementation and succeed. This is usually not a problem as Assembler provides typed API so operand types are normally checked by C++ compiler at compile time, however, Assembler is fully dynamic and its emit() function can be called with any instruction id, options, and operands. Moreover, it's also possible to form instructions that will be accepted by the typed API, for example by calling
mov(x86::eax, x86::al) - the C++ compiler won't see a problem as both EAX and AL are Gp registers.
To help with common mistakes AsmJit allows to activate instruction validation. This feature instruments the Assembler to call InstAPI::validate() before it attempts to encode any instruction.
The example below illustrates how validation can be turned on:
All emitters provide functions to construct machine-size registers depending on the target. This feature is for users that want to write code targeting both 32-bit and 64-bit architectures at the same time. In AsmJit terminology such registers have prefix
z, so for example on X86 architecture the following native registers are provided:
zax- mapped to either
zbx- mapped to either
zcx- mapped to either
zdx- mapped to either
zsp- mapped to either
zbp- mapped to either
zsi- mapped to either
zdi- mapped to either
The example just returns
0, but the function generated contains a standard prolog and epilog sequence and the function itself reserves 32 bytes of local stack. The advantage is clear - a single code-base can handle multiple targets easily. If you want to create a register of native size dynamically by specifying its id it's also possible:
x86::Assembler extends the standard BaseAssembler with X86/X64 specific conventions that are often used by assemblers to embed data next to the code. The following functions can be used to embed data:
The following example illustrates how embed works:
Sometimes it's required to read the data that is embedded after code, for example. This can be done through Label as shown below:
It's also possible to embed labels. In general AsmJit provides the following options:
The following example demonstrates how to embed labels and their differences:
The example below demonstrates how FuncFrame and FuncDetail can be used together with x86::Assembler to generate a function that will use platform dependent calling conventions automatically depending on the target:
This is an advanced topic that is sometimes unavoidable. AsmJit by default appends machine code it generates into a CodeBuffer, however, it also allows to set the offset in CodeBuffer explicitly and to overwrite its content. This technique is extremely dangerous as X86 instructions have variable length (see below), so you should in general only patch code to change instruction's immediate values or some other details not known the at a time the instruction was emitted. A typical scenario that requires code-patching is when you start emitting function and you don't know how much stack you want to reserve for it.
Before we go further it's important to introduce instruction options, because they can help with code-patching (and not only patching, but that will be explained in AVX-512 section):
long_()instruction options to force short or long form, respectively. The most useful is
long_()as it basically forces AsmJit to always emit the longest form. The
short_()is not that useful as it's automatic (except jumps to non-bound labels). Note that the underscore after each function name avoids collision with built-in C++ types.
To illustrate what short form and long form means in binary let's assume we want to emit "add esp, 16" instruction, which has two possible binary encodings:
83C410- This is a short form aka
short add esp, 16- You can see opcode byte (0x8C), MOD/RM byte (0xC4) and an 8-bit immediate value representing
81C410000000- This is a long form aka
long add esp, 16- You can see a different opcode byte (0x81), the same Mod/RM byte (0xC4) and a 32-bit immediate in little-endian representing
It should be obvious that patching an existing instruction into an instruction having a different size may create various problems. So it's recommended to be careful and to only patch instructions into instructions having the same size. The example below demonstrates how instruction options can be used to guarantee the size of an instruction by forcing the assembler to use long-form encoding:
If you run the example it will just work, because both instructions have the same size. As an experiment you can try removing
long_() form to see what happens when wrong code is generated.
In 64-bit mode there is one more thing to worry about when patching code: REX prefix. It's a single byte prefix designed to address registers with ids from 9 to 15 and to override the default width of operation from 32 to 64 bits. AsmJit, like other assemblers, only emits REX prefix when it's necessary. If the patched code only changes the immediate value as shown in the previous example then there is nothing to worry about as it doesn't change the logic behind emitting REX prefix, however, if the patched code changes register id or overrides the operation width then it's important to take care of REX prefix as well.
AsmJit contains another instruction option that controls (forces) REX prefix -
rex(). If you use it the instruction emitted will always use REX prefix even when it's encodable without it. The following list contains some instructions and their binary representations to illustrate when it's emitted:
add esp, 16- 32-bit operation in 64-bit mode doesn't require REX prefix.
rex add esp, 16- 32-bit operation in 64-bit mode with forced REX prefix (0x40).
add rsp, 16- 64-bit operation in 64-bit mode requires REX prefix (0x48).
add r12d, 16- 32-bit operation in 64-bit mode using R12D requires REX prefix (0x41).
add r12, 16- 64-bit operation in 64-bit mode using R12 requires REX prefix (0x49).
X86 architecture is known for its prefixes. AsmJit supports all prefixes that can affect how the instruction is encoded:
It's important to understand that prefixes are part of instruction options. When a member function that involves adding a prefix is called the prefix is combined with existing instruction options, which will affect the next instruction generated.
x86::Assembler can generate AVX512+ code including the use of opmask registers. Opmask can be specified through x86::Assembler::k() function, which stores it as an extra register, which will be used by the next instruction. AsmJit uses such concept for manipulating instruction options as well.
The following AVX512 features are supported:
The following example demonstrates how AVX512 features can be used: