Nyxstone

https://docs.rs/nyxstone/
Admin
Nyxstone is a Rust library that provides assembly and disassembly capabilities for multiple CPU...
Tokens:6,232
Snippets:41
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### assemble_with

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Assembles assembly instructions at a given start address into bytecode, with additional label definitions.

```APIDOC
## assemble_with

### Description
Assembles assembly instructions at a given start address into bytecode, with additional label definitions.

### Method
Rust method

### Signature
pub fn assemble_with<'iter, It, Lbl>(&self, assembly: &str, address: u64, labels: It) -> anyhow::Result<Vec<u8>>
where
    Lbl: 'iter + AsRef<str>,
    It: IntoIterator<Item = (&'iter Lbl, &'iter u64)>,

### Parameters
- `assembly` (str) - Required - The instructions to assemble.
- `address` (u64) - Required - The start location of the instructions.
- `labels` (It) - Required - Additional label definitions by absolute address, expects a reference to some `Map<AsRef<str>, u64>` which can be iterated over.

### Returns
Ok() and bytecode on success, Err() otherwise.
```

--------------------------------

### Assemble instruction with Nyxstone

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Example usage of Nyxstone: create an instance for the x86_64 architecture with default configuration, assemble an instruction string to a list of Instruction objects, and verify the result. The example uses the ? operator, so it must be called from a function that returns a Result.

```rust
let nyxstone = Nyxstone::new("x86_64", NyxstoneConfig::default())?;

let instructions = nyxstone.assemble_to_instructions("mov rax, rbx", 0x1000)?;

assert_eq!(
     instructions,
     vec![Instruction {
         address: 0x1000,
         assembly: "mov rax, rbx".into(),
         bytes: vec![0x48, 0x89, 0xd8]
     }]
);
```

--------------------------------

### assemble_to_instructions_with

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Translates assembly instructions at a given start address to instruction details containing bytes, with additional label definitions.

```APIDOC
## assemble_to_instructions_with

### Description
Translates assembly instructions at a given start address to instruction details containing bytes, with additional label definitions. Does not support assembly directives that impact the layout (f. i., .section, .org).

### Method
Rust method

### Signature
pub fn assemble_to_instructions_with<'iter, It, Lbl>(
    &self,
    assembly: &str,
    address: u64,
    labels: It,
) -> anyhow::Result<Vec<Instruction>>
where
    Lbl: 'iter + AsRef<str>,
    It: IntoIterator<Item = (&'iter Lbl, &'iter u64)>,

### Parameters
- `assembly` (str) - Required - The instructions to assemble.
- `address` (u64) - Required - The start location of the instructions.
- `labels` (It) - Required - Additional label definitions by absolute address, expects a reference to some `Map<AsRef<str>, u64>` which can be iterated over.

### Returns
Ok() and instruction details on success, Err() otherwise.
```

--------------------------------

### Rust example: Using Nyxstone to assemble an instruction

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Shows how to create a Nyxstone instance for x86_64 and assemble 'mov rax, rbx' at address 0x1000, returning an Instruction with address, assembly, and bytes. Requires the nyxstone crate and anyhow for error handling.

```rust
use std::collections::HashMap;
use nyxstone::{Nyxstone, NyxstoneConfig, Instruction};

fn main() -> anyhow::Result<()> {
    let nyxstone = Nyxstone::new("x86_64", NyxstoneConfig::default())?;

    let instructions = nyxstone.assemble_to_instructions("mov rax, rbx", 0x1000)?;

    assert_eq!(
        instructions,
        vec![Instruction {
            address: 0x1000,
            assembly: "mov rax, rbx".into(),
            bytes: vec![0x48, 0x89, 0xd8]
        }]
    );
    Ok(())
}
```

--------------------------------

### disassemble_to_instructions

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Translates bytes to instruction details containing disassembly text at a given start address.

```APIDOC
## disassemble_to_instructions

### Description
Translates bytes to instruction details containing disassembly text at a given start address.

### Method
Rust method

### Signature
pub fn disassemble_to_instructions(
    &self,
    bytes: &[u8],
    address: u64,
    count: usize,
) -> anyhow::Result<Vec<Instruction>>

### Parameters
- `bytes` (&[u8]) - Required - The bytes to be disassembled.
- `address` (u64) - Required - The start address of the bytes.
- `count` (usize) - Required - Number of instructions to be disassembled. If zero is supplied, all instructions are disassembled.

### Returns
Ok() and Instruction details on success, Err() otherwise.
```

--------------------------------

### disassemble

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Translates bytes to disassembly text at a given start address.

```APIDOC
## disassemble

### Description
Translates bytes to disassembly text at a given start address.

### Method
Rust method

### Signature
pub fn disassemble(&self, bytes: &[u8], address: u64, count: usize) -> anyhow::Result<String>

### Parameters
- `bytes` (&[u8]) - Required - The bytes to be disassembled.
- `address` (u64) - Required - The start address of the bytes.
- `count` (usize) - Required - Number of instructions to be disassembled. If zero is supplied, all instructions are disassembled.

### Returns
Ok() and disassembly text on success, Err() otherwise.
```

