Package ghidra.app.plugin.assembler

Interface GenericAssembler<RP extends AssemblyResolvedPatterns>

All Known Subinterfaces:
Assembler
All Known Implementing Classes:
AbstractSleighAssembler, SleighAssembler
public interface GenericAssembler<RP extends AssemblyResolvedPatterns>

  • Method Details

    • getLanguage

      Language getLanguage()
      Get the language of this assembler
      Returns:
      the processor language

    • getProgram

      Program getProgram()
      If the assembler is bound to a program, get that program
      Returns:
      the program, or null

    • 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 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