public class

CFG

extends Object
implements IControlFlowGraph<InsnType extends IInstruction>
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.code.android.controlflow.CFG<InsnType extends com.pnfsoftware.jeb.core.units.code.ILocatedInstruction>

Class Overview

This class represents a Control Flow Graph for a method, or more generally, any body of code. The CFG can be typed to handle specific instructions.

This class provides basic Data Flow Analysis support. A client can request simple and full du- and ud-chains. Full chains contain more precise cross-block information.

There are two ways to build a CFG:

  • By using the simple #CFG() constructor, and then calling #buildGraph(List, List) with a list of pre-basic blocks.
  • By calling the CFG(List) or CFG(List, List) constructor and passing a flat list of instructions.

This class is to be deprecated and used only by the Android package.

Summary

Public Constructors
CFG(List<BasicBlockBuilder<InsnType>> builders)
Create a CFG using a pre-computed list of partial basic block.
CFG(List<InsnType> insns, List<IrregularFlowData> irrdata)
Create a CFG by recursively parsing a list of instructions.
Public Methods
boolean deleteEdge(BasicBlock<InsnType> x, BasicBlock<InsnType> y)
Delete a regular edge X->Y
Warning! The method throws if duplicate edges x->y are found.
void doDataFlowAnalysis()
Perform data flow analysis on the CFG.
void doDataFlowAnalysis(boolean redo)
Perform data flow analysis on the CFG.
String format(boolean format_addresses, int format_chains, Object context)
Format the CFG into a printable string.
String formatBlockInstruction(InsnType insn)
String formatBlockInstructions(BasicBlock<InsnType> bb)
String formatChains(InsnType insn, ChainType type)
String formatFullChains(InsnType insn, ChainType type)
String formatInstruction(InsnType insn)
String formatInstructions(Collection<InsnType> insns)
Format a list of instructions and their associated full chains.
String formatInstructions()
Format all the instructions (and their full chains) of a CFG into a printable string.
String formatInstructions2()
static <InsnType extends ILocatedInstruction> String formatRegisterToInsnCollection(Map<Integer, Set<InsnType>> m)
List<IrregularFlowData> generateIrregularFlowDataObjects()
(Re-)generate the irregular control flow information present in this CFG.
BasicBlock<InsnType> get(int index)
Retrieve a basic block.
TreeMap<Long, BasicBlock<InsnType>> getAddressBlockMap()
Get a complete map of the basic blocks and their addresses in the CFG.
BasicBlock<InsnType> getBlockAt(long base)
Get the basic block that starts at the provided address or offset.
BasicBlock<InsnType> getBlockContaining(long address)
Get the basic block that contains the provided address.
BasicBlock<InsnType> getBlockFor(InsnType insn)
List<BasicBlock<InsnType>> getBlocks()
Get a copy of the block list of the CFG.
Map<InsnType, Map<Integer, List<Integer>>> getDefUseChains()
Retrieve the simple def-use chains.
BasicBlock<InsnType> getEntryBlock()
Get the entry block.
List<BasicBlock<InsnType>> getExitBlocks()
Get the ordered list of exit blocks.
Map<InsnType, Map<Integer, List<InsnType>>> getFullDefUseChains()
Retrieve the full def-use chains.
Map<InsnType, Map<Integer, List<InsnType>>> getFullUseDefChains()
Retrieve the full use-def chains.
void getGraphRepresentation(List<int[]> edges, List<int[]> irregularEdges)
Get the a graph representation of the CFG.
Map<Integer, Set<InsnType>> getInputMap()
InsnType getInstruction(long address)
Get the instruction located at the exact address.
InsnType getInstructionAt(long address)
int getInstructionCount()
Get the total number of instructions in the CFG.
Couple<BasicBlock<InsnType>, Integer> getInstructionLocation(long address)
TreeMap<Long, InsnType> getInstructionSet()
List<InsnType> getInstructions()
Get the instruction list of this CFG by aggregating each instruction of every block.
BasicBlock<InsnType> getLast()
Map<Integer, Set<InsnType>> getOuputMap()
Map<Integer, Set<InsnType>> getReachMap(BasicBlock<InsnType> b)
Map<Integer, Set<InsnType>> getReachMap(InsnType insn)
Map<InsnType, Map<Integer, List<Integer>>> getUseDefChains()
Retrieve the simple use-def chains.
IVariableInformationProvider getVariableInformationProvider()
boolean hasExit()
Determine if this CFG has exit blocks, that is, blocks without out-edges.
boolean hasNoExit()
Determine if this CFG does not have any exit block.
int reconnectEdge(BasicBlock<InsnType> x, BasicBlock<InsnType> y, BasicBlock<InsnType> z)
This method regularly reconnects a block X from Y to Z.
void removeBlock(BasicBlock<InsnType> b)
Remove a block, and update the fixtures.
void resetDFA()
IVariableInformationProvider setVariableInformationProvider(IVariableInformationProvider prv)
int simplify()
Merge the blocks that can be merged, without changing the flow of the graph.
int simplifyIrregularFlows()
Merge blocks that can be merged, taking into accounts irregular flows.
int size()
Get the number of blocks.
String toString()
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.pnfsoftware.jeb.core.units.code.IControlFlowGraph

