Struct Assembler

pub(crate) struct Assembler<R: Relocation, const S: usize> {
    buffer: ArrayVec<u8, S>,
    target: Option<AssemblyOffset>,
    phantom: PhantomData<R>,
}

Available on crate feature compiler and (x86-64 or AArch64) only.

Our own simple replacement for [dynasmrt::Assembler]

The default assembler in [dynasmrt] has a ton of features we don’t need, but more importantly it will panic if it can’t make its memory region executable. This is a no-go for us, since there is a fallback available.

Our needs are simple: a single un-named label, no relocations, and no modification after finalization. However, we do need to handle runtime mmap errors thoroughly.

Fields

buffer: ArrayVec<u8, S>

Temporary fixed capacity buffer for assembling code

target: Option<AssemblyOffset>

Address of the last “target” label, if any

phantom: PhantomData<R>

Relocations are applied immediately and not stored.

Implementations

impl<R: Relocation, const S: usize> Assembler<R, S>

pub(crate) fn entry() -> AssemblyOffset

Return the entry point as an [AssemblyOffset].

pub(crate) fn len(&self) -> usize

Size of the code stored so far, in bytes

pub(crate) fn new() -> Self

Make a new assembler with a temporary buffer but no executable buffer.

pub(crate) fn finalize(&self) -> Result<Executable, CompilerError>

Return a new Executable with the code that’s been written so far.

This may fail if we can’t allocate some memory, fill it, and mark it as executable. For example, a Linux platform with policy to restrict mprotect will show runtime errors at this point.

Performance note: Semantically it makes more sense to consume the Assembler instance here, passing it by value. This can result in a memcpy that doesn’t optimize out, which is a dramatic increase to the memory bandwidth required in compilation. We avoid that extra copy by only passing a reference.

Trait Implementations

impl<R: Clone + Relocation, const S: usize> Clone for Assembler<R, S>

fn clone(&self) -> Assembler<R, S>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<R: Debug + Relocation, const S: usize> Debug for Assembler<R, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R: Relocation, const S: usize> DynasmApi for Assembler<R, S>

fn offset(&self) -> AssemblyOffset

Report the current offset into the assembling target

fn push(&mut self, byte: u8)

Push a byte into the assembling target

fn align(&mut self, _alignment: usize, _with: u8)

Push filler until the assembling target end is aligned to the given alignment.

fn push_i8(&mut self, value: i8)

Push a signed byte into the assembling target

fn push_i16(&mut self, value: i16)

Push a signed word into the assembling target

fn push_i32(&mut self, value: i32)

Push a signed doubleword into the assembling target

fn push_i64(&mut self, value: i64)

Push a signed quadword into the assembling target

fn push_u16(&mut self, value: u16)

Push an usigned word into the assembling target

fn push_u32(&mut self, value: u32)

Push an usigned doubleword into the assembling target

fn push_u64(&mut self, value: u64)

Push an usigned quadword into the assembling target

fn runtime_error(&self, msg: &'static str) -> !

This function is called in when a runtime error has to be generated. It panics.

impl<R: Relocation, const S: usize> DynasmLabelApi for Assembler<R, S>

type Relocation = R

The relocation info type this assembler uses.

fn local_label(&mut self, name: &'static str)

Record the definition of a local label

fn backward_relocation( &mut self, name: &'static str, target_offset: isize, field_offset: u8, ref_offset: u8, kind: R, )

Equivalent of backward_reloc, but takes a non-encoded relocation

fn global_label(&mut self, _name: &'static str)

Record the definition of a global label

fn dynamic_label(&mut self, _id: DynamicLabel)

Record the definition of a dynamic label

fn bare_relocation( &mut self, _target: usize, _field_offset: u8, _ref_offset: u8, _kind: R, )

Equivalent of bare_reloc, but takes a non-encoded relocation

fn global_relocation( &mut self, _name: &'static str, _target_offset: isize, _field_offset: u8, _ref_offset: u8, _kind: R, )

Equivalent of global_reloc, but takes a non-encoded relocation

fn dynamic_relocation( &mut self, _id: DynamicLabel, _target_offset: isize, _field_offset: u8, _ref_offset: u8, _kind: R, )

Equivalent of dynamic_reloc, but takes a non-encoded relocation

fn forward_relocation( &mut self, _name: &'static str, _target_offset: isize, _field_offset: u8, _ref_offset: u8, _kind: R, )

Equivalent of forward_reloc, but takes a non-encoded relocation

fn forward_reloc( &mut self, name: &'static str, target_offset: isize, field_offset: u8, ref_offset: u8, kind: <Self::Relocation as Relocation>::Encoding, )

Record a relocation spot for a forward reference to a local label

fn backward_reloc( &mut self, name: &'static str, target_offset: isize, field_offset: u8, ref_offset: u8, kind: <Self::Relocation as Relocation>::Encoding, )

Record a relocation spot for a backward reference to a local label

fn global_reloc( &mut self, name: &'static str, target_offset: isize, field_offset: u8, ref_offset: u8, kind: <Self::Relocation as Relocation>::Encoding, )

Record a relocation spot for a reference to a global label

fn dynamic_reloc( &mut self, id: DynamicLabel, target_offset: isize, field_offset: u8, ref_offset: u8, kind: <Self::Relocation as Relocation>::Encoding, )

Record a relocation spot for a reference to a dynamic label

fn bare_reloc( &mut self, target: usize, field_offset: u8, ref_offset: u8, kind: <Self::Relocation as Relocation>::Encoding, )

Record a relocation spot to an arbitrary target.

impl<'a, R: Relocation, const S: usize> Extend<&'a u8> for Assembler<R, S>

fn extend<T: IntoIterator<Item = &'a u8>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<R: Relocation, const S: usize> Extend<u8> for Assembler<R, S>

fn extend<T: IntoIterator<Item = u8>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.