Package com.pnfsoftware.jeb.core.units.code.asm.cfg

Class BasicBlock<InsnType extends IInstruction>

java.lang.Object

com.pnfsoftware.jeb.core.units.code.asm.cfg.BasicBlock<InsnType>

Type Parameters:

InsnType -

All Implemented Interfaces:

IBasicBlock<InsnType>, Comparable<BasicBlock<InsnType>>, Iterable<InsnType>

@Ser
public class BasicBlock<InsnType extends IInstruction>
extends Object
implements IBasicBlock<InsnType>, Comparable<BasicBlock<InsnType>>

This class represents a basic block of generic instructions.

See Also:

• CFG

Constructor Summary

Constructors

Constructor	Description
BasicBlock(long base)	Create a new empty basic block.
BasicBlock(long base, List<InsnType> insns, List<Long> dstOffsets, List<Long> irrdstOffsets, boolean unknownDst)	Create a new basic block.

Method Summary

Modifier and Type	Method	Description
void	add(int index, InsnType insn)	DANGEROUS METHOD. Add an instruction into the block.
void	add(InsnType insn)	DANGEROUS METHOD. Append an instruction to the block.
void	addAll(int index, Collection<InsnType> coll)	DANGEROUS METHOD. Add instructions into the block.
void	addAll(Collection<InsnType> coll)	DANGEROUS METHOD. Append instructions to the block.
Iterable<AddressableInstruction<InsnType>>	addressableInstructions()
int	allinsize()	Get the total number of input edges to this block.
int	alloutsize()
boolean	canThrow()
int	compareTo(BasicBlock<InsnType> o)
InsnType	get(int index)	Get the instruction at the specified index.
AddressableInstruction<InsnType>	get2(int index)	Get the instruction at the specified index, in an addressable form.
long	getAddress()
long[]	getAddresses()	Get a list of the addresses of each instruction in the block.
long	getAddressOfInstruction(int index)
List<BasicBlock<InsnType>>	getAllInputBlocks()
Iterable<BasicBlock<InsnType>>	getAllInputs()	Retrieve a read-only iterable of regular and irregular input blocks.
List<BasicBlock<InsnType>>	getAllOutputBlocks()	Get regular and irregular output blocks.
Iterable<BasicBlock<InsnType>>	getAllOutputs()	Retrieve a read-only iterable of regular and irregular output blocks.
long	getBase()	Address of first instruction in the block.
AddressableInstruction<InsnType>	getBranchingInstruction2()	Same as getBranchingInstruction2(true, true).
AddressableInstruction<InsnType>	getBranchingInstruction2(boolean includeBreaking, boolean includeCalling)	Retrieve the branching instruction, if any.
Object	getData(String name)	May return null if the custom object does not exist.
long	getEndAddress()	Address following the last instruction of the block (ie, last exclusive address).
long	getFirstAddress()	Address of first instruction in the block.
int	getIndexOfInstruction(long address)
int	getIndexOfInstruction(InsnType insn)	Locate an instruction in the block.
BasicBlock<InsnType>	getInputBlock(int index)	Get a regular input block.
List<BasicBlock<InsnType>>	getInputBlocks()	Get the regular input blocks.
List<Long>	getInputOffsets()
List<BasicBlock<InsnType>>	getInputs()	Retrieve a read-only list of input blocks (regular).
InsnType	getInstruction(long address)	Get the instruction located at the exact address.
List<InsnType>	getInstructions()	Get a copy of the list of instructions that make up this basic block.
BasicBlock<InsnType>	getIrregularInputBlock(int index)	Get an irregular input block.
List<BasicBlock<InsnType>>	getIrregularInputBlocks()
List<Long>	getIrregularInputOffsets()
List<BasicBlock<InsnType>>	getIrregularInputs()	Retrieve a read-only list of irregular input blocks.
BasicBlock<InsnType>	getIrregularOutputBlock(int index)	Get an irregular output block.
List<BasicBlock<InsnType>>	getIrregularOutputBlocks()	Get irregular output blocks.
List<Long>	getIrregularOutputOffsets()
List<BasicBlock<InsnType>>	getIrregularOutputs()	Retrieve a read-only list of irregular output blocks.
InsnType	getLast()	Get the last instruction of the block.
AddressableInstruction<InsnType>	getLast2()	Get the last instruction of the block, in an addressable form.
long	getLastAddress()	Address of last instruction in the block.
BasicBlock<InsnType>	getOutputBlock(int index)	Get a regular output block.
List<BasicBlock<InsnType>>	getOutputBlocks()	Get the regular output blocks.
List<Long>	getOutputOffsets()
List<BasicBlock<InsnType>>	getOutputs()	Retrieve a read-only list of output blocks (regular).
int	getSizeOfInstructions()
boolean	hasUnknownDst()
int	insize()	Get the number of regular input edges to this block.
int	irrinsize()	Get the number of irregular input edges to this block.
int	irroutsize()
boolean	isEmpty()	Determine if the block has 0 instruction.
boolean	isInfiniteLoop()	Check if the block has a single regular out-edge which points to itself.
boolean	isSelfReferencing()	Check if the block has at least one regular out-edge pointing to itself.
Iterator<InsnType>	iterator()
int	outsize()
boolean	remove(int index)	Remove an instruction from the block as well as associated chains.
boolean	removeData(String name)
InsnType	set(int index, InsnType insn)	DANGEROUS METHOD. Replace an instruction.
void	setData(String name, Object object)	Custom data is reset when a DFA is invalidated.
InsnType	setLast(InsnType insn)
void	setUnknownDst(boolean unknownDst)
BasicBlock<InsnType>	shallowCopy(boolean copyBlockReferences)	Shallow duplication of a basic block.
int	size()	Get the number of instructions in the block.
String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Details