Public Constructors

public CFG (List<BasicBlockBuilder<InsnType>> builders)

Create a CFG using a pre-computed list of partial basic block.

public CFG (List<InsnType> insns, List<IrregularFlowData> irrdata)

Create a CFG by recursively parsing a list of instructions.

Parameters
insns list of instructions to be processed
irrdata (optional) irregular flow information, used for exception support

Public Methods

public boolean deleteEdge (BasicBlock<InsnType> x, BasicBlock<InsnType> y)

Delete a regular edge X->Y
Warning! The method throws if duplicate edges x->y are found.

Parameters
x source block
y destination block
Returns
  • true if x->y existed and was deleted

public void doDataFlowAnalysis ()

Perform data flow analysis on the CFG.

Do NOT force a new analysis: Same as doDataFlowAnalysis(false).

public void doDataFlowAnalysis (boolean redo)

Perform data flow analysis on the CFG.

Parameters
redo force a new analysis

public String format (boolean format_addresses, int format_chains, Object context)

Format the CFG into a printable string.

Parameters
format_chains 0=no, 1=simple chains, 2=full chains

public String formatBlockInstruction (InsnType insn)

public String formatBlockInstructions (BasicBlock<InsnType> bb)

public String formatChains (InsnType insn, ChainType type)

public String formatFullChains (InsnType insn, ChainType type)

public String formatInstruction (InsnType insn)

public String formatInstructions (Collection<InsnType> insns)

Format a list of instructions and their associated full chains.

public String formatInstructions ()

Format all the instructions (and their full chains) of a CFG into a printable string.

public String formatInstructions2 ()

public static String formatRegisterToInsnCollection (Map<Integer, Set<InsnType>> m)

public List<IrregularFlowData> generateIrregularFlowDataObjects ()

(Re-)generate the irregular control flow information present in this CFG.

public BasicBlock<InsnType> get (int index)

Retrieve a basic block.

public TreeMap<Long, BasicBlock<InsnType>> getAddressBlockMap ()

Get a complete map of the basic blocks and their addresses in the CFG. This method is recommended for use when multiple, repeated invocations of #getBlockAt(int) are to be made.

Returns
  • a map of address->block

public BasicBlock<InsnType> getBlockAt (long base)

Get the basic block that starts at the provided address or offset.

Parameters
base the block address/offset
Returns
  • basic block, or null if none starts at that address

public BasicBlock<InsnType> getBlockContaining (long address)

Get the basic block that contains the provided address.

Note that the address just needs to be in the block address range; it does not need to point to the beginning of an instruction within the block

Parameters
address an address within the block

public BasicBlock<InsnType> getBlockFor (InsnType insn)

public List<BasicBlock<InsnType>> getBlocks ()

Get a copy of the block list of the CFG. The list is ordered by ascending block address. Modifying the list does not impact the CFG.

Returns
  • a copy of the list of blocks

public Map<InsnType, Map<Integer, List<Integer>>> getDefUseChains ()

Retrieve the simple def-use chains.

public BasicBlock<InsnType> getEntryBlock ()

Get the entry block. The entry block is unique.

Returns
  • never null

public List<BasicBlock<InsnType>> getExitBlocks ()

Get the ordered list of exit blocks. A CFG may have zero or more exit blocks; CFG representing standard routines will have at least one (generally one) exit block.

