Package ghidra.app.plugin.assembler.sleigh.sem

Class AssemblyResolvedConstructor

java.lang.Object

ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolution

ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolvedConstructor

All Implemented Interfaces:

java.lang.Comparable<AssemblyResolution>

public class AssemblyResolvedConstructor
extends AssemblyResolution

A AssemblyResolution indicating successful application of a constructor This is almost analogous to DisjointPattern, in that is joins an instruction AssemblyPatternBlock with a corresponding context AssemblyPatternBlock. However, this object is mutable, and it collects backfill records, as well as forbidden patterns. When the applied constructor is from the "instruction" subtable, this represents a fully- constructed instruction with required context. All backfill records ought to be resolved and applied before the final result is given to the user, i.e., passed into the AssemblySelector. If at any time during the resolution or backfill process, the result becomes confined to one of the forbidden patterns, it must be dropped, since the encoding will actually invoke a more specific SLEIGH constructor.

Field Summary

Fields

Change	Modifier and Type	Field	Description
NEW	protected com.google.common.collect.ImmutableSet<AssemblyResolvedBackfill>	backfills
NEW	protected AssemblyPatternBlock	ctx
NEW	protected static java.lang.String	CTX
NEW	protected com.google.common.collect.ImmutableSet<AssemblyResolvedConstructor>	forbids
NEW	protected AssemblyPatternBlock	ins
NEW	protected static java.lang.String	INS
NEW	protected static java.util.regex.Pattern	pat
NEW	protected static java.lang.String	SEP

Fields inherited from class ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolution

children, description

Method Summary

Change	Modifier and Type	Method	Description
	AssemblyResolution	backfill(RecursiveDescentSolver solver, java.util.Map<java.lang.String,java.lang.Long> vals)	Apply as many backfill records as possible Each backfill record is resolved in turn, if the record cannot be resolved, it remains listed.
NEW	protected boolean	bitsEqual(AssemblyResolvedConstructor that)	Check if this and another resolution have equal encodings This is like equals(Object), but it ignores backfills records and forbidden patterns.
	AssemblyResolution	checkNotForbidden()	Check if the current encoding is forbidden by one of the attached patterns The pattern become forbidden if this encoding's known bits are an overset of any forbidden pattern's known bits.
NEW	protected java.lang.String	childrenToString(java.lang.String indent)	Get the child portion of AssemblyResolution.toString() If a subclass has another, possible additional, notion of children that it would like to include in AssemblyResolution.toString(), it must override this method.
	AssemblyResolvedConstructor	combine(AssemblyResolvedBackfill bf)	Combine the given backfill record into this resolution
	AssemblyResolvedConstructor	combine(AssemblyResolvedConstructor that)	Combine the encodings and backfills of the given resolution into this one This combines corresponding pattern blocks (assuming they agree), collects backfill records, and collects forbidden patterns.
