Skip to main content

Crate onlineasm_macros

Crate onlineasm_macros 

Source
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. =>name binds a fresh label at the current position to the Rust variable name. 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 as t0, ft0, and sp (there is no built-in arg0-arg7. Declare your own VReg constant and splice it. A bare argN is a compile error pointing at that), physical registers such as rax, xmm0, x9, and d0, 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/%lr on AArch64 and the full psABI name set on RISC-V), .name label 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 its PatchHandle to name. Patchable instructions: jmp/call with a label target (a jump site), move with 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-or arithmetic 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. After finish, Finished::location turns the handle into a PatchLocation: retarget a jump with asmkit::repatch_jump_span, or rewrite an immediate with onlineasm::repatch_u64.

  • #[patch_abs = name] on jmp/call with an integer or {expr} target reserves a 64-bit absolute-address slot: it emits a patchable move of the target into the expansion scratch GPR followed by an indirect jump/call through it, and binds the move’s PatchHandle (an immediate site) to name, for onlineasm::repatch_u64 to 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} (anything Into<onlineasm::ExternalName>) and binds the onlineasm::Extern to name, 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} or call extern near {expr}. An extern is a jmp/call target or the source of move/leap/globaladdr/la; the image is then loaded with Finished::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.