Returns
  • a collection of blocks, possibly empty

public Map<InsnType, Map<Integer, List<InsnType>>> getFullDefUseChains ()

Retrieve the full def-use chains.
This chain is the only one to have an extra key, set to null, which lists the registers defined 'outside' the routine and used throughout the routine, ie those which should be passed as parameters to the routine.
It is the caller's responsibility to check that these registers are indeed provided as parameters.

public Map<InsnType, Map<Integer, List<InsnType>>> getFullUseDefChains ()

Retrieve the full use-def chains.

public void getGraphRepresentation (List<int[]> edges, List<int[]> irregularEdges)

Get the a graph representation of the CFG. The list of edges return use a 1-based node numbering scheme.

Parameters
edges (output) array of regular edges, eg: {{1,2},{1,3},{2,3}}
irregularEdges (output) array of irregular edges

public Map<Integer, Set<InsnType>> getInputMap ()

public InsnType getInstruction (long address)

Get the instruction located at the exact address.

Returns
  • an instruction, null if none

public InsnType getInstructionAt (long address)

public int getInstructionCount ()

Get the total number of instructions in the CFG. This method sums the number of instructions of each block of the CFG.

public Couple<BasicBlock<InsnType>, Integer> getInstructionLocation (long address)

public TreeMap<Long, InsnType> getInstructionSet ()

public List<InsnType> getInstructions ()

Get the instruction list of this CFG by aggregating each instruction of every block. The list is ordered by ascending address/offset.

public BasicBlock<InsnType> getLast ()

public Map<Integer, Set<InsnType>> getOuputMap ()

public Map<Integer, Set<InsnType>> getReachMap (BasicBlock<InsnType> b)

public Map<Integer, Set<InsnType>> getReachMap (InsnType insn)

public Map<InsnType, Map<Integer, List<Integer>>> getUseDefChains ()

Retrieve the simple use-def chains.

public IVariableInformationProvider getVariableInformationProvider ()

public boolean hasExit ()

Determine if this CFG has exit blocks, that is, blocks without out-edges.

public boolean hasNoExit ()

Determine if this CFG does not have any exit block.

public int reconnectEdge (BasicBlock<InsnType> x, BasicBlock<InsnType> y, BasicBlock<InsnType> z)

This method regularly reconnects a block X from Y to Z. (x->y becomes x->z)
Warning! The method throws if duplicate edges x->y are found.

Parameters
x the original source block
y the original destination block
z the new destination block
Returns
  • +1: success
    0: failure, x->y does not exist
    -1: failure, a edge x->z already exists, and duplicate edges are never allowed

public void removeBlock (BasicBlock<InsnType> b)

Remove a block, and update the fixtures. This method is content-agnostic.

A CFG should never contain empty blocks. However, when the CFG is optimized, instructions are removed, and some nodes might end up empty. This transient, stale state is fine AS LONG AS the client knows what it is doing and removes the empty block as soon as they're done, before passing it down the processing chain. This method removes empty blocks and updates the edges of connected and connecting blocks.

1st caveat: the empty block's out-degree or in-degree MUST be one. (Otherwise, stitching up the edges would not be possible.)

2nd caveat: duplicate edges can be introduced. The client should remove them if it doesn't like that.

3rd caveat: the fixtures update is instruction-agnostic. This means that the client is solely responsible regarding the decision to remove an empty block. For instance, the last instruction of the predecessor block should be checked and the client should make sure that removing the block and updating the fixtures is an operation compatible with the semantics of that last instruction.

Parameters
b block to be removed

public void resetDFA ()

public IVariableInformationProvider setVariableInformationProvider (IVariableInformationProvider prv)

public int simplify ()

Merge the blocks that can be merged, without changing the flow of the graph.
Necessary conditions include: adjacent blocks, first block falls thru the second one, no block shall have irregular outputs, and only the first block may have irregular inputs. or contents of the nodes.

Returns
  • number of mergers

public int simplifyIrregularFlows ()

Merge blocks that can be merged, taking into accounts irregular flows.
A follow through may be merged with a block inside a try (with irregular outedges) if no instruction within the block can raise.

Returns
  • the number of simplifications performed

public int size ()

Get the number of blocks.

public String toString ()