NEW	protected AssemblyResolvedConstructor	combineLessBackfill(AssemblyResolvedConstructor that, AssemblyResolvedBackfill bf)	Combine a backfill result
NEW	protected int	computeHash()
	AssemblyResolvedConstructor	copyAppendDescription(java.lang.String append)	Duplicate this resolution, with additional description text appended
	java.lang.String	dumpConstructorTree()	Used for testing and diagnostics: list the constructor line numbers used to resolve this encoding This includes braces to describe the tree structure
	boolean	equals(java.lang.Object obj)
	static AssemblyResolvedConstructor	fromString(java.lang.String str, java.lang.String description, com.google.common.collect.ImmutableList<AssemblyResolution> children)	Build a new successful SLEIGH constructor resolution from a string representation This was used primarily in testing, to specify expected results.
	AssemblyPatternBlock	getContext()	Get the context block
	int	getDefinedInstructionLength()	Get the length of the instruction encoding, excluding trailing undefined bytes
	AssemblyPatternBlock	getInstruction()	Get the instruction block
	int	getInstructionLength()	Get the length of the instruction encoding This is used to ensure each operand is encoded at the correct offset
	int	getSpecificity()	Count the number of bits specified in the resolution patterns Totals the specificity of the instruction and context pattern blocks.
	boolean	hasBackfills()	Check if this resolution has pending backfills to apply
	boolean	hasChildren()	Check if this record has children If a subclass has another, possibly additional, notion of children that it would like to include in AssemblyResolution.toString(), it must override this method to return true when such children are present.
	boolean	isBackfill()	Check if this record describes a backfill
	boolean	isError()	Check if this record describes an error
	java.lang.String	lineToString()	Display the resolution result in one line (omitting child details)
	AssemblyResolvedConstructor	maskOut(ContextOp cop)	Set all bits read by a given context operation to unknown
	java.lang.Iterable<byte[]>	possibleInsVals(AssemblyPatternBlock forCtx)	Get an iterable over all the possible fillings of the instruction pattern given a context This is meant to be used idiomatically, as in an enhanced for loop:
	MaskedLong	readContext(int start, int len)	Decode a portion of the context block
	MaskedLong	readContextOp(ContextOp cop)	Decode the value from the context located where the given context operation would write This is used to read the value from the left-hand-side "variable" of a context operation.
	MaskedLong	readInstruction(int start, int len)	Decode a portion of the instruction block
	AssemblyResolvedConstructor	shift(int amt)	Shift the resolved instruction pattern to the right This also shifts any backfill and forbidden pattern records.
	AssemblyResolvedConstructor	solveContextChangesForForbids(AssemblyConstructorSemantic sem, java.util.Map<java.lang.String,java.lang.Long> vals, java.util.Map<java.lang.Integer,java.lang.Object> opvals)	Solve and apply context changes in reverse to forbidden patterns To avoid circumstances where a context change during disassembly would invoke a more specific subconstructor than was used to assembly the instruction, we must solve the forbidden patterns in tandem with the overall resolution.
	AssemblyResolvedConstructor	truncate(int amt)	Truncate (unshift) the resolved instruction pattern from the left
	AssemblyResolvedConstructor	withDescription(java.lang.String desc)	Create a copy of this resolution with a new description
	AssemblyResolvedConstructor	withForbids(java.util.Set<AssemblyResolvedConstructor> more)	Create a new resolution from this one with the given forbidden patterns recorded
	AssemblyResolvedConstructor	writeContextOp(ContextOp cop, MaskedLong val)	Encode the given value into the context block as specified by an operation

Methods inherited from class ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolution

backfill, compareTo, contextOnly, error, error, fromPattern, hashCode, instrOnly, nop, resolved, toString, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INS NEW

protected static final java.lang.String INS

See Also:

Constant Field Values

CTX NEW

protected static final java.lang.String CTX

See Also:

Constant Field Values

SEP NEW

protected static final java.lang.String SEP

See Also:

Constant Field Values

ins NEW

protected final AssemblyPatternBlock ins

ctx NEW

protected final AssemblyPatternBlock ctx

backfills NEW

protected final com.google.common.collect.ImmutableSet<AssemblyResolvedBackfill> backfills

forbids NEW

protected final com.google.common.collect.ImmutableSet<AssemblyResolvedConstructor> forbids

pat NEW

protected static final java.util.regex.Pattern pat

Method Detail

computeHash NEW

protected int computeHash()

Specified by:

computeHash in class AssemblyResolution

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

fromString

public static AssemblyResolvedConstructor fromString(java.lang.String str,
                                                     java.lang.String description,
                                                     com.google.common.collect.ImmutableList<AssemblyResolution> children)

Build a new successful SLEIGH constructor resolution from a string representation This was used primarily in testing, to specify expected results.

Parameters:

str - the string representation: "ins:[pattern],ctx:[pattern]"

description - a description of the resolution

children - any children involved in the resolution

Returns:

the decoded resolution

See Also:

StringUtilities#convertHexStringToMaskedValue(AtomicLong, AtomicLong, String, int, int, String)

shift

public AssemblyResolvedConstructor shift(int amt)

Shift the resolved instruction pattern to the right This also shifts any backfill and forbidden pattern records.

Parameters:

amt - the number of bytes to shift.

Returns:

the result

truncate

public AssemblyResolvedConstructor truncate(int amt)

Truncate (unshift) the resolved instruction pattern from the left

Parameters:

amt - the number of bytes to remove from the left

Returns:

the result

checkNotForbidden

public AssemblyResolution checkNotForbidden()

Check if the current encoding is forbidden by one of the attached patterns The pattern become forbidden if this encoding's known bits are an overset of any forbidden pattern's known bits.