BasicBlock

public BasicBlock(long base)

Create a new empty basic block.

BasicBlock

public BasicBlock(long base,
 List<InsnType> insns,
 List<Long> dstOffsets,
 List<Long> irrdstOffsets,
 boolean unknownDst)

Create a new basic block.

Parameters:

base -

insns -

dstOffsets -

irrdstOffsets -

unknownDst -

Method Details

shallowCopy

public BasicBlock<InsnType> shallowCopy(boolean copyBlockReferences)

Shallow duplication of a basic block. USE THE RESULTING BLOCK WITH CAUTION. - Instructions references are copied
- Block references (edges) are optionally copied (the blocks are not)
- DFA data is not copied

Parameters:

copyBlockReferences -

Returns:

a new block

getBase

public long getBase()

Description copied from interface: IBasicBlock

Address of first instruction in the block.

Specified by:

getBase in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getAddress

public long getAddress()

getFirstAddress

public long getFirstAddress()

Description copied from interface: IBasicBlock

Address of first instruction in the block.

Specified by:

getFirstAddress in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getLastAddress

public long getLastAddress()

Description copied from interface: IBasicBlock

Address of last instruction in the block.

Specified by:

getLastAddress in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getEndAddress

public long getEndAddress()

Description copied from interface: IBasicBlock

Address following the last instruction of the block (ie, last exclusive address).

Specified by:

getEndAddress in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getAddressOfInstruction

public long getAddressOfInstruction(int index)

Specified by:

getAddressOfInstruction in interface IBasicBlock<InsnType extends IInstruction>

getAddresses

public long[] getAddresses()

Get a list of the addresses of each instruction in the block.

Returns:

getIndexOfInstruction

public int getIndexOfInstruction(long address)

Specified by:

getIndexOfInstruction in interface IBasicBlock<InsnType extends IInstruction>

Parameters:

address - instruction address

Returns:

-1 if there is no instruction starting at the provided address

getIndexOfInstruction

public int getIndexOfInstruction(InsnType insn)

Locate an instruction in the block. Comparison is done by identity.

Parameters:

insn -

Returns:

the instruction index, -1 if not found

canThrow

public boolean canThrow()

Specified by:

canThrow in interface IBasicBlock<InsnType extends IInstruction>

size

public int size()

Description copied from interface: IBasicBlock

Get the number of instructions in the block.

Specified by:

size in interface IBasicBlock<InsnType extends IInstruction>

Returns:

isEmpty

public boolean isEmpty()

Description copied from interface: IBasicBlock

Determine if the block has 0 instruction.

Specified by:

isEmpty in interface IBasicBlock<InsnType extends IInstruction>

Returns:

get

public InsnType get(int index)

Description copied from interface: IBasicBlock

Get the instruction at the specified index.

Specified by:

get in interface IBasicBlock<InsnType extends IInstruction>

Returns:

get2

public AddressableInstruction<InsnType> get2(int index)

Get the instruction at the specified index, in an addressable form.

Parameters:

index -

Returns:

getLast

public InsnType getLast()

Get the last instruction of the block.

Keep in mind that a branching instruction may NOT be the last instruction of a basic block if it supports delay-slots.

Specified by:

getLast in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getSizeOfInstructions

public int getSizeOfInstructions()

Specified by:

getSizeOfInstructions in interface IBasicBlock<InsnType extends IInstruction>

getLast2

public AddressableInstruction<InsnType> getLast2()

Get the last instruction of the block, in an addressable form.

Keep in mind that a branching instruction may NOT be the last instruction of a basic block if it supports delay-slots.

Returns:

getInstruction

public InsnType getInstruction(long address)

Description copied from interface: IBasicBlock

