gtirb.ir module

The IR is the core class for reading and writing GTIRB files.

You can open a GTIRB Protobuf file and load it into an IR instance:

>>> ir = IR.load_protobuf('filename.gtirb')

And then you can write the IR instance as a Protobuf file:

>>> ir.save_protobuf('filename.gtirb')

class gtirb.ir.IR(*, modules=[], aux_data={}, cfg={}, version=4, uuid=None)

Bases: AuxDataContainer

A complete internal representation consisting of multiple Modules.

Variables:

• ~.modules – A list of Modules contained in the IR.

• ~.cfg – The IR’s control flow graph.

• ~.version – The Protobuf version of this IR.

__init__(*, modules=[], aux_data={}, cfg={}, version=4, uuid=None)

Parameters:

• modules (typing.Iterable[gtirb.module.Module]) – A list of Modules contained in the IR.

• cfg (typing.Iterable[gtirb.cfg.Edge]) – A set of Edges representing the IR’s control flow graph. Defaults to being empty.

• aux_data (typing.Union[typing.Mapping[str, gtirb.auxdata.AuxData], typing.Iterable[typing.Tuple[str, gtirb.auxdata.AuxData]]]) – The initial auxiliary data to be associated with the object, as a mapping from names to gtirb.AuxData. Defaults to being empty.

• version (int) – The Protobuf version of this IR.

• uuid (typing.Optional[uuid.UUID]) – The UUID of this IR, or None if a new UUID needs generated via uuid.uuid4(). Defaults to None.

property byte_blocks: Iterator[ByteBlock]

The ByteBlocks in this IR.

byte_blocks_at(addrs)

Finds all the byte blocks that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.ByteBlock]

byte_blocks_on(addrs)

Finds all the byte blocks that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.ByteBlock]

property byte_intervals: Iterator[ByteInterval]

The ByteIntervals in this IR.

byte_intervals_at(addrs)

Finds all the byte intervals that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.byteinterval.ByteInterval]

byte_intervals_on(addrs)

Finds all the byte intervals that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.byteinterval.ByteInterval]

property cfg_nodes: Iterator[CfgNode]

The CfgNodes in this IR.

property code_blocks: Iterator[CodeBlock]

The CodeBlocks in this IR.

code_blocks_at(addrs)

Finds all the code blocks that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.CodeBlock]

code_blocks_on(addrs)

Finds all the code blocks that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.CodeBlock]

property data_blocks: Iterator[DataBlock]

The DataBlocks in this IR.

data_blocks_at(addrs)

Finds all the data blocks that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.DataBlock]

data_blocks_on(addrs)

Finds all the data blocks that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.block.DataBlock]

deep_eq(other)

This overrides gtirb.Node.deep_eq() to check for AuxData equality.

Because the values stored by AuxData are not necessarily amenable to deep checking, the auxiliary data dictionaries stored for self and other are not deeply checked. Instead, they are considered to be equal if their sets of keys are equal.

Return type:

bool

get_by_uuid(uuid)

Look up a node by its UUID.

This method will find any node currently attached to this IR. It will not find any nodes attached to other IRs, or not attached to any IR.

Parameters:

uuid (uuid.UUID) – The UUID to look up.

Return type:

typing.Optional[gtirb.node.Node]

Returns:

The Node this UUID corresponds to, or None if no node exists with that UUID.

static load_protobuf(file_name)

Load IR from a Protobuf file at the specified path.

Parameters:

file_name – The path to the Protobuf file.

Returns:

A Python GTIRB IR object.

static load_protobuf_file(protobuf_file)

Load IR from a Protobuf object.

Use this function when you have a Protobuf object already loaded, and you want to parse it as a GTIRB IR. If the Protobuf object is stored in a file, use gtirb.IR.load_protobuf() instead.

Parameters:

protobuf_file (typing.BinaryIO) – A byte stream encoding a GTIRB Protobuf message.

Return type:

gtirb.ir.IR

Returns:

An IR object representing the same information that is contained in protobuf_file.

modules_named(name)

Find all modules with a given name

Return type:

typing.Iterator[gtirb.module.Module]

property proxy_blocks: Iterator[ProxyBlock]

The ProxyBlocks in this IR.

save_protobuf(file_name)

Save self to a Protobuf file at the specified path.

Parameters:

file_name – The file path at which to save the Protobuf representation of self.

save_protobuf_file(protobuf_file)

Save self to a Protobuf object.

Parameters:

protobuf_file (typing.BinaryIO) – The byte stream to write the GTIRB Protobuf message to.

Return type:

None

property sections: Iterator[Section]

The Sections in this IR.

sections_at(addrs)

Finds all the sections that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.section.Section]

sections_on(addrs)

Finds all the sections that overlap an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[gtirb.section.Section]

symbolic_expressions_at(addrs)

Finds all the symbolic expressions that begin at an address or range of addresses.

Parameters:

addrs (typing.Union[int, range]) – Either a range object or a single address.

Return type:

typing.Iterable[typing.Tuple[gtirb.byteinterval.ByteInterval, int, gtirb.symbolicexpression.SymbolicExpression]]

Returns:

Yields (interval, offset, symexpr) tuples for every symbolic expression in the range.

property symbols: Iterator[Symbol]

The Symbols in this IR.