Returns:

false if the pattern is forbidden (and thus in error), true if permitted

bitsEqual NEW

protected boolean bitsEqual(AssemblyResolvedConstructor that)

Check if this and another resolution have equal encodings This is like equals(Object), but it ignores backfills records and forbidden patterns.

Parameters:

that - the other resolution

Returns:

true if both have equal encodings

combine

public AssemblyResolvedConstructor combine(AssemblyResolvedConstructor that)

Combine the encodings and backfills of the given resolution into this one This combines corresponding pattern blocks (assuming they agree), collects backfill records, and collects forbidden patterns.

Parameters:

that - the other resolution

Returns:

the result if successful, or null

combineLessBackfill NEW

protected AssemblyResolvedConstructor combineLessBackfill(AssemblyResolvedConstructor that,
                                                          AssemblyResolvedBackfill bf)

Combine a backfill result

Parameters:

that - the result from backfilling

bf - the resolved backfilled record

Returns:

the result if successful, or null When a backfill is successful, the result should be combined with the owning resolution. In addition, for bookkeeping's sake, the resolved record should be removed from the list of backfills.

combine

public AssemblyResolvedConstructor combine(AssemblyResolvedBackfill bf)

Combine the given backfill record into this resolution

Parameters:

bf - the backfill record

Returns:

the result

withForbids

public AssemblyResolvedConstructor withForbids(java.util.Set<AssemblyResolvedConstructor> more)

Create a new resolution from this one with the given forbidden patterns recorded

Parameters:

more - the additional forbidden patterns to record

Returns:

the new resolution

withDescription

public AssemblyResolvedConstructor withDescription(java.lang.String desc)

Create a copy of this resolution with a new description

Parameters:

desc - the new description

Returns:

the copy

writeContextOp

public AssemblyResolvedConstructor writeContextOp(ContextOp cop,
                                                  MaskedLong val)

Encode the given value into the context block as specified by an operation

Parameters:

cop - the context operation specifying the location of the value to encode

val - the masked value to encode

Returns:

the result This is the forward (as in disassembly) direction of applying context operations. The pattern expression is evaluated, and the result is written as specified.

readContextOp

public MaskedLong readContextOp(ContextOp cop)

Decode the value from the context located where the given context operation would write This is used to read the value from the left-hand-side "variable" of a context operation. It seems backward, because it is. When assembling, the right-hand-side expression of a context operation must be solved. This means the "variable" is known from the context(s) of the resolved children constructors. The value read is then used as the goal in solving the expression.

Parameters:

cop - the context operation whose "variable" to read.

Returns:

the masked result.

copyAppendDescription

public AssemblyResolvedConstructor copyAppendDescription(java.lang.String append)

Duplicate this resolution, with additional description text appended

Parameters:

append - the text to append

Returns:

the duplicate

maskOut

public AssemblyResolvedConstructor maskOut(ContextOp cop)

Set all bits read by a given context operation to unknown

Parameters:

cop - the context operation

Returns:

the result

See Also:

AssemblyPatternBlock.maskOut(ContextOp)

backfill

public AssemblyResolution backfill(RecursiveDescentSolver solver,
                                   java.util.Map<java.lang.String,java.lang.Long> vals)

Apply as many backfill records as possible Each backfill record is resolved in turn, if the record cannot be resolved, it remains listed. If the record can be resolved, but it conflicts, an error record is returned. Each time a record is resolved and combined successfully, all remaining records are tried again. The result is the combined resolved backfills, with only the unresolved backfill records listed.

Parameters:

solver - the solver, usually the same as the original attempt to solve.

vals - the values.

Returns:

the result, or an error.

lineToString

public java.lang.String lineToString()

Description copied from class: AssemblyResolution

Display the resolution result in one line (omitting child details)

Specified by:

lineToString in class AssemblyResolution

Returns:

the display description

hasBackfills

public boolean hasBackfills()

Check if this resolution has pending backfills to apply

Returns:

true if there are backfills

solveContextChangesForForbids

public AssemblyResolvedConstructor solveContextChangesForForbids(AssemblyConstructorSemantic sem,
                                                                 java.util.Map<java.lang.String,java.lang.Long> vals,
                                                                 java.util.Map<java.lang.Integer,java.lang.Object> opvals)