Get the instruction located at the exact address.

Specified by:

getInstruction in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getInstructions

public List<InsnType> getInstructions()

Description copied from interface: IBasicBlock

Get a copy of the list of instructions that make up this basic block.

Specified by:

getInstructions in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getBranchingInstruction2

public AddressableInstruction<InsnType> getBranchingInstruction2(boolean includeBreaking,
 boolean includeCalling)

Retrieve the branching instruction, if any. In the general case, it should not be assumed that the branching instruction must be the last instruction of a block. Example: on delay-slot architectures, a number of instructions may follow the branching instructions. They are included in the block. That means that the branching instruction, when there is one, may be the one/two/Nth-before-last.

Parameters:

includeBreaking -

includeCalling -

Returns:

the branching instruction+address, or null if none

getBranchingInstruction2

public AddressableInstruction<InsnType> getBranchingInstruction2()

Same as getBranchingInstruction2(true, true).

remove

public boolean remove(int index)

Remove an instruction from the block as well as associated chains. Usage is not recommended for public clients.

This method may have the nasty side-effect of making the block empty. In that case, it returns true, and it is the caller's responsibility to refresh the CFG at their earliest convenience.

Another issue the client needs to take care of is the removal of the last instruction, which should only happen on very specific conditions, since the trailing instruction typically conditions the out-edges of the block.

Parameters:

index -

Returns:

true if the CFG need refreshing

add

public void add(InsnType insn)

DANGEROUS METHOD. Append an instruction to the block.

The instruction is appended to the block. The edges are not updated.
The caller is responsible for verifying the instruction (no null, no dup., etc.).
The caller is responsible for maintaining the consistency of the block and of the CFG.

Parameters:

insn - the instruction to be appended

add

public void add(int index,
 InsnType insn)

DANGEROUS METHOD. Add an instruction into the block.

Parameters:

index -

insn -

addAll

public void addAll(Collection<InsnType> coll)

DANGEROUS METHOD. Append instructions to the block.

The instructions are appended to the block. The edges are not updated.
The caller is responsible for verifying the instructions (no null, no dup., etc.).
The caller is responsible for maintaining the consistency of the block and of the CFG.

Parameters:

coll -

addAll

public void addAll(int index,
 Collection<InsnType> coll)

DANGEROUS METHOD. Add instructions into the block.

Parameters:

index -

coll -

set

public InsnType set(int index,
 InsnType insn)

DANGEROUS METHOD. Replace an instruction. Sizes must match.

Edges are not updated.
The caller is responsible for maintaining the consistency of the block and of the CFG.

Parameters:

index -

insn - the instruction

Returns:

the instruction that was replaced

setLast

public InsnType setLast(InsnType insn)

insize

public int insize()

Description copied from interface: IBasicBlock

Get the number of regular input edges to this block.

Specified by:

insize in interface IBasicBlock<InsnType extends IInstruction>

Returns:

irrinsize

public int irrinsize()

Description copied from interface: IBasicBlock

Get the number of irregular input edges to this block.

Specified by:

irrinsize in interface IBasicBlock<InsnType extends IInstruction>

Returns:

allinsize

public int allinsize()

Description copied from interface: IBasicBlock

Get the total number of input edges to this block.

Specified by:

allinsize in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getInputBlock

public BasicBlock<InsnType> getInputBlock(int index)

Description copied from interface: IBasicBlock

Get a regular input block.

Specified by:

getInputBlock in interface IBasicBlock<InsnType extends IInstruction>

Parameters:

index - block index

Returns:

a block

getInputBlocks

public List<BasicBlock<InsnType>> getInputBlocks()

Description copied from interface: IBasicBlock

Get the regular input blocks.

Specified by:

getInputBlocks in interface IBasicBlock<InsnType extends IInstruction>

Returns:

a copy of the list of regular input blocks

getIrregularInputBlock

public BasicBlock<InsnType> getIrregularInputBlock(int index)

Description copied from interface: IBasicBlock

Get an irregular input block.

Specified by:

getIrregularInputBlock in interface IBasicBlock<InsnType extends IInstruction>

Parameters:

index - block index

Returns:

a block

getIrregularInputBlocks

public List<BasicBlock<InsnType>> getIrregularInputBlocks()

Specified by:

getIrregularInputBlocks in interface IBasicBlock<InsnType extends IInstruction>

getAllInputBlocks

public List<BasicBlock<InsnType>> getAllInputBlocks()

Specified by:

getAllInputBlocks in interface IBasicBlock<InsnType extends IInstruction>

outsize

public int outsize()

Specified by:

outsize in interface IBasicBlock<InsnType extends IInstruction>

irroutsize

public int irroutsize()

Specified by:

irroutsize in interface IBasicBlock<InsnType extends IInstruction>

