Expand description
onlineasm! emits runtime assembly using offlineasm mnemonics.
use onlineasm::{onlineasm, Assembler, JitAllocator};
let mut asm = Assembler::native();
let mut jit = JitAllocator::new(Default::default());
onlineasm!(asm;
#[patch = slot] move t0, 0;
ret;
);
// `slot` is the `PatchHandle`, usable after the macro like a `=>` binding.
let code = asm.finish().expect("finish");
let location = code.location(slot).expect("slot is bound");
let mut span = code.allocate(&mut jit).expect("allocate");
// SAFETY: `span` holds `code`, and nothing executes the patched
// instruction while it is rewritten.
unsafe {
onlineasm::repatch_u64(&mut jit, &mut span, &location, 42).expect("repatch");
}Rules:
-
The first argument is the assembler expression (evaluated once). The rest are
;-separated statements. -
.name:defines a local label, referenced as.name.=>namebinds a fresh label at the current position to the Rust variablename. Bindings introduced by=>,extern, and#[patch]are returned from the macro (statement position) so they stay usable afterwards. There are no string label maps. -
Operands: integer literals (decimal/
0x/0o/0b, signed), offlineasm vregs such ast0,ft0, andsp(there is no built-inarg0-arg7. Declare your ownVRegconstant and splice it. A bareargNis a compile error pointing at that), physical registers such asrax,xmm0,x9, andd0, spelled bare or with a%prefix (%rax; unchecked, including reserved and scratch ones -%additionally reaches ABI names with no bare/vreg meaning, such as%sp/%fp/%lron AArch64 and the full psABI name set on RISC-V),.namelabel references,[base + index*scale + disp]memory, and{expr}splices of Rust values (VReg,Gpr,Fpr,Mem,Label, integers). -
#[patch = name]emits the instruction through a patchable site and binds itsPatchHandletoname. Patchable instructions:jmp/callwith a label target (a jump site),movewith a register destination and an immediate source (an immediate site), and conditional branches (a jump site), except float conditions that expand to several branches and the overflow-of-orarithmetic branch (borio/borqo), which emits no branch at all. An external symbol is never a patch site.#[patch]on anything but an instruction is a compile error; a non-patchable mnemonic or operand shape panics at emission, naming the mnemonic. Afterfinish,Finished::locationturns the handle into aPatchLocation: retarget a jump withasmkit::repatch_jump_span, or rewrite an immediate withonlineasm::repatch_u64. -
#[patch_abs = name]onjmp/callwith an integer or{expr}target reserves a 64-bit absolute-address slot: it emits a patchablemoveof the target into the expansion scratch GPR followed by an indirect jump/call through it, and binds themove’sPatchHandle(an immediate site) toname, foronlineasm::repatch_u64to fill in after allocation. The scratch GPR is clobbered. Any other mnemonic, or a target that is neither an integer nor{expr}, is a compile error. -
extern name = {expr};declares the external symbol{expr}(anythingInto<onlineasm::ExternalName>) and binds theonlineasm::Externtoname, which later operands name bare (call name) and the macro returns like a=>binding.extern near name = {expr};declares a direct (near) reference. An operand can also declare one in place:call extern {expr}orcall extern near {expr}. An extern is ajmp/calltarget or the source ofmove/leap/globaladdr/la; the image is then loaded withFinished::load.
External symbols can also be brought in by splicing an address
(move reg, {sym as u64}) or by reserving a #[patch] slot and
repatching it at runtime.
Macros§
- onlineasm
- Emits runtime assembly using offlineasm mnemonics.