--------------------------------

### Nyxstone::assemble_to_instructions

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Translates assembly instructions at a given start address to a vector of Instruction objects, including address, assembly, and bytes.

```APIDOC
## Nyxstone::assemble_to_instructions

### Description
Translates assembly instructions at a given start address to a vector of Instruction objects.

### Method
`pub fn assemble_to_instructions(&self, assembly: &str, address: u64) -> anyhow::Result<Vec<Instruction>>`

### Parameters
- `assembly` (&str) - Required - The instructions to assemble.
- `address` (u64) - Required - The start location of the instructions.

### Returns
- `anyhow::Result<Vec<Instruction>>` - Ok with a vector of Instruction objects on success, Err otherwise.

### Example
```rust
let instructions = nyxstone.assemble_to_instructions("mov rax, rbx", 0x1000)?;
assert_eq!(
    instructions,
    vec![Instruction {
        address: 0x1000,
        assembly: "mov rax, rbx".into(),
        bytes: vec![0x48, 0x89, 0xd8]
    }]
);
```
```

--------------------------------

### Nyxstone::assemble

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Translates assembly instructions at a given start address to bytes. Does not support assembly directives that impact layout.

```APIDOC
## Nyxstone::assemble

### Description
Translates assembly instructions at a given start address to bytes.

### Method
`pub fn assemble(&self, assembly: &str, address: u64) -> anyhow::Result<Vec<u8>>`

### Parameters
- `assembly` (&str) - Required - The instructions to assemble.
- `address` (u64) - Required - The start location of the instructions.

### Returns
- `anyhow::Result<Vec<u8>>` - Ok with the bytecode on success, Err otherwise.

### Notes
Does not support assembly directives that impact the layout (e.g., .section, .org).
```

--------------------------------

### pub fn assemble

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Assembles a string of assembly instructions starting at a given address, returning the resulting bytecode. This method does not support layout-affecting directives.

```APIDOC
## pub fn assemble(&self, assembly: &str, address: u64) -> Result<Vec<u8>>

### Description
Translates assembly instructions at a given start address to bytes.

### Parameters
- **assembly** (`&str`) - Required - The instructions to assemble.
- **address** (`u64`) - Required - The start location of the instructions.

### Returns
`Ok()` and bytecode on success, `Err()` otherwise.

### Note
Does not support assembly directives that impact the layout (e.g., `.section`, `.org`).
```

--------------------------------

### pub fn disassemble

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Disassembles a byte sequence starting at a given address, returning the textual assembly representation. The count parameter controls how many instructions are decoded.

```APIDOC
## pub fn disassemble(&self, bytes: &[u8], address: u64, count: usize) -> Result<String>

### Description
Translates bytes to disassembly text at a given start address.

### Parameters
- **bytes** (`&[u8]`) - Required - The bytes to be disassembled.
- **address** (`u64`) - Required - The start address of the bytes.
- **count** (`usize`) - Required - Number of instructions to be disassembled. If zero is supplied, all instructions are disassembled.

### Returns
`Ok()` and disassembly text on success, `Err()` otherwise.
```

--------------------------------

### pub fn assemble_to_instructions_with

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Assembles assembly instructions with additional label definitions and returns detailed instruction objects. This combines the features of `assemble_with` and `assemble_to_instructions`.

```APIDOC
## pub fn assemble_to_instructions_with<'iter, It, Lbl>(&self, assembly: &str, address: u64, labels: It) -> Result<Vec<Instruction>>
where Lbl: 'iter + AsRef<str>, It: IntoIterator<Item = (&'iter Lbl, &'iter u64)>

### Description
Translates assembly instructions at a given start address to instruction details containing bytes, with additional label definitions.

### Parameters
- **assembly** (`&str`) - Required - The instructions to assemble.
- **address** (`u64`) - Required - The start location of the instructions.
- **labels** (`It`) - Required - Additional label definitions by absolute address, expects a reference to some `Map<AsRef<str>, u64>` which can be iterated over.

### Returns
`Ok()` and instruction details on success, `Err()` otherwise.

### Note
Does not support assembly directives that impact the layout (e.g., `.section`, `.org`).
```

--------------------------------

### pub fn new

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Constructs a new Nyxstone instance with the specified target triple and configuration. This is the entry point for creating an assembler/disassembler instance.

```APIDOC
## pub fn new( target_triple: &str, config: NyxstoneConfig<'_, '_>, ) -> Result<Nyxstone>

### Description
Builds a Nyxstone instance with specific configuration.

### Parameters
- **target_triple** (`&str`) - Required - Llvm target triple or architecture identifier of triple.
- **config** (`NyxstoneConfig<'_, '_>`) - Required - Optional configuration for the `Nyxstone` instance.

### Returns
`Ok()` and the Nyxstone instance on success, `Err()` otherwise.

### Errors
Errors occur when the LLVM triple was not supplied to the builder or LLVM fails.

### Note
For the most common architectures, the following triples are recommended:
- x86_32: `i686-linux-gnu`
- x86_64: `x86_64-linux-gnu`
- armv6m: `armv6m-none-eabi`
- armv7m: `armv7m-none-eabi`
- armv8m: `armv8m.main-none-eabi`
- aarch64: `aarch64-linux-gnueabihf`
Using shorthand identifiers like `arm` can lead to Nyxstone not being able to assemble certain instructions.
```

