Struct dynasmrt::Assembler

pub struct Assembler<R: Relocation> { /* private fields */ }

A full assembler implementation. Supports labels, all types of relocations, incremental compilation and multithreaded execution with simultaneous compiltion. Its implementation guarantees no memory is executable and writable at the same time.

Implementations

impl<R: Relocation> Assembler<R>

pub fn new() -> Result<Self>

Create a new, empty assembler, with initial allocation size page_size.

pub fn new_dynamic_label(&mut self) -> DynamicLabel

Create a new dynamic label ID

pub fn alter_uncommitted(&mut self) -> UncommittedModifier<'_>

Use an UncommittedModifier to alter uncommitted code. This does not allow the user to change labels/relocations.

pub fn alter<F, O>(&mut self, f: F) -> Result<O, DynasmError> where
    F: FnOnce(&mut Modifier<'_, R>) -> O, 

Use a Modifier to alter committed code directly. While this is happening no code can be executed as the relevant pages are remapped as writable. This API supports defining new labels/relocations, and overwriting previously defined relocations.

pub fn commit(&mut self) -> Result<(), DynasmError>

Commit code, flushing the temporary internal assembling buffer to the mapped executable memory. This makes assembled code available for execution.

pub fn finalize(self) -> Result<ExecutableBuffer, Self>

Finalize this assembler, returning the internal executablebuffer if no Executor instances exist. This panics if any uncommitted changes caused errors near the end. To handle these, call commit() explicitly beforehand.

pub fn reader(&self) -> Executor

Create an executor which can be used to execute code while still assembling code

pub fn labels(&self) -> &LabelRegistry

Provides access to the assemblers internal labels registry

pub fn labels_mut(&mut self) -> &mut LabelRegistry

Provides mutable access to the assemblers internal labels registry

Trait Implementations

impl<R: Debug + Relocation> Debug for Assembler<R>

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

Formats the value using the given formatter.

impl<R: Relocation> DynasmApi for Assembler<R>

fn offset(&self) -> AssemblyOffset

Report the current offset into the assembling target

fn push(&mut self, value: 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> DynasmLabelApi for Assembler<R>

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 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 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 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 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 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> Extend<&'a u8> for Assembler<R>

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

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> Extend<u8> for Assembler<R>

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

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.