Struct dynasmrt::x86::Assembler

pub struct Assembler { /* fields omitted */ }

This struct is an implementation of a dynasm runtime. It supports incremental compilation as well as multithreaded execution with simultaneous compilation. Its implementation ensures that no memory is writeable and executable at the same time.

Methods

impl Assembler

pub fn new() -> Result<Assembler>

Create a new Assembler instance This function will return an error if it was not able to map the required executable memory. However, further methods on the Assembler will simply panic if an error occurs during memory remapping as otherwise it would violate the invariants of the assembler. This behaviour could be improved but currently the underlying memmap crate does not return the original mappings if a call to mprotect/VirtualProtect fails so there is no reliable way to error out if a call fails while leaving the logic of the Assembler intact.

pub fn new_dynamic_label(&mut self) -> DynamicLabel

Create a new dynamic label that can be referenced and defined.

pub fn get_dynamic_label_offset(
    &self,
    label: DynamicLabel
) -> Option<AssemblyOffset>

Query the offset of a dynamic label.

pub fn alter<F, O>(&mut self, f: F) -> O where
    F: FnOnce(&mut AssemblyModifier) -> O, 

To allow already committed code to be altered, this method allows modification of the internal ExecutableBuffer directly. When this method is called, all data will be committed and access to the internal ExecutableBuffer will be locked. The passed function will then be called with an AssemblyModifier as argument. Using this AssemblyModifier changes can be made to the committed code. After this function returns, any labels in these changes will be resolved and the ExecutableBuffer will be unlocked again.

pub fn alter_uncommitted(&mut self) -> UncommittedModifier

Similar to Assembler::alter, this method allows modification of the yet to be committed assembing buffer. Note that it is not possible to use labels in this context, and overriding labels will cause corruption when the assembler tries to resolve the labels at commit time.

pub fn commit(&mut self)

Commit the assembled code from a temporary buffer to the executable buffer. This method requires write access to the execution buffer and therefore has to obtain a lock on the datastructure. When this method is called, all labels will be resolved, and the result can no longer be changed.

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

Consumes the assembler to return the internal ExecutableBuffer. This method will only fail if an Executor currently holds a lock on the datastructure, in which case it will return itself.

pub fn reader(&self) -> Executor

Creates a read-only reference to the internal ExecutableBuffer that must be locked to access it. Multiple of such read-only locks can be obtained at the same time, but as long as they are alive they will block any self.commit() calls.

Trait Implementations

impl DynasmApi for Assembler

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 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 DynasmLabelApi for Assembler

type Relocation = (u8, u8, u8)

tuple of encoded (offset, size, kind)

fn align(&mut self, alignment: usize)

Push nops until the assembling target end is aligned to the given alignment

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

Record the definition of a global label

fn global_reloc(&mut self, name: &'static str, kind: Self::Relocation)

Record a relocation spot for a reference to a global label

fn dynamic_label(&mut self, id: DynamicLabel)

Record the definition of a dynamic label

fn dynamic_reloc(&mut self, id: DynamicLabel, kind: Self::Relocation)

Record a relocation spot for a reference to a dynamic label

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

Record the definition of a local label

fn forward_reloc(&mut self, name: &'static str, kind: Self::Relocation)

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

fn backward_reloc(&mut self, name: &'static str, kind: Self::Relocation)

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

fn bare_reloc(&mut self, target: usize, kind: Self::Relocation)

Record a relocation spot to an arbitrary target

impl Extend<u8> for Assembler

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

Extends a collection with the contents of an iterator.

impl<'a> Extend<&'a u8> for Assembler

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

Extends a collection with the contents of an iterator.

impl Debug for Assembler

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

Formats the value using the given formatter.