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 - instruction type held by this block
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:

  • Constructor Details

    • BasicBlock

      public BasicBlock(long base)
      Create a new empty basic block.
      Parameters:
      base - block base address

    • BasicBlock

      public BasicBlock(long base, List<InsnType> insns, List<Long> dstOffsets, List<Long> irrdstOffsets, boolean unknownDst)
      Create a new basic block.
      Parameters:
      base - block base address
      insns - instructions
      dstOffsets - regular destination offsets
      irrdstOffsets - irregular destination offsets
      unknownDst - true if the block has at least one unknown destination

  • 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 - if true, copy block edge references
      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:
      first instruction address

    • getAddress

      public long getAddress()
      Get the block address.
      Returns:
      block base address

    • 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:
      first instruction address

    • 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:
      last instruction address

    • 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:
      end address

    • getAddressOfInstruction

      public long getAddressOfInstruction(int index)
      Description copied from interface: IBasicBlock
      Get the address of an instruction by index.
      Specified by:
      getAddressOfInstruction in interface IBasicBlock<InsnType extends IInstruction>
      Parameters:
      index - instruction index
      Returns:
      instruction address

    • getAddresses

      public long[] getAddresses()
      Get a list of the addresses of each instruction in the block.
      Returns:
      instruction addresses

    • getIndexOfInstruction

      public int getIndexOfInstruction(long address)
      Description copied from interface: IBasicBlock
      Get the index of an instruction by 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 - instruction to locate
      Returns:
      the instruction index, -1 if not found

    • canThrow

      public boolean canThrow()
      Description copied from interface: IBasicBlock
      Determine whether this block can throw an exception.
      Specified by:
      canThrow in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      true if the block can throw

    • 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:
      instruction count

    • 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:
      true if the block has no instruction

    • 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>
      Parameters:
      index - instruction index
      Returns:
      instruction

    • get2

      public AddressableInstruction<InsnType> get2(int index)
      Get the instruction at the specified index, in an addressable form.
      Parameters:
      index - instruction index
      Returns:
      addressable instruction

    • 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:
      last instruction

    • getSizeOfInstructions

      public int getSizeOfInstructions()
      Description copied from interface: IBasicBlock
      Get the total size of instructions in the block.
      Specified by:
      getSizeOfInstructions in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      instruction size

    • 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:
      last addressable instruction

    • 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>
      Parameters:
      address - instruction address
      Returns:
      instruction, or null

    • 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:
      instruction list

    • 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 - if true, include flow-breaking instructions
      includeCalling - if true, include routine-call instructions
      Returns:
      the branching instruction+address, or null if none

    • getBranchingInstruction2

      public AddressableInstruction<InsnType> getBranchingInstruction2()
      Same as getBranchingInstruction2(true, true).
      Returns:
      the branching instruction and address, or null if none

    • 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 - instruction 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 - insertion index
      insn - instruction to add

    • 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 - instructions to append

    • addAll

      public void addAll(int index, Collection<InsnType> coll)
      DANGEROUS METHOD. Add instructions into the block.
      Parameters:
      index - insertion index
      coll - instructions to add

    • 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 - instruction index
      insn - the instruction
      Returns:
      the instruction that was replaced

    • setLast

      public InsnType setLast(InsnType insn)
      Replace the last instruction.
      Parameters:
      insn - replacement instruction
      Returns:
      previous last instruction

    • 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:
      regular input edge count

    • 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:
      irregular input edge count

    • 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:
      input edge count

    • 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()
      Description copied from interface: IBasicBlock
      Get irregular input blocks.
      Specified by:
      getIrregularInputBlocks in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      a copy of the list of irregular input blocks

    • getAllInputBlocks

      public List<BasicBlock<InsnType>> getAllInputBlocks()
      Description copied from interface: IBasicBlock
      Get regular and irregular input blocks.
      Specified by:
      getAllInputBlocks in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      a copy of the list of all input blocks

    • outsize

      public int outsize()
      Description copied from interface: IBasicBlock
      Get the number of regular output edges from this block.
      Specified by:
      outsize in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      regular output edge count

    • irroutsize

      public int irroutsize()
      Description copied from interface: IBasicBlock
      Get the number of irregular output edges from this block.
      Specified by:
      irroutsize in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      irregular output edge count

    • alloutsize

      public int alloutsize()
      Description copied from interface: IBasicBlock
      Get the total number of output edges from this block.
      Specified by:
      alloutsize in interface IBasicBlock<InsnType extends IInstruction>
      Returns:
      output edge count

    • 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>
      Parameters:
      index - block index
      Returns:
      output block

    • 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()
      Get regular output block addresses.
      Returns:
      regular output offsets

    • 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>
      Parameters:
      index - block index
      Returns:
      irregular output block

    • 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()
      Get irregular output block addresses.
      Returns:
      irregular output offsets

    • 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:
      read-only regular input blocks

    • getInputOffsets

      public List<Long> getInputOffsets()
      Get regular input block addresses.
      Returns:
      regular input offsets

    • 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:
      read-only irregular input blocks

    • getIrregularInputOffsets

      public List<Long> getIrregularInputOffsets()
      Get irregular input block addresses.
      Returns:
      irregular input offsets

    • 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:
      regular output blocks view

    • 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:
      irregular output blocks view

    • 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:
      all input blocks view

    • 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:
      all output blocks view

    • setUnknownDst

      public void setUnknownDst(boolean unknownDst)
      Set whether this block has an unknown destination.
      Parameters:
      unknownDst - true if the block has an unknown destination

    • hasUnknownDst

      public boolean hasUnknownDst()
      Determine whether this block has an unknown destination.
      Returns:
      true if this block has an unknown destination

    • isSelfReferencing

      public boolean isSelfReferencing()
      Check if the block has at least one regular out-edge pointing to itself.
      Returns:
      true if the block has a regular out-edge to itself

    • isInfiniteLoop

      public boolean isInfiniteLoop()
      Check if the block has a single regular out-edge which points to itself.
      Returns:
      true if the block is an infinite loop

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • setData

      public void setData(String name, Object object)
      Set custom data. Custom data is reset when a DFA is invalidated.
      Parameters:
      name - data key
      object - data value

    • getData

      public Object getData(String name)
      Get custom data.
      Parameters:
      name - data key
      Returns:
      data value, or null

    • removeData

      public boolean removeData(String name)
      Remove custom data.
      Parameters:
      name - data key
      Returns:
      true if custom data was removed

    • iterator

      public Iterator<InsnType> iterator()
      Specified by:
      iterator in interface Iterable<InsnType extends IInstruction>

    • addressableInstructions

      public Iterable<AddressableInstruction<InsnType>> addressableInstructions()
      Iterate over addressable instructions.
      Returns:
      addressable instructions

    • compareTo

      public int compareTo(BasicBlock<InsnType> o)
      Specified by:
      compareTo in interface Comparable<InsnType extends IInstruction>