Table Of Contents



Summary

insertOnEdge adds instrumentation(s) to the Chain in a manner such that the resulting CFG of the program will contain toInsert on an edge that is defined by point_source and point_target.

This API available in Soot’s

Class patchingChain <E extends Unit>

</a>

public void insertOnEdge(E toInsert, E point_src, E point_tgt)
public void insertOnEdge(List<E> toInsert, E point_src, E point_tgt)
public void insertOnEdge(Chain<E> toInsert, E point_src, E point_tgt)

Specified by

insertOnEdge in interface Chain<E extends Unit>

Parameters

  • toInsert - the instrumentation to be added in the Chain
  • point_src - the source point of an edge in CFG
  • point_tgt - the target point of an edge in CFG


Introduction

The insertOnEdge API correctly adds instructions (toInsert) to the target program (Body) on an edge. In a Control Flow Graph, such a directed edge would be represented by a source point (point_src) and a target unit (point_tgt).

Without this API, instrumenting certain edges can prove difficult and time consuming to the user.

Consider the following if condition:

if (x!=40) {    //unit1
  x=40;		//unit2
}
x = x + 2;	//unit3

The control flow graph for the above code is as follows:
CFG

Assume that the user wishes to instrument all three edges with a statement toInsert.

  • Edge 1: Can be instrumented using body.getUnits().insertAfter(toInsert, Unit1)

  • Edge 2: Can be instrumented using body.getUnits().insertBeforeNoRedirect(toInsert, Unit3)

  • Edge 3: ????

None of the APIs previously available enables a user to easily instrument only the false branch (Edge 3). Neither insertBefore unit3 nor insertAfter unit1 will work. Using insertBefore unit3 will cause the instrumentation to be executed no matter which branch the program takes.

This is where insertOnEdge comes in. The 3rd edge can be instrumented by simply using body.getUnits().insertOnEdge(toInsert, Unit1, Unit3);

In fact, insertOnEdge can be used on all three edges. This further reduces the user’s work.

body.getUnits().insertOnEdge(toInsert, Unit1, Unit2);
body.getUnits().insertOnEdge(toInsert, Unit2, Unit3);
body.getUnits().insertOnEdge(toInsert, Unit1, Unit3);


Usage

  • insertOnEdge(toInsert, null, target)
    Doing this is same as performing insertBefore(toInsert, target). All jumps to target is redirected to toInsert

  • insertOnEdge(toInsert, source, null)
    Doing this is same as performing insertAfter(toInsert, source)

  • insertOnEdge(toInsert, source, target)
    This adds an instrumentation in a manner such that the resulting CFG of the program will contain toInsert on an edge that is defined by source and target.
    insertOnEdge will throw RuntimeException if such an edge does not exist in the program’s CFG.

  • insertOnEdge(toInsert, null, null)
    Just don’t do this. insertOnEdge will throw a RuntimeException.



Code

You could read the following code to go into the nitty-gritties of insertOnEdge. (View code on GitHub):



Future Work

  • At the time of writing, this work is tested and known to work on Jimple code. Shimple intermediate representation is not supported.
  • Exception edges cannot be instrumented using this method.


PS: The insertOnEdge feature was added to the Soot repository with this pull request: Feature/insert on edge #583

Have any suggestions or questions that you want answered? Feel free to contact me or use the comment section below.