alloutsize

public int alloutsize()

Specified by:

alloutsize in interface IBasicBlock<InsnType extends IInstruction>

getOutputBlock

public BasicBlock<InsnType> getOutputBlock(int index)

Description copied from interface: IBasicBlock

Get a regular output block.

Specified by:

getOutputBlock in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getOutputBlocks

public List<BasicBlock<InsnType>> getOutputBlocks()

Description copied from interface: IBasicBlock

Get the regular output blocks.

Specified by:

getOutputBlocks in interface IBasicBlock<InsnType extends IInstruction>

Returns:

a copy of the list of regular output blocks

getOutputOffsets

public List<Long> getOutputOffsets()

getIrregularOutputBlock

public BasicBlock<InsnType> getIrregularOutputBlock(int index)

Description copied from interface: IBasicBlock

Get an irregular output block.

Specified by:

getIrregularOutputBlock in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getIrregularOutputBlocks

public List<BasicBlock<InsnType>> getIrregularOutputBlocks()

Description copied from interface: IBasicBlock

Get irregular output blocks.

Specified by:

getIrregularOutputBlocks in interface IBasicBlock<InsnType extends IInstruction>

Returns:

a copy of the list of irregular output blocks

getIrregularOutputOffsets

public List<Long> getIrregularOutputOffsets()

getAllOutputBlocks

public List<BasicBlock<InsnType>> getAllOutputBlocks()

Description copied from interface: IBasicBlock

Get regular and irregular output blocks.

Specified by:

getAllOutputBlocks in interface IBasicBlock<InsnType extends IInstruction>

Returns:

a copy of the list of all output blocks

getInputs

public List<BasicBlock<InsnType>> getInputs()

Retrieve a read-only list of input blocks (regular).

NOTE: This method is faster than getInputBlocks() since it does not provide a copy of the list.

Specified by:

getInputs in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getInputOffsets

public List<Long> getInputOffsets()

getIrregularInputs

public List<BasicBlock<InsnType>> getIrregularInputs()

Retrieve a read-only list of irregular input blocks.

NOTE: This method is faster than getIrregularInputBlocks() since it does not provide a copy of the list.

Specified by:

getIrregularInputs in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getIrregularInputOffsets

public List<Long> getIrregularInputOffsets()

getOutputs

public List<BasicBlock<InsnType>> getOutputs()

Description copied from interface: IBasicBlock

Retrieve a read-only list of output blocks (regular).

NOTE: This method is faster than IBasicBlock.getOutputBlocks() since it does not provide a copy of the list.

Specified by:

getOutputs in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getIrregularOutputs

public List<BasicBlock<InsnType>> getIrregularOutputs()

Description copied from interface: IBasicBlock

Retrieve a read-only list of irregular output blocks.

NOTE: This method is faster than IBasicBlock.getIrregularOutputBlocks() since it does not provide a copy of the list.

Specified by:

getIrregularOutputs in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getAllInputs

public Iterable<BasicBlock<InsnType>> getAllInputs()

Description copied from interface: IBasicBlock

Retrieve a read-only iterable of regular and irregular input blocks.

NOTE: This method is faster than IBasicBlock.getAllInputBlocks() since it does not provide a copy of the list.

Specified by:

getAllInputs in interface IBasicBlock<InsnType extends IInstruction>

Returns:

getAllOutputs

public Iterable<BasicBlock<InsnType>> getAllOutputs()

Description copied from interface: IBasicBlock

Retrieve a read-only iterable of regular and irregular output blocks.

NOTE: This method is faster than IBasicBlock.getAllOutputBlocks() since it does not provide a copy of the list.

Specified by:

getAllOutputs in interface IBasicBlock<InsnType extends IInstruction>

Returns:

setUnknownDst

public void setUnknownDst(boolean unknownDst)

hasUnknownDst

public boolean hasUnknownDst()

isSelfReferencing

public boolean isSelfReferencing()

Check if the block has at least one regular out-edge pointing to itself.

Returns:

isInfiniteLoop

public boolean isInfiniteLoop()

Check if the block has a single regular out-edge which points to itself.

Returns:

toString

public String toString()

Overrides:

toString in class Object

setData

public void setData(String name,
 Object object)

Custom data is reset when a DFA is invalidated.

getData

public Object getData(String name)

May return null if the custom object does not exist.

removeData

public boolean removeData(String name)

iterator

public Iterator<InsnType> iterator()

Specified by:

iterator in interface Iterable<InsnType extends IInstruction>

addressableInstructions

public Iterable<AddressableInstruction<InsnType>> addressableInstructions()

compareTo

public int compareTo(BasicBlock<InsnType> o)

Specified by:

compareTo in interface Comparable<InsnType extends IInstruction>