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 java.lang.Object
implements Assembler

An Assembler for a SleighLanguage. To obtain one of these, please use SleighAssemblerBuilder, or better yet, the static methods of Assemblers.

Field Summary

Fields

Modifier and Type	Field	Description
protected AssemblyContextGraph	ctxGraph
protected static DbgTimer	dbg
static int	DEFAULT_MAX_RECURSION_DEPTH
protected AssemblyDefaultContext	defaultContext
protected SleighLanguage	lang
protected Listing	listing
protected Memory	memory
protected AssemblyParser	parser
protected Program	program
protected AssemblySelector	selector

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, java.lang.String... assembly)	Assemble a sequence of instructions and place them at the given address.
byte[]	assembleLine(Address at, java.lang.String line)	Assemble a line instruction at the given address.
byte[]	assembleLine(Address at, java.lang.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 java.util.Map<java.lang.String,java.lang.Long>	getProgramLabels()	A convenience to obtain a map of program labels strings to long values
java.util.Collection<AssemblyParseResult>	parseLine(java.lang.String line)	Parse a line instruction.
InstructionIterator	patchProgram(byte[] insbytes, Address at)	Place instruction bytes into the bound program.
Instruction	patchProgram(AssemblyResolvedConstructor res, Address at)	Place a resolved (and fully-masked) instruction into the bound program.
AssemblyResolutionResults	resolveLine(Address at, java.lang.String line)	Assemble a line instruction at the given address.
AssemblyResolutionResults	resolveLine(Address at, java.lang.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 Detail

DEFAULT_MAX_RECURSION_DEPTH

public static final int DEFAULT_MAX_RECURSION_DEPTH

See Also:

Constant Field Values

dbg

protected static final DbgTimer dbg

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

Constructor Detail

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 Detail

patchProgram

public Instruction patchProgram(AssemblyResolvedConstructor 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,
                                    java.lang.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,
                           java.lang.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 java.util.Collection<AssemblyParseResult> parseLine(java.lang.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,
                                             java.lang.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,
                                             java.lang.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,
                           java.lang.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

getProgramLabels

protected java.util.Map<java.lang.String,java.lang.Long> getProgramLabels()

A convenience to obtain a map of program labels strings to long values

Returns:

the map TODO Use a Map<String, Address> instead so that, if possible, symbol values can be checked lest they be an invalid substitution for a given operand.

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