gtirb.cfg module

class gtirb.cfg.CFG(edges=None)

Bases: MutableSet[Edge]

A control-flow graph for an IR. Vertices are CfgNodes, and edges may optionally contain Edge.Labels.

The graph may be viewed simply as a set of Edges. For convenience, the out_edges() and in_edges() methods provide access to the outgoing or incoming edges of individual nodes.

For efficency, only vertices with edges are guaranteed to be stored in this graph. If you want to find all vertices possible (that is, all CfgNodes), use IR.cfg_nodes() instead.

Internally, the graph is stored as a NetworkX instance, which can be accessed using nx(). This allows NetworkX’s large library of graph algorithms to be used on CFGs, if desired.

__contains__(edge)

Return type:

bool

__init__(edges=None)

__iter__()

Return type:

typing.Iterator[gtirb.cfg.Edge]

__len__()

Return type:

int

add(edge)

Add an element.

Return type:

None

clear()

This is slow (creates N new iterators!) but effective.

Return type:

None

deep_eq(other)

Return type:

bool

discard(edge)

Remove an element. Do not raise an exception if absent.

Return type:

None

in_edges(node)

Return type:

typing.Iterator[gtirb.cfg.Edge]

nx()

Return type:

networkx.classes.multidigraph.MultiDiGraph

out_edges(node)

Return type:

typing.Iterator[gtirb.cfg.Edge]

update(edges)

Return type:

None

class gtirb.cfg.Edge(source: CfgNode, target: CfgNode, label: EdgeLabel | None = None)

Bases: NamedTuple

An edge in the CFG from source to target, with optional control-flow details in label.

Variables:

• ~.source – The source CFG node.

• ~.target – The target CFG node.

• ~.label – An optional label containing more control flow information.

Label

alias of EdgeLabel

Type

alias of EdgeType

static __new__(cls, source, target, label=None)

Create new instance of NamedTuple(source, target, label)

Return type:

gtirb.cfg.Edge

__slots__ = ()

class gtirb.cfg.EdgeLabel(type: EdgeType, conditional: bool = False, direct: bool = True)

Bases: tuple

Contains a more detailed description of a gtirb.Edge in the CFG.

Variables:

• ~.conditional – When this edge is part of a conditional branch, conditional is True when the edge represents the control flow taken when the branch’s condition is met, and False when it represents the control flow taken when the branch’s condition is not met. Otherwise, it is always False.

• ~.direct – True if the branch or call is direct, and False if it is indirect. If an edge is indirect, then all outgoing indirect edges represent the set of possible locations the edge may branch to. If there exists an indirect outgoing edge to a gtirb.ProxyBlock without any gtirb.Symbol objects referring to it, then the set of all possible branch locations is unknown.

• ~.type – The type of control flow the gtirb.Edge represents.

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__slots__ = ()

conditional: bool

Alias for field number 1

direct: bool

Alias for field number 2

type: gtirb.cfg.EdgeType

Alias for field number 0

class gtirb.cfg.EdgeType(value)

Bases: Enum

The type of control flow transfer indicated by a gtirb.Edge.

Branch = 0

This edge is the explicit target of a jump instruction. May be conditional or unconditional. If conditional, there will be a corresponding edge of type gtirb.Edge.Type.Fallthrough.

Call = 1

This edge is the explicit target of a call instruction. Unless the function does not return, there will also be a corresponding edge of type gtirb.Edge.Type.Fallthrough.

Fallthrough = 2

This edge represents two blocks executing in sequence. This occurs on the non-branching paths of conditional branch instructions, after call instructons have returned, and when two blocks have no control flow between them, but another gtirb.Edge targets the target block. If there exists a fallthrough edge from block A to block B, then A must immediately precede B in memory.

Return = 3

This edge represents a return from a function, generally via a return instruction. Return edges may either go to a symbolless gtirb.ProxyBlock, which indicates that the set of possible return targets is unknown, or there may be one return edge per return target, which indicates that the set of possible return targets if fully known.

Syscall = 4

This edge is the explicit target of a system call instruction. Unless the function does not return, there will also be a corresponding edge of type gtirb.Edge.Type.Fallthrough. This is the system call equivalent to gtirb.Edge.Type.Call.

Sysret = 5

This edge represents a return from a system call, generally via a return instruction. Return edges may either go to a symbolless gtirb.ProxyBlock, which indicates that the set of possible return targets is unknown, or there may be one return edge per return target, which indicates that the set of possible return targets if fully known. This is the system call equivalent to gtirb.Edge.Type.Return.