Object Code Graph (ocgraph)

ocgraph converts the disassembly of one function into a control-flow graph (CFG). It can enrich the graph with instruction and branch coverage from OCCTRE or TSIM.

The analyzer supports ARM, MSP430, PowerPC, RISC-V, SPARC V8, and x86 GNU objdump output. Every run writes both a PDF for review and the corresponding Graphviz source (.gv).

A graph is a view of the disassembly you supply: it depends on that disassembly, on the architecture selection, and on the optional runtime coverage, so validate a generated graph for the intended toolchain and assurance process.

Quick start

Python 3.11 or newer and the Graphviz system package are required, because the dot binary renders the PDF. Install the tool with pipx, which keeps it in its own virtual environment:

pipx install ocgraph
objdump -d --disassemble=my_function ./application > my_function.asm
ocgraph --file my_function.asm --arch x86 --diss objdump

python -m pip install ocgraph installs it into the active environment instead, which is what a packager wants. python -m ocgraph runs the same command from a checkout of the source tree, and ocgraph --version reports the version.

This creates my_function.pdf and my_function.gv. Use --output to choose a different output basename and --view to open the generated PDF after both files have been written.

Documentation

The full documentation covers installation, accepted disassembly input, coverage formats, command-line and Python usage, graph interpretation, and extension development:

• Published documentation
• Documentation sources

Build it locally with:

poetry install
poetry run sphinx-build -W -b html doc doc_html

The generated entry page is doc_html/index.html.

Development

CONTRIBUTING.md describes the development environment, and the development chapter explains the analysis flow and the extension points. The short version:

poetry install
poetry run pytest
poetry run mypy -p ocgraph
poetry run pre-commit run --all-files

The pipeline runs the suite on Debian bookworm, Debian trixie, Ubuntu 24.04, and Arch Linux, which pins the interpreters 3.11, 3.13, 3.12, and the rolling 3.14.

License

Released under the MIT License, see LICENSE. The project was forked from asm2cfg by Mauri Mustonen, who holds the copyright of 2021 for the work it builds on, and Celeres holds the copyright of 2023 to 2026 for the extensions. The two notices are kept apart in LICENSES.

Links

• Documentation
• PyPI
• Source repository
• Issues
• Changelog
• asm2cfg, the upstream project