Interface

Module entry point for the ocgraph package.

Let this module be executed from the command line with python -m ocgraph from root of the project.

ocgraph.__main__.main(args: Sequence[str] | None = None) → None

Command-line entry point to the program.

Class for read and analyze the input string.

class ocgraph.interface.analyzer.Analyzer(diss: Disassembler, arch: Architecture, logger: Logger)

Bases: object

Analyzer Class.

__init__(diss: Disassembler, arch: Architecture, logger: Logger) → None

Initialize the Analyzer.

analyze() → None

Run complete analyzing algorithm.

parse_file(file_path: str) → None

Parse a assembler file.

parse_lines(lines: list[str]) → None

Parse a list of assembly lines.

Class for reading coverage input and updating the instructions.

class ocgraph.interface.coverage_reader.CoverageReader(instructions: list[Instruction], arch: Architecture)

Bases: object

CoverageReader Class.

__init__(instructions: list[Instruction], arch: Architecture) → None
static decode_coverage_value(input_value: str) → Coverage

Convert tsim bit field into appropriate coverage enum element:

"executed":         0b00001, => line taken.
"written":          0b00010, => ignored.
"read":             0b00100, => ignored.
"branch_taken":     0b01000, => jump taken.
"branch_not_taken": 0b10000  => jump passed.
Parameters:

input_value – Bit field of binary coded coverage.

Returns:

coverage converted into Coverage enum.

offset_address(address: int, start_address: int = -1) → int

Compute an offset and apply it to address.

Parameters:

  • address – Address to offset

  • start_address – Start address of the function in the test binary used to produce the coverage file. If not specified, it is assumed that the coverage and disassembly files share the same address space.

Returns:

offset_address = address - start_address_in_coverage + start_address_in_disassembly

parse_coverage(file_path: str, start_address: int = -1) → dict[int, Coverage]

Parse TSIM coverage file and return a coverage map on address base.

Parameters:

  • file_path – Path to the file which shall be read.

  • start_address – Start address of the function in the test binary used to produce the coverage file. If not specified, it is assumed that the coverage and disassembly files share the same address space.

Returns:

a coverage map where each instruction address has a coverage state associated as a dictionary.

update_by_occtre_coverage(file_path: str, start_address: int = -1) → None

Read OCCTRE coverage file and update coverage information.

Parameters:

  • file_path – Path to the file which shall be read.

  • start_address – Start address of the function in the test binary used to produce the coverage file. If not specified, it is assumed that the coverage and disassembly files share the same address space.

update_by_tsim_coverage(file_path: str, start_address: int = -1) → None

Read tsim coverage file and update the coverage information.

Expected format for the TSIM coverrage file::

<address>: 16 bit fields for the following addresses separated by whitespace.

Format example::

310041d8 : 9 1 0 0 1 1 1 11 0 1 1 1 1 19 1 1

Bit field format (from tsim manual):

The coverage data for each 32-bit word of memory consists of a 5-bit field, with bit0 (lsb) indicating that the word has been executed, bit1 indicating that the word has been written, and bit2 that the word has been read. Bit3 and bit4 indicates the presence of a branch instruction; if bit3 is set then the branch was taken while bit4 is set if the branch was not taken.

Bit field example:

19 -> 0x19 -> 11001 -> executed: true, written: false, read: false, branch_taken: true, branch_not_taken: true

Parameters:

  • file_path – Path to the file which shall be read.

  • start_address – Start address of the function in the test binary used to produce the coverage file. If not specified, it is assumed that the coverage and disassembly files share the same address space.

Class for drawing the output.

class ocgraph.interface.drawer.Drawer(arch: Architecture, logger: Logger, graph_options: dict[str, Any] | None = None)

Bases: object

Drawer Class.

__init__(arch: Architecture, logger: Logger, graph_options: dict[str, Any] | None = None) → None
draw_cfg(name: str, basic_blocks: dict[int, BasicBlock], output: str | None = None) → None

Draw a function graph.

set_graph_option(graph_options: dict[str, Any]) → None

Set new graph options.

view_cfg(name: str, basic_blocks: dict[int, BasicBlock]) → None

View a function graph.