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 Detail

      • assemble

        InstructionIterator assemble​(Address at,
                             java.lang.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,
                    java.lang.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

      • parseLine

        java.util.Collection<AssemblyParseResult> parseLine​(java.lang.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

      • patchProgram

        Instruction patchProgram​(AssemblyResolvedConstructor 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