Solve and apply context changes in reverse to forbidden patterns To avoid circumstances where a context change during disassembly would invoke a more specific subconstructor than was used to assembly the instruction, we must solve the forbidden patterns in tandem with the overall resolution. If the context of any forbidden pattern cannot be solved, we simply drop the forbidden pattern -- the lack of a solution implies there is no way the context change could produce the forbidden pattern.

Parameters:

sem - the constructor whose context changes to solve

vals - any defined symbols

opvals - the operand values

Returns:

the result

See Also:

AssemblyConstructorSemantic.solveContextChanges(AssemblyResolvedConstructor, Map, Map)

getInstructionLength

public int getInstructionLength()

Get the length of the instruction encoding This is used to ensure each operand is encoded at the correct offset

Returns:

the length of the instruction block

getDefinedInstructionLength

public int getDefinedInstructionLength()

Get the length of the instruction encoding, excluding trailing undefined bytes

Returns:

the length of the defined bytes in the instruction block

getInstruction

public AssemblyPatternBlock getInstruction()

Get the instruction block

Returns:

the instruction block

getContext

public AssemblyPatternBlock getContext()

Get the context block

Returns:

the context block

readInstruction

public MaskedLong readInstruction(int start,
                                  int len)

Decode a portion of the instruction block

Parameters:

start - the first byte to decode

len - the number of bytes to decode

Returns:

the read masked value

See Also:

AssemblyPatternBlock.readBytes(int, int)

readContext

public MaskedLong readContext(int start,
                              int len)

Decode a portion of the context block

Parameters:

start - the first byte to decode

len - the number of bytes to decode

Returns:

the read masked value

See Also:

AssemblyPatternBlock.readBytes(int, int)

isError

public boolean isError()

Description copied from class: AssemblyResolution

Check if this record describes an error

Specified by:

isError in class AssemblyResolution

Returns:

true if the record is an error

isBackfill

public boolean isBackfill()

Description copied from class: AssemblyResolution

Check if this record describes a backfill

Specified by:

isBackfill in class AssemblyResolution

Returns:

true if the record is a backfill

hasChildren

public boolean hasChildren()

Description copied from class: AssemblyResolution

Check if this record has children If a subclass has another, possibly additional, notion of children that it would like to include in AssemblyResolution.toString(), it must override this method to return true when such children are present.

Overrides:

hasChildren in class AssemblyResolution

Returns:

true if this record has children

See Also:

AssemblyResolution.childrenToString(String)

childrenToString NEW

protected java.lang.String childrenToString(java.lang.String indent)

Description copied from class: AssemblyResolution

Get the child portion of AssemblyResolution.toString() If a subclass has another, possible additional, notion of children that it would like to include in AssemblyResolution.toString(), it must override this method.

Overrides:

childrenToString in class AssemblyResolution

Parameters:

indent - the current indentation

Returns:

the indented description for each child on its own line

See Also:

AssemblyResolution.hasChildren()

dumpConstructorTree

public java.lang.String dumpConstructorTree()

Used for testing and diagnostics: list the constructor line numbers used to resolve this encoding This includes braces to describe the tree structure

Returns:

the constructor tree

See Also:

ConstructState.dumpConstructorTree()

getSpecificity

public int getSpecificity()

Count the number of bits specified in the resolution patterns Totals the specificity of the instruction and context pattern blocks.

Returns:

the number of bits in the resulting patterns

See Also:

AssemblyPatternBlock.getSpecificity()

possibleInsVals

public java.lang.Iterable<byte[]> possibleInsVals(AssemblyPatternBlock forCtx)

Get an iterable over all the possible fillings of the instruction pattern given a context This is meant to be used idiomatically, as in an enhanced for loop:

 
 for (byte[] ins : rcon.possibleInsVals(ctx)) {
     System.out.println(format(ins));
 }
 
 

This is similar to calling getInstruction().AssemblyPatternBlock.possibleVals(), but with forbidden patterns removed. A context is required so that only those forbidden patterns matching the given context are actually removed. This method should always be preferred to the sequence mentioned above, since AssemblyPatternBlock.possibleVals() on its own may yield bytes that do not produce the desired instruction.

Parameters:

forCtx - the context at the assembly address

Returns:

the iterable