Description

Base class for adjusting basic blocks during discovery.

User-defined basic block callbacks are invoked as each instruction is discovered for a basic block. See Partitioner::discoverBasicBlock for details.

One of the important uses for basic block callbacks is to adjust the control flow successors for a basic block. As each instruction of a basic block is discovered the partitioner calculates its control flow successors to decide what to do. The successors are calculated by evaluating the basic block instructions in a symbolic domain, and if that fails, by looking at the final instruction's concrete successors. Once these successors are obtained, the partitioner invokes user callbacks so that the user has a chance to make adjustments. By time this callback is invoked, the basic block's initial successors have been computed and cached in the basic block. That list can be obtained by invoking Partitioner::basicBlockSuccessors (or similar) or by accessing the BasicBlock::successors cache directly. Likewise, the successor list can be adjusted by invoking methods in the partitioner API or by modifying the cache directly.

Another important use for these callbacks is to tell the partitioner when a basic block is finished. The partitioner has a fairly long list of criteria that it uses as documented in Partitioner::discoverBasicBlock. One of these criteria is to look at the args.results.termination enum returned by the callbacks: if it is TERMINATE_NOW or TERMINATE_PRIOR then the block is forcibly terminated regardless of what would have otherwise happened.

The partitioner expects callbacks to have shared ownership (see Shared ownership) and references them only via Sawyer::SharedPointer. Therefore, subclasses should implement an instance class method that allocates a new object and returns a shared pointer.

Definition at line 39 of file Modules.h.

#include <Rose/BinaryAnalysis/Partitioner2/Modules.h>

Inheritance diagram for Rose::BinaryAnalysis::Partitioner2::BasicBlockCallback:

[legend]

Collaboration diagram for Rose::BinaryAnalysis::Partitioner2::BasicBlockCallback:

[legend]

Classes
struct	Args
	Arguments passed to the callback. More...

struct	Results
	Results coordinated across all callbacks. More...

Public Types
enum	Termination { CONTINUE_DISCOVERY , TERMINATE_NOW , TERMINATE_PRIOR }
	Whether to terminate a basic block. More...

using	Ptr = BasicBlockCallbackPtr
	Shared-ownership pointer to a BasicBlockCallback.

Public Member Functions
virtual bool	operator() (bool chain, const Args &)=0
	Callback method.

Public Member Functions inherited from Sawyer::SharedObject
	SharedObject ()
	Default constructor.

	SharedObject (const SharedObject &)
	Copy constructor.

virtual	~SharedObject ()
	Virtual destructor.

SharedObject &	operator= (const SharedObject &)
	Assignment.

Member Typedef Documentation

◆ Ptr

using Rose::BinaryAnalysis::Partitioner2::BasicBlockCallback::Ptr = BasicBlockCallbackPtr

Shared-ownership pointer to a BasicBlockCallback.

See Shared ownership.

Definition at line 42 of file Modules.h.

Member Enumeration Documentation

◆ Termination

enum Rose::BinaryAnalysis::Partitioner2::BasicBlockCallback::Termination

Whether to terminate a basic block.

Enumerator
CONTINUE_DISCOVERY	Do not explicitly terminate block here.
TERMINATE_NOW	Make current instruction the final instruction of the block.
TERMINATE_PRIOR	Make previous instruction the final instruction of the block.

Definition at line 45 of file Modules.h.

Member Function Documentation

◆ operator()()

virtual bool Rose::BinaryAnalysis::Partitioner2::BasicBlockCallback::operator()	(	bool	chain,
		const Args &
	)

pure virtual

Callback method.

This is the method invoked for the callback. The chain argument is the return value from the previous callback in the list (true for the first callback). The successor callbacks use chain to indicate whether subsequent callbacks should do anything.

The documentation for this class was generated from the following file:

Modules.h