ROSE 0.11.145.192
|
Basic block information.
A basic block is a sequence of distinct instructions with linear control flow from the first instruction to the last. No edges are permitted to enter or leave the basic block except to the first instruction and from the last instruction, respectively. The instructions of a basic block are not required to be contiguous or non-overlapping or at increasing addresses.
In the absense of interrupt handling, the instructions of a basic block are executed entirely. In the absense of multi-threading, no other instructions intervene.
A basic block is a read-only object once it reaches the BB_COMPLETE state, and can thus be shared between partitioners and threads. The memory for these objects is shared and managed by a shared pointer implementation.
A basic block may belong to multiple functions.
Thread safety: Most of this API is not thread safe, however it is possible to call the non-safe functions as long as no other thread is modifying the basic block at the same tme. The functions for querying and modifying the semantic state are thread safe since they're often called from parallel analysis, but no non-safe methods should be called at the same time by other threads.
See also, SgAsmBlock which is how a basic block (and some other things) are represented in the AST.
Definition at line 165 of file BasicBlock.h.
#include <Rose/BinaryAnalysis/Partitioner2/BasicBlock.h>
Public Types | |
typedef Sawyer::SharedPointer< BasicBlock > | Ptr |
Shared pointer to a basic block. | |
using | Successor = BasicBlockSuccessor |
Basic block successor. | |
using | Successors = BasicBlockSuccessors |
All successors in no particular order. | |
Public Types inherited from Sawyer::Attribute::Storage< SyncTag > | |
typedef SynchronizationTraits< SyncTag > | Sync |
Public Member Functions | |
void | copyCache (const BasicBlockPtr &other) |
virtual Ptr | create (rose_addr_t startVa, const PartitionerConstPtr &partitioner) const |
Virtual constructor. | |
void | clearCache () |
Clear all cached data. | |
bool | isFrozen () const |
Determine if basic block is read-only. | |
rose_addr_t | address () const |
Get the address for a basic block. | |
AddressIntervalSet | insnAddresses () const |
Get all instruction addresses. | |
rose_addr_t | fallthroughVa () const |
Get the address after the end of the final instruction. | |
size_t | nInstructions () const |
Get the number of instructions in this block. | |
bool | isEmpty () const |
Return true if this basic block has no instructions. | |
SgAsmInstruction * | instructionExists (rose_addr_t startVa) const |
Determine if this basic block contains an instruction at a specific address. | |
Sawyer::Optional< size_t > | instructionExists (SgAsmInstruction *) const |
Determines if this basic block contains the specified instruction. | |
const std::vector< SgAsmInstruction * > & | instructions () const |
Get the instructions for this block. | |
void | append (const PartitionerConstPtr &, SgAsmInstruction *) |
Append an instruction to a basic block. | |
void | pop () |
Undo the latest append. | |
std::set< rose_addr_t > | explicitConstants () const |
Set of explicit constants. | |
size_t | nDataBlocks () const |
Get the number of data blocks owned. | |
AddressIntervalSet | dataAddresses () const |
Addresses that are part of static data. | |
DataBlockPtr | dataBlockExists (const DataBlockPtr &) const |
Determine if this basic block contains the specified data block or equivalent data block. | |
bool | insertDataBlock (const DataBlockPtr &) |
Make this basic block own the specified data block or equivalent data block. | |
DataBlockPtr | eraseDataBlock (const DataBlockPtr &) |
Remove specified or equivalent data block from this basic block. | |
const std::vector< DataBlockPtr > & | dataBlocks () const |
Data blocks owned. | |
BasicBlockSemantics | semantics () const |
Return information about semantics. | |
void | dropSemantics (const PartitionerConstPtr &) |
Drops semantic information. | |
BasicBlockSemantics | undropSemantics (const PartitionerConstPtr &) |
Undrop semantics. | |
const Sawyer::Cached< std::set< rose_addr_t > > & | ghostSuccessors () const |
Ghost successors. | |
void | clearSuccessors () |
Clear all successor information. | |
const Sawyer::Cached< bool > & | isFunctionCall () const |
Is a function call? | |
void | isFunctionCall (bool flag) const |
const Sawyer::Cached< bool > & | isFunctionReturn () const |
Is a function return? | |
void | isFunctionReturn (bool flag) const |
const Sawyer::Cached< bool > & | mayReturn () const |
May-return property. | |
void | mayReturn (bool flag) const |
const Sawyer::Cached< bool > & | popsStack () const |
Pops stack property. | |
void | popsStack (bool flag) const |
std::string | printableName () const |
A printable name for this basic block. | |
const std::string & | comment () const |
Comment. | |
void | comment (const std::string &s) |
Comment. | |
const SourceLocation & | sourceLocation () const |
Optional location in source code. | |
void | sourceLocation (const SourceLocation &loc) |
Optional location in source code. | |
Sawyer::Optional< size_t > | instructionIndex (rose_addr_t) const |
Position of an instruction. | |
Sawyer::Optional< size_t > | instructionIndex (SgAsmInstruction *) const |
Position of an instruction. | |
const Sawyer::Cached< Successors > & | successors () const |
Control flow successors. | |
void | successors (const Successors &) |
Control flow successors. | |
void | insertSuccessor (const BaseSemantics::SValuePtr &, EdgeType type=E_NORMAL, Confidence confidence=ASSUMED) |
Insert a new successor. | |
void | insertSuccessor (rose_addr_t va, size_t nBits, EdgeType type=E_NORMAL, Confidence confidence=ASSUMED) |
Insert a new successor. | |
Public Member Functions inherited from Sawyer::SharedObject | |
SharedObject () | |
Default constructor. | |
SharedObject (const SharedObject &) | |
Copy constructor. | |
virtual | ~SharedObject () |
Virtual destructor. | |
SharedObject & | operator= (const SharedObject &) |
Assignment. | |
Public Member Functions inherited from Sawyer::Attribute::Storage< SyncTag > | |
Storage () | |
Default constructor. | |
Storage (const Storage &other) | |
Copy constructor. | |
Storage & | operator= (const Storage &other) |
Assignment operator. | |
bool | attributeExists (Id id) const |
Check attribute existence. | |
void | eraseAttribute (Id id) |
Erase an attribute. | |
void | clearAttributes () |
Erase all attributes. | |
template<typename T > | |
void | setAttribute (Id id, const T &value) |
Store an attribute. | |
template<typename T > | |
bool | setAttributeMaybe (Id id, const T &value) |
Store an attribute if not already present. | |
template<typename T > | |
T | getAttribute (Id id) const |
Get an attribute that is known to exist. | |
template<typename T > | |
Sawyer::Optional< T > | getAttributeMaybe (const Id id) const |
Return an attribute if it exists, or else nothing. | |
template<typename T > | |
T | attributeOrElse (Id id, const T &dflt) const |
Return an attribute or a specified value. | |
template<typename T > | |
T | attributeOrDefault (Id id) const |
Return an attribute or a default-constructed value. | |
template<typename T > | |
Sawyer::Optional< T > | optionalAttribute (Id id) const |
Return the attribute as an optional value. | |
size_t | nAttributes () const |
Number of attributes stored. | |
std::vector< Id > | attributeIds () const |
Returns ID numbers for all IDs stored in this container. | |
Static Public Member Functions | |
static Ptr | instance (rose_addr_t startVa, const PartitionerConstPtr &partitioner) |
Static allocating constructor. | |
Protected Member Functions | |
BasicBlock (rose_addr_t startVa, const PartitionerConstPtr &) | |
Shared pointer to a basic block.
Definition at line 168 of file BasicBlock.h.
Basic block successor.
Definition at line 171 of file BasicBlock.h.
All successors in no particular order.
Definition at line 174 of file BasicBlock.h.
|
inlinestatic |
Static allocating constructor.
The startVa
is the starting address for this basic block. The partitioner
is the partitioner on whose behalf this basic block is created. The partitioner is not stored in the basic block, but is only used to initialize certain data members of the block (such as its instruction dispatcher).
Definition at line 238 of file BasicBlock.h.
Referenced by create().
|
inlinevirtual |
Virtual constructor.
The startVa
is the starting address for this basic block. The partitioner
is the partitioner on whose behalf this basic block is created. The partitioner is not stored in the basic block, but is only used to initialize certain data members of the block (such as its instruction dispatcher).
Definition at line 247 of file BasicBlock.h.
References instance().
|
inline |
Clear all cached data.
Thread safety: This method is thread safe.
Definition at line 258 of file BasicBlock.h.
|
inline |
Determine if basic block is read-only.
Returns true if read-only, false otherwise.
Thread safety: This method is thread safe.
Definition at line 272 of file BasicBlock.h.
|
inline |
Comment.
A basic block may have a multi-line, plain-text comment.
Thread safety: This method is not thread safe.
Definition at line 284 of file BasicBlock.h.
|
inline |
Comment.
A basic block may have a multi-line, plain-text comment.
Thread safety: This method is not thread safe.
Definition at line 285 of file BasicBlock.h.
|
inline |
Optional location in source code.
Definition at line 291 of file BasicBlock.h.
|
inline |
Optional location in source code.
Definition at line 292 of file BasicBlock.h.
|
inline |
Get the address for a basic block.
A basic block's address is also the starting address of its initial instruction. The initial instruction need not be the instruction with the lowest address, but rather the instruction which is always executed first by the basic block.
Thread safety: This method is thread-safe.
Definition at line 307 of file BasicBlock.h.
AddressIntervalSet Rose::BinaryAnalysis::Partitioner2::BasicBlock::insnAddresses | ( | ) | const |
Get all instruction addresses.
The return value is the set of all virtual addresses for both instruction starting addresses and the internal addresses of instructions.
Thread safety: This method is not thread safe.
rose_addr_t Rose::BinaryAnalysis::Partitioner2::BasicBlock::fallthroughVa | ( | ) | const |
Get the address after the end of the final instruction.
This is the address that immediately follows the final byte of the instruction that is executed last by the basic block. The final executed instruction need not be the instruction with the highest address.
Thread safety: This method is not thread safe.
|
inline |
Get the number of instructions in this block.
Thread safety: This method is thread safe.
Definition at line 331 of file BasicBlock.h.
|
inline |
Return true if this basic block has no instructions.
A basic block is always expected to have at least one instruction whose address is the same as the basic block's address, and this method returns true if that instruction has not yet been discovered and appended to this basic block. A basic block may also own data blocks, but they are not counted by this method.
Thread safety: This method is thread-safe.
Definition at line 343 of file BasicBlock.h.
SgAsmInstruction * Rose::BinaryAnalysis::Partitioner2::BasicBlock::instructionExists | ( | rose_addr_t | startVa | ) | const |
Determine if this basic block contains an instruction at a specific address.
Returns a non-null instruction pointer if this basic block contains an instruction that starts at the specified address, returns null otherwise.
Thread safety: This method is not thread safe.
Sawyer::Optional< size_t > Rose::BinaryAnalysis::Partitioner2::BasicBlock::instructionExists | ( | SgAsmInstruction * | ) | const |
Determines if this basic block contains the specified instruction.
If the basic block contains the instruction then this method returns the index of this instruction within the block, otherwise it returns nothing.
Thread safety: This method is not thread safe.
Sawyer::Optional< size_t > Rose::BinaryAnalysis::Partitioner2::BasicBlock::instructionIndex | ( | rose_addr_t | ) | const |
Position of an instruction.
Returns the position (index) of the specified instruction within this basic block. If the instruction doesn't exist then returns nothing.
Sawyer::Optional< size_t > Rose::BinaryAnalysis::Partitioner2::BasicBlock::instructionIndex | ( | SgAsmInstruction * | ) | const |
Position of an instruction.
Returns the position (index) of the specified instruction within this basic block. If the instruction doesn't exist then returns nothing.
|
inline |
Get the instructions for this block.
Instructions are returned in the order they would be executed (i.e., the order they were added to the block). Blocks in the undiscovered and not-existing states never have instructions (they return an empty vector); blocks in the incomplete and complete states always return at least one instruction.
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 381 of file BasicBlock.h.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::append | ( | const PartitionerConstPtr & | , |
SgAsmInstruction * | |||
) |
Append an instruction to a basic block.
If this is the first instruction then the instruction address must match the block's starting address, otherwise the new instruction must not already be a member of this basic block. No other attempt is made to verify the integrety of the intra-block control flow (i.e., we do not check that the previous instruction had a single successor which is the newly appended instruction). It is an error to attempt to append to a frozen block.
The partitioner argument is only used for adjusting the instruction semantics framework for the block.
When adding multiple instructions:
Thread safety: This method is not thread safe.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::pop | ( | ) |
Undo the latest append.
An append can be undone so that instructions can be appended, the result checked, and then undone. Only one level of undo is available.
Thread safety: This method is thread safe.
std::set< rose_addr_t > Rose::BinaryAnalysis::Partitioner2::BasicBlock::explicitConstants | ( | ) | const |
Set of explicit constants.
Traverses all the instructions of this basic block and returns all explicit constants found in the instruction operands. Some architectures call these "immediate values".
Thread safety: This method is thread safe.
size_t Rose::BinaryAnalysis::Partitioner2::BasicBlock::nDataBlocks | ( | ) | const |
Get the number of data blocks owned.
Thread safety: This method is thread safe.
AddressIntervalSet Rose::BinaryAnalysis::Partitioner2::BasicBlock::dataAddresses | ( | ) | const |
Addresses that are part of static data.
Returns all addresses that are part of static data.
Thread safety: This method is not thread safe.
DataBlockPtr Rose::BinaryAnalysis::Partitioner2::BasicBlock::dataBlockExists | ( | const DataBlockPtr & | ) | const |
Determine if this basic block contains the specified data block or equivalent data block.
If the basic block owns the specified data block or an equivalent data block then this method returns a pointer to the existing data block, otherwise it returns the null pointer.
Thread safety: This method is not thread safe.
bool Rose::BinaryAnalysis::Partitioner2::BasicBlock::insertDataBlock | ( | const DataBlockPtr & | ) |
Make this basic block own the specified data block or equivalent data block.
If the specified data block is not yet owned by this basic block and the basic block contains no equivalent data block, then the specified data block is added as a member of this basic block and this method returns true. Otherwise, this basic block already contains the specified data block or an equivalent data block and the method returns false. A data block cannot be inserted when this basic block is frozen.
Thread safety: This method is not thread safe.
DataBlockPtr Rose::BinaryAnalysis::Partitioner2::BasicBlock::eraseDataBlock | ( | const DataBlockPtr & | ) |
Remove specified or equivalent data block from this basic block.
If this basic block is in a detached state (i.e., not part of the CFG/AUM) then the specified data block or equivalent data block is removed from this basic block. Returns the data block that was erased, or null if none was erased.
It is an error to invoke this method on basic block that is attached to the CFG/AUM, for which isFrozen returns true. This method is a no-op if the specified data block is a null pointer.
|
inline |
Data blocks owned.
Returned vector is sorted according to data block starting address.
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 467 of file BasicBlock.h.
BasicBlockSemantics Rose::BinaryAnalysis::Partitioner2::BasicBlock::semantics | ( | ) | const |
Return information about semantics.
Although most of the returned information can also be obtained by calling individual accessor functions, this function returns all the information as a single atomic operation.
Thread safety: This method is thread safe.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::dropSemantics | ( | const PartitionerConstPtr & | ) |
Drops semantic information.
This function deletes semantic information for the basic block and can be used to save space. The partitioner can be configured to drop semantic information when a basic block is attached to the CFG. The partitioner is used only for adjusting the instruction semantics framework for the block.
Thread safety: This method is thread safe.
BasicBlockSemantics Rose::BinaryAnalysis::Partitioner2::BasicBlock::undropSemantics | ( | const PartitionerConstPtr & | ) |
Undrop semantics.
This is the inverse of dropSemantics. If semantics have been dropped then they will be recalculated if possible. If semantics have not been dropped then nothing happens. The partitioner is used only for adjusting the instruction semantics framework for the block.
Thread safety: This method is thread safe.
|
inline |
Control flow successors.
The control flow successors indicate how control leaves the end of a basic block. These successors should be the most basic level of information; e.g., a basic block that results in an unconditional function call should not have an edge representing the return from that call. The successors are typically computed in the partitioner and cached in the basic block.
Thread safety: The accessor is not thread safe since it returns a reference; The mutator is thread safe.
Definition at line 516 of file BasicBlock.h.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::successors | ( | const Successors & | ) |
Control flow successors.
The control flow successors indicate how control leaves the end of a basic block. These successors should be the most basic level of information; e.g., a basic block that results in an unconditional function call should not have an edge representing the return from that call. The successors are typically computed in the partitioner and cached in the basic block.
Thread safety: The accessor is not thread safe since it returns a reference; The mutator is thread safe.
|
inline |
Ghost successors.
A ghost successor is a control flow successor that is present in an individual instruction, but not present in the broader scope of a basic block. Ghost successors typically occur when a conditional branch instruction in the middle of a basic block has an opaque predicate, causing it to become an unconditional branch. The return value is the union of the ghost successors for each instruction in the basic block, and is updated whenever the set of instructions in the basic block changes. The ghost successors are typically computed in the partitioner and cached in the basic block.
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 530 of file BasicBlock.h.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::insertSuccessor | ( | const BaseSemantics::SValuePtr & | , |
EdgeType | type = E_NORMAL , |
||
Confidence | confidence = ASSUMED |
||
) |
Insert a new successor.
Inserts a new successor into the cached successor list. If the successor is already present then it is not added again (the comparison uses structural equivalance). Both the expression and the edge type are significant when comparing. For instance, it is permissible to have a function call edge and a call-return edge that both point to the fall-through address.
Thread safety: This method is not thread safe.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::insertSuccessor | ( | rose_addr_t | va, |
size_t | nBits, | ||
EdgeType | type = E_NORMAL , |
||
Confidence | confidence = ASSUMED |
||
) |
Insert a new successor.
Inserts a new successor into the cached successor list. If the successor is already present then it is not added again (the comparison uses structural equivalance). Both the expression and the edge type are significant when comparing. For instance, it is permissible to have a function call edge and a call-return edge that both point to the fall-through address.
Thread safety: This method is not thread safe.
void Rose::BinaryAnalysis::Partitioner2::BasicBlock::clearSuccessors | ( | ) |
Clear all successor information.
Thread safety: This method is thread safe.
|
inline |
Is a function call?
If the basic block appears to be a function call then this property is set to true. A block is a function call if it appears to store a return value on the stack and then unconditionally branch to a function. It need not end with a specific CALL instruction, nor are all CALL instructions actually function calls. This property is typically computed in the partitioner and cached in the basic block.
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 564 of file BasicBlock.h.
|
inline |
Definition at line 565 of file BasicBlock.h.
|
inline |
Is a function return?
This property indicates whether the basic block appears to be a return from a function call. A block is a return from a function call if, after the block is executed, the instruction pointer contains the value stored in memory one past the top of the stack.
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 574 of file BasicBlock.h.
|
inline |
Definition at line 575 of file BasicBlock.h.
|
inline |
May-return property.
This property holds a Boolean that indicates whether a function-return basic block is reachable from this basic block. In other words, if control enters this basic block, might the top stack frame eventually be popped?
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 583 of file BasicBlock.h.
|
inline |
Definition at line 584 of file BasicBlock.h.
|
inline |
Pops stack property.
This property holds a Boolean that indicates whether this basic block is known to have a net stack popping effect.
Thread safety: This method is not thread safe since it returns a reference.
Definition at line 591 of file BasicBlock.h.
|
inline |
Definition at line 592 of file BasicBlock.h.
std::string Rose::BinaryAnalysis::Partitioner2::BasicBlock::printableName | ( | ) | const |
A printable name for this basic block.
Returns a string like 'basic block 0x10001234'.
Thread safety: This method is not thread safe.