gtirb.block module

class gtirb.block.Block(uuid=None)[source]

Bases: Node

The base class for blocks. Symbols may have references to any subclass of Block.

property module: Module | None

Get the module this node ultimately belongs to.

property references: Iterator[Symbol]

Get all the symbols that refer to this block.

class gtirb.block.ByteBlock(*, size=0, offset=0, uuid=None, byte_interval=None)[source]

Bases: Block

The base class for blocks that belong to a ByteInterval and store their bytes there.

Variables:

  • ~.size – The size of the block in bytes.

  • ~.offset – The offset from the beginning of the byte interval to which this block belongs. Multiple blocks in the same interval may have the same offset.

__init__(*, size=0, offset=0, uuid=None, byte_interval=None)[source]
Parameters:

  • size (int) – The size of the data object in bytes.

  • offset (int) – The offset from the beginning of the byte interval to which this block belongs.

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

  • byte_interval (typing.Optional[gtirb.byteinterval.ByteInterval]) – The ByteInterval this block belongs to.

property address: int | None

Get the address of this block, or None if not present.

property byte_interval: ByteInterval | None

The ByteInterval this block belongs to.

contains_address(address)[source]

Indicate if the provided address is within this block. Returns False if the block has no address.

Return type:

bool

contains_offset(offset)[source]

Indicate if the provided offset is within this block.

Return type:

bool

property contents: bytes

Get the bytes in this block.

deep_eq(other)[source]

Check: is self structurally equal to other?

This method should be used only when deep structural equality checks are actually needed, and not for all equality checks. Typically the default implmentation of __eq__, which checks pointer equality, is sufficient; Nodes are cached such that references to two Nodes with the same UUID refer to the same exact object. Use this method when you have manually constructed Nodes that may share the same UUID despite being different objects, and you need to check for structural equality.

Return type:

bool

property ir: IR | None

Get the IR this node ultimately belongs to.

property module: Module | None

Get the module this node ultimately belongs to.

offset

A descriptor that will notify a parent when the value is set and can be otherwise used like a normal attribute.

property section: Section | None

Get the section this node ultimately belongs to.

size

A descriptor that will notify a parent when the value is set and can be otherwise used like a normal attribute.

class gtirb.block.CfgNode(uuid=None)[source]

Bases: Block

The base class for blocks that may appear as vertices in the CFG.

property incoming_edges: Iterable[Edge]

Get the edges that point to this CFG node.

property outgoing_edges: Iterable[Edge]

Get the edges that start at this CFG node.

class gtirb.block.CodeBlock(*, decode_mode=DecodeMode.Default, size=0, offset=0, uuid=None, byte_interval=None)[source]

Bases: ByteBlock, CfgNode

A basic block in the binary.

Does not directly store data bytes, which are kept in a ByteInterval.

Variables:

~.decode_mode – The decode mode of the block, used in some ISAs to differentiate between sub-ISAs (e.g. differentiating blocks written in ARM and Thumb).

class DecodeMode(value)[source]

Bases: Enum

Variations on decoding a particular ISA

Default = 0

Default decode mode for all ISAs

Thumb = 1

Thumb decode mode for ARM32

__init__(*, decode_mode=DecodeMode.Default, size=0, offset=0, uuid=None, byte_interval=None)[source]
Parameters:

  • size (int) – The length of the block in bytes.

  • decode_mode (gtirb.block.CodeBlock.DecodeMode) – The decode mode of the block, used in some ISAs to differentiate between sub-ISAs (e.g. differentiating blocks written in ARM and Thumb). Defaults to DecodeMode.Default.

  • offset (int) – The offset from the beginning of the byte interval to which this block belongs.

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

  • byte_interval (typing.Optional[gtirb.byteinterval.ByteInterval]) – The ByteInterval this block belongs to.

deep_eq(other)[source]

Check: is self structurally equal to other?

This method should be used only when deep structural equality checks are actually needed, and not for all equality checks. Typically the default implmentation of __eq__, which checks pointer equality, is sufficient; Nodes are cached such that references to two Nodes with the same UUID refer to the same exact object. Use this method when you have manually constructed Nodes that may share the same UUID despite being different objects, and you need to check for structural equality.

Return type:

bool

property incoming_edges: Iterator[Edge]

Get the edges that point to this CFG node.

property outgoing_edges: Iterator[Edge]

Get the edges that start at this CFG node.

class gtirb.block.DataBlock(*, size=0, offset=0, uuid=None, byte_interval=None)[source]

Bases: ByteBlock

Represents a data object, possibly symbolic.

__init__(*, size=0, offset=0, uuid=None, byte_interval=None)[source]
Parameters:

  • size (int) – The size of the data object in bytes.

  • offset (int) – The offset from the beginning of the byte interval to which this block belongs.

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

  • byte_interval (typing.Optional[gtirb.byteinterval.ByteInterval]) – The ByteInterval this block belongs to.

class gtirb.block.ProxyBlock(*, uuid=None, module=None)[source]

Bases: CfgNode

A placeholder that serves as the endpoint (source or target) of a gtirb.Edge.

ProxyBlock objects allow the construction of CFG edges to or from another node. For example, a call to a function in another module may be represented by a gtirb.Edge that originates at the calling gtirb.CodeBlock and targets a ProxyBlock. Another example would be a gtirb.Edge that represents an indirect jump whose target is not known.

A ProxyBlock does not represent any instructions and so has neither an address nor a size.

__init__(*, uuid=None, module=None)[source]
Parameters:

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

deep_eq(other)[source]

Check: is self structurally equal to other?

This method should be used only when deep structural equality checks are actually needed, and not for all equality checks. Typically the default implmentation of __eq__, which checks pointer equality, is sufficient; Nodes are cached such that references to two Nodes with the same UUID refer to the same exact object. Use this method when you have manually constructed Nodes that may share the same UUID despite being different objects, and you need to check for structural equality.

Return type:

bool

property incoming_edges: Iterator[Edge]

Get the edges that point to this CFG node.

property ir: IR | None

Get the IR this node ultimately belongs to.

property module: Module | None

Get the module this node ultimately belongs to.

property outgoing_edges: Iterator[Edge]

Get the edges that start at this CFG node.