Package ghidra.app.plugin.assembler

# Interface Assembler

All Known Implementing Classes:
  `SleighAssembler`

public interface Assembler
The primary interface for performing assembly in Ghidra.

Use the `Assemblers` class to obtain a suitable implementation for a given program or language.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `InstructionIterator`
  `assemble(Address at, String... listing)`
  Assemble a sequence of instructions and place them at the given address.
  `byte[]`
  `assembleLine(Address at, String line)`
  Assemble a line instruction at the given address.
  `byte[]`
  `assembleLine(Address at, String line, AssemblyPatternBlock ctx)`
  Assemble a line instruction at the given address, assuming the given context.
  `AssemblyPatternBlock`
  `getContextAt(Address addr)`
  Get the context at a given address
  `Collection<AssemblyParseResult>`
  `parseLine(String line)`
  Parse a line instruction.
  `InstructionIterator`
  `patchProgram(byte[] insbytes, Address at)`
  Place instruction bytes into the bound program.
  `Instruction`
  `patchProgram(AssemblyResolvedPatterns res, Address at)`
  Place a resolved (and fully-masked) instruction into the bound program.
  `AssemblyResolutionResults`
  `resolveLine(Address at, String line)`
  Assemble a line instruction at the given address.
  `AssemblyResolutionResults`
  `resolveLine(Address at, String line, AssemblyPatternBlock ctx)`
  Assemble a line instruction at the given address, assuming the given context.
  `AssemblyResolutionResults`
  `resolveTree(AssemblyParseResult parse, Address at)`
  Resolve a given parse tree at the given address.
  `AssemblyResolutionResults`
  `resolveTree(AssemblyParseResult parse, Address at, AssemblyPatternBlock ctx)`
  Resolve a given parse tree at the given address, assuming the given context

