Package ghidra.app.plugin.assembler.sleigh

# Class SleighAssembler

java.lang.Object
ghidra.app.plugin.assembler.sleigh.SleighAssembler

All Implemented Interfaces:
  `Assembler`

public class SleighAssembler extends Object implements Assembler
An `Assembler` for a `SleighLanguage`.

For documentation on how the SLEIGH assembler works, see `SleighAssemblerBuilder`. To use the assembler, please use `Assemblers.getAssembler(Program)` or similar.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `SleighAssembler.ListenerForSymbolsRefresh`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected AssemblyContextGraph`
  `ctxGraph`
  `protected static final DbgTimer`
  `dbg`
  `protected AssemblyDefaultContext`
  `defaultContext`
  `protected SleighLanguage`
  `lang`
  `protected Listing`
  `listing`
  `protected final Object`
  `lock`
  `protected Memory`
  `memory`
  `protected AssemblyParser`
  `parser`
  `protected Program`
  `program`
  `protected AssemblySelector`
  `selector`
  `protected AssemblyNumericSymbols`
  `symbols`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `SleighAssembler(AssemblySelector selector, SleighLanguage lang, AssemblyParser parser, AssemblyDefaultContext defaultContext, AssemblyContextGraph ctxGraph)`
  Construct a SleighAssembler.
  `protected`
  `SleighAssembler(AssemblySelector selector, Program program, AssemblyParser parser, AssemblyDefaultContext defaultContext, AssemblyContextGraph ctxGraph)`
  Construct a SleighAssembler.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `InstructionIterator`
  `assemble(Address at, String... assembly)`
  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
  `protected AssemblyNumericSymbols`
  `getNumericSymbols()`
  A convenience to obtain assembly symbols
  `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

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### dbg

    protected static final DbgTimer dbg

  - ### lock

    protected final Object lock

  - ### selector

    protected AssemblySelector selector

  - ### program

    protected Program program

  - ### listing

    protected Listing listing

  - ### memory

    protected Memory memory

  - ### parser

    protected AssemblyParser parser

  - ### defaultContext

    protected AssemblyDefaultContext defaultContext

  - ### ctxGraph

    protected AssemblyContextGraph ctxGraph

  - ### lang

    protected SleighLanguage lang

  - ### symbols

    protected AssemblyNumericSymbols symbols

- ## Constructor Details

  - ### SleighAssembler

    protected SleighAssembler(AssemblySelector selector, Program program, AssemblyParser parser, AssemblyDefaultContext defaultContext, AssemblyContextGraph ctxGraph)
    Construct a SleighAssembler.
    Parameters:
      `selector` - a method of selecting one result from many
      `program` - the program to bind to (must have same language as parser)
      `parser` - the parser for the SLEIGH language
      `defaultContext` - the default context for the language
      `ctxGraph` - the context graph

  - ### SleighAssembler

    protected SleighAssembler(AssemblySelector selector, SleighLanguage lang, AssemblyParser parser, AssemblyDefaultContext defaultContext, AssemblyContextGraph ctxGraph)
    Construct a SleighAssembler.

    NOTE: This variant does not permit `assemble(Address, String...)`.

    Parameters:
      `selector` - a method of selecting one result from many
      `lang` - the SLEIGH language (must be same as to create the parser)
      `parser` - the parser for the SLEIGH language
      `defaultContext` - the default context for the language
      `ctxGraph` - the context graph

- ## Method Details

  - ### patchProgram

    public Instruction patchProgram(AssemblyResolvedPatterns res, Address at) throws MemoryAccessException
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `patchProgram` in interface `Assembler`
    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

    public InstructionIterator patchProgram(byte[] insbytes, Address at) throws MemoryAccessException
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `patchProgram` in interface `Assembler`
    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

  - ### assemble

    public InstructionIterator assemble(Address at, String... assembly) throws AssemblySyntaxException, AssemblySemanticException, MemoryAccessException, AddressOverflowException
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `assemble` in interface `Assembler`
    Parameters:
      `at` - the location where the resulting instructions should be placed
      `assembly` - 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

    public byte[] assembleLine(Address at, String line) throws AssemblySyntaxException, AssemblySemanticException
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `assembleLine` in interface `Assembler`
    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

  - ### parseLine

    public Collection<AssemblyParseResult> parseLine(String line)
    Description copied from interface: `Assembler`
    Parse a line instruction.

    Generally, you should just use `Assembler.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.

    Specified by:
      `parseLine` in interface `Assembler`
    Parameters:
      `line` - the line (or partial line) to parse
    Returns:
      the results of parsing

  - ### resolveTree

    public AssemblyResolutionResults resolveTree(AssemblyParseResult parse, Address at)
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `resolveTree` in interface `Assembler`
    Parameters:
      `parse` - a parse result giving a valid tree
      `at` - the location of the start of the instruction
    Returns:
      the results of semantic resolution

  - ### resolveTree

    public AssemblyResolutionResults resolveTree(AssemblyParseResult parse, Address at, AssemblyPatternBlock ctx)
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `resolveTree` in interface `Assembler`
    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

  - ### resolveLine

    public AssemblyResolutionResults resolveLine(Address at, String line) throws AssemblySyntaxException
    Description copied from interface: `Assembler`
    Assemble a line instruction at the given address.

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

    Specified by:
      `resolveLine` in interface `Assembler`
    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

    public AssemblyResolutionResults resolveLine(Address at, String line, AssemblyPatternBlock ctx) throws AssemblySyntaxException
    Description copied from interface: `Assembler`
    Assemble a line instruction at the given address, assuming the given context.

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

    Specified by:
      `resolveLine` in interface `Assembler`
    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

  - ### assembleLine

    public byte[] assembleLine(Address at, String line, AssemblyPatternBlock ctx) throws AssemblySemanticException, AssemblySyntaxException
    Description copied from interface: `Assembler`
    Assemble a line instruction at the given address, assuming the given context.

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

    Specified by:
      `assembleLine` in interface `Assembler`
    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:
      `AssemblySemanticException` - the well-formed instruction cannot be assembled
      `AssemblySyntaxException` - the textual instruction is not well-formed

  - ### getNumericSymbols

    protected AssemblyNumericSymbols getNumericSymbols()
    A convenience to obtain assembly symbols
    Returns:
      the map

  - ### getContextAt

    public AssemblyPatternBlock getContextAt(Address addr)
    Description copied from interface: `Assembler`
    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.

    Specified by:
      `getContextAt` in interface `Assembler`
    Parameters:
      `addr` - the address
    Returns:
      the context