--------------------------------

### Nyxstone::new

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Builds a Nyxstone instance with a specific target triple and configuration. Returns an error if the LLVM triple is invalid or LLVM fails.

```APIDOC
## Nyxstone::new

### Description
Builds a Nyxstone instance with specific configuration.

### Method
`pub fn new(target_triple: &str, config: NyxstoneConfig) -> anyhow::Result<Nyxstone>`

### Parameters
- `target_triple` (&str) - Required - LLVM target triple or architecture identifier of triple.
- `config` (NyxstoneConfig) - Required - Configuration for the Nyxstone instance.

### Returns
- `anyhow::Result<Nyxstone>` - Ok with the Nyxstone instance on success, Err otherwise.

### Errors
Errors occur when the LLVM triple was not supplied to the builder or LLVM fails.

### Notes
For common architectures, recommended triples include: `i686-linux-gnu`, `x86_64-linux-gnu`, `armv6m-none-eabi`, `armv7m-none-eabi`, `armv8m.main-none-eabi`, `aarch64-linux-gnueabihf`. Using shorthand identifiers like `arm` can lead to assembly failures.
```

--------------------------------

### pub fn assemble_with

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Assembles assembly instructions with additional label definitions, returning the resulting bytecode. This variant allows specifying labels for use in the assembly.

```APIDOC
## pub fn assemble_with<'iter, It, Lbl>(&self, assembly: &str, address: u64, labels: It) -> Result<Vec<u8>>
where Lbl: 'iter + AsRef<str>, It: IntoIterator<Item = (&'iter Lbl, &'iter u64)>

### Description
Translates assembly instructions at a given start address to bytes, with additional label definitions.

### Parameters
- **assembly** (`&str`) - Required - The instructions to assemble.
- **address** (`u64`) - Required - The start location of the instructions.
- **labels** (`It`) - Required - Additional label definitions by absolute address, expects a reference to some `Map<AsRef<str>, u64>` which can be iterated over.

### Returns
`Ok()` and bytecode on success, `Err()` otherwise.

### Note
Does not support assembly directives that impact the layout (e.g., `.section`, `.org`).
```

--------------------------------

### pub fn assemble_to_instructions

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Assembles assembly instructions and returns detailed instruction objects that include the byte representation. This provides more information than the plain bytecode result.

```APIDOC
## pub fn assemble_to_instructions(&self, assembly: &str, address: u64) -> Result<Vec<Instruction>>

### Description
Translates assembly instructions at a given start address to instruction details containing bytes.

### Parameters
- **assembly** (`&str`) - Required - The instructions to assemble.
- **address** (`u64`) - Required - The start location of the instructions.

### Returns
`Ok()` and instruction details on success, `Err()` otherwise.

### Note
Does not support assembly directives that impact the layout (e.g., `.section`, `.org`).
```

--------------------------------

### IntegerBase Enum

Source: https://docs.rs/nyxstone/latest/src/nyxstone/lib.rs.html

Configuration options for the integer style of immediates in disassembly output.

```APIDOC
## IntegerBase Enum

### Description
Configuration options for the integer style of immediates in disassembly output.

### Variants
- `Dec` - Immediates are represented in decimal format.
- `HexPrefix` - Immediates are represented in hex format, prepended with 0x, for example: 0xff.
- `HexSuffix` - Immediates are represented in hex format, suffixed with h, for example: 0ffh.

### Default
`Dec`
```

--------------------------------

### pub fn disassemble_to_instructions

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Disassembles a byte sequence and returns detailed instruction objects containing the disassembly text. This provides more structured information than the plain text result.

```APIDOC
## pub fn disassemble_to_instructions(&self, bytes: &[u8], address: u64, count: usize) -> Result<Vec<Instruction>>

### Description
Translates bytes to instruction details containing disassembly text at a given start address.

### Parameters
- **bytes** (`&[u8]`) - Required - The bytes to be disassembled.
- **address** (`u64`) - Required - The start address of the bytes.
- **count** (`usize`) - Required - Number of instructions to be disassembled. If zero is supplied, all instructions are disassembled.

### Returns
`Ok()` and Instruction details on success, `Err()` otherwise.
```

--------------------------------

### Struct Nyxstone

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

Public interface for calling nyxstone from rust.

```APIDOC
## Struct Nyxstone

### Description
Public interface for calling nyxstone from rust.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Error Handling
N/A
```

--------------------------------

### Nyxstone struct definition

Source: https://docs.rs/nyxstone/latest/nyxstone/struct.Nyxstone.html

The public interface for calling nyxstone from Rust. The struct has private fields, so instances are created via the associated functions like Nyxstone::new.

```rust
pub struct Nyxstone { /* private fields */ }
```
Tokens:
Raw