- ## Method Details

  - ### assemble

    InstructionIterator assemble(Address at, String... listing) throws AssemblySyntaxException, AssemblySemanticException, MemoryAccessException, AddressOverflowException
    Assemble a sequence of instructions and place them at the given address.

    This method is only valid if the assembler is bound to a program. An instance may optionally implement this method without a program binding. In that case, the returned iterator will refer to pseudo instructions.

    NOTE: There must be an active transaction on the bound program for this method to succeed.

    Parameters:
      `at` - the location where the resulting instructions should be placed
      `listing` - a new-line separated or array sequence of instructions
    Returns:
      an iterator over the resulting instructions
    Throws:
      `AssemblySyntaxException` - a textual instruction is non well-formed
      `AssemblySemanticException` - a well-formed instruction cannot be assembled
      `MemoryAccessException` - there is an issue writing the result to program memory
      `AddressOverflowException` - the resulting block is beyond the valid address range

  - ### assembleLine

    byte[] assembleLine(Address at, String line) throws AssemblySyntaxException, AssemblySemanticException
    Assemble a line instruction at the given address.

    This method is valid with or without a bound program. Even if bound, the program is not modified; however, the appropriate context information is taken from the bound program. Without a program, the language's default context is taken at the given location.

    Parameters:
      `at` - the location of the start of the instruction
      `line` - the textual assembly code
    Returns:
      the binary machine code, suitable for placement at the given address
    Throws:
      `AssemblySyntaxException` - the textual instruction is not well-formed
      `AssemblySemanticException` - the the well-formed instruction cannot be assembled

  - ### assembleLine

    byte[] assembleLine(Address at, String line, AssemblyPatternBlock ctx) throws AssemblySemanticException, AssemblySyntaxException
    Assemble a line instruction at the given address, assuming the given context.

    This method works like `assembleLine(Address, String)` except that it allows you to override the assumed context at that location.

    Parameters:
      `at` - the location of the start of the instruction
      `line` - the textual assembly code
      `ctx` - the context register value at the start of the instruction
    Returns:
      the results of semantic resolution (from all parse results)
    Throws:
      `AssemblySyntaxException` - the textual instruction is not well-formed
      `AssemblySemanticException` - the well-formed instruction cannot be assembled

  - ### parseLine

    Collection<AssemblyParseResult> parseLine(String line)
    Parse a line instruction.

    Generally, you should just use `assembleLine(Address, String)`, but if you'd like access to the parse trees outside of an `AssemblySelector`, then this may be an acceptable option. Most notably, this is an excellent way to obtain suggestions for auto-completion.

    Each item in the returned collection is either a complete parse tree, or a syntax error Because all parse paths are attempted, it's possible to get many mixed results. For example, The input line may be a valid instruction; however, there may be suggestions to continue the line toward another valid instruction.

    Parameters:
      `line` - the line (or partial line) to parse
    Returns:
      the results of parsing

  - ### resolveTree

    AssemblyResolutionResults resolveTree(AssemblyParseResult parse, Address at, AssemblyPatternBlock ctx)
    Resolve a given parse tree at the given address, assuming the given context

    Each item in the returned collection is either a completely resolved instruction, or a semantic error. Because all resolutions are attempted, it's possible to get many mixed results.

    NOTE: The resolved instructions are given as masks and values. Where the mask does not cover, you can choose any value.

    Parameters:
      `parse` - a parse result giving a valid tree
      `at` - the location of the start of the instruction
      `ctx` - the context register value at the start of the instruction
    Returns:
      the results of semantic resolution

  - ### resolveTree

    AssemblyResolutionResults resolveTree(AssemblyParseResult parse, Address at)
    Resolve a given parse tree at the given address.

    Each item in the returned collection is either a completely resolved instruction, or a semantic error. Because all resolutions are attempted, it's possible to get many mixed results.

    NOTE: The resolved instructions are given as masks and values. Where the mask does not cover, you can choose any value.

    Parameters:
      `parse` - a parse result giving a valid tree
      `at` - the location of the start of the instruction
    Returns:
      the results of semantic resolution

  - ### resolveLine

    AssemblyResolutionResults resolveLine(Address at, String line) throws AssemblySyntaxException
    Assemble a line instruction at the given address.

    This method works like `resolveLine(Address, String, AssemblyPatternBlock)`, except that it derives the context using `getContextAt(Address)`.

    Parameters:
      `at` - the location of the start of the instruction
      `line` - the textual assembly code
    Returns:
      the collection of semantic resolution results
    Throws:
      `AssemblySyntaxException` - the textual instruction is not well-formed

  - ### resolveLine

    AssemblyResolutionResults resolveLine(Address at, String line, AssemblyPatternBlock ctx) throws AssemblySyntaxException
    Assemble a line instruction at the given address, assuming the given context.

    This method works like `assembleLine(Address, String, AssemblyPatternBlock)`, except that it returns all possible resolutions for the parse trees that pass the `AssemblySelector`.

    Parameters:
      `at` - the location of the start of the instruction
      `line` - the textual assembly code
      `ctx` - the context register value at the start of the instruction
    Returns:
      the collection of semantic resolution results
    Throws:
      `AssemblySyntaxException` - the textual instruction is not well-formed

  - ### patchProgram

    Instruction patchProgram(AssemblyResolvedPatterns res, Address at) throws MemoryAccessException
    Place a resolved (and fully-masked) instruction into the bound program.

    This method is not valid without a program binding. Also, this method must be called during a program database transaction.

    Parameters:
      `res` - the resolved and fully-masked instruction
      `at` - the location of the start of the instruction
    Returns:
      the new `Instruction` code unit
    Throws:
      `MemoryAccessException` - there is an issue writing the result to program memory

  - ### patchProgram

    InstructionIterator patchProgram(byte[] insbytes, Address at) throws MemoryAccessException
    Place instruction bytes into the bound program.

    This method is not valid without a program binding. Also, this method must be called during a program database transaction.

    Parameters:
      `insbytes` - the instruction data
      `at` - the location of the start of the instruction
    Returns:
      an iterator over the disassembled instructions
    Throws:
      `MemoryAccessException` - there is an issue writing the result to program memory

  - ### getContextAt

    AssemblyPatternBlock getContextAt(Address addr)
    Get the context at a given address

    If there is a program binding, this will extract the actual context at the given address. Otherwise, it will obtain the default context at the given address for the language.

    Parameters:
      `addr` - the address
    Returns:
      the context