ocgraph 0.3.0__tar.gz → 1.0.0__tar.gz

ocgraph-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,156 @@
+stages:
+- setup
+- test
+- code-quality
+- build
+- doc
+- publish
+
+# Default image of the jobs that do not select one: the Debian stable build of
+# this project. The matrix jobs pick the image of their distribution.
+image: $CI_REGISTRY_IMAGE/debian-bookworm
+
+# Build and push one project image per supported distribution. Each image pins
+# the Python of that distribution, so the matrix below tests the package on the
+# interpreter versions the classifiers claim: 3.11 on Debian bookworm, 3.12 on
+# Ubuntu 24.04, 3.13 on Debian trixie and on Arch. The images also carry the
+# Graphviz binaries, which render the graphs of the suite.
+setup:
+  stage: setup
+  image: docker
+  before_script:
+  - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
+  script:
+  - docker pull $(grep FROM docker/Dockerfile-$OS | cut -d' ' -f2)
+  - docker build -t $CI_REGISTRY_IMAGE/$OS -f docker/Dockerfile-$OS .
+  - docker push $CI_REGISTRY_IMAGE/$OS
+  parallel:
+    matrix:
+    - OS: [debian-bookworm, debian-trixie, ubuntu-24-04, arch]
+
+test:
+  stage: test
+  # The image of the matrix entry pins the interpreter: 3.11 on bookworm, 3.12 on
+  # Ubuntu 24.04, 3.13 on trixie and on Arch.
+  image: $CI_REGISTRY_IMAGE/$OS
+  before_script:
+  - poetry install
+  script:
+  - poetry run pytest
+  # The coverage reports come from the addopts of the pytest section of
+  # pyproject.toml, which is also what a local run produces. The job variable is
+  # the one report that only the pipeline wants: the JUnit results of the merge
+  # request.
+  variables:
+    PYTEST_ADDOPTS: --junitxml=report.xml
+  coverage: '/^TOTAL.*\s+(\d+\%)$/'
+  needs: [setup]
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+      junit: report.xml
+    paths:
+    - htmlcov
+    - output
+    - coverage.xml
+    - report.xml
+  parallel:
+    matrix:
+    - OS: [debian-bookworm, debian-trixie, ubuntu-24-04, arch]
+
+# The type check is a gate: the package ships `ocgraph/py.typed` and the strict
+# settings of pyproject.toml apply, so a type error blocks a change. It runs on
+# the interpreter of the default image, 3.11, like the release build does.
+mypy:
+  stage: code-quality
+  before_script:
+  - poetry install
+  script:
+  - poetry run mypy -p ocgraph
+  needs: [setup]
+
+# The two linters publish review reports on the merge request. Their findings do
+# not block a change, in contrast to the type check above.
+pylint:
+  stage: code-quality
+  before_script:
+  - poetry install
+  script:
+  - poetry run pylint -j0 --allow-reexport-from-package y --output-format=codeclimate ocgraph > pylint-report.json
+  needs: [setup]
+  allow_failure: true
+  artifacts:
+    reports:
+      codequality: pylint-report.json
+    paths:
+    - pylint-report.json
+    expire_in: 30 days
+
+ruff:
+  stage: code-quality
+  before_script:
+  - poetry install
+  script:
+  - poetry run ruff check ocgraph test --output-format=gitlab --output-file=ruff-report.json
+  - poetry run ruff check ocgraph test --output-format=concise
+  needs: [setup]
+  allow_failure: true
+  artifacts:
+    reports:
+      codequality: ruff-report.json
+    paths:
+    - ruff-report.json
+    expire_in: 30 days
+
+build:
+  stage: build
+  before_script:
+  - poetry install
+  script:
+  - poetry build
+  needs: [test, mypy]
+  artifacts:
+    paths:
+    - dist
+    expire_in: 30 days
+
+documentation:
+  stage: doc
+  before_script:
+  - poetry install
+  script:
+  - poetry run sphinx-build -W -b html doc doc_html
+  needs: [build]
+  artifacts:
+    paths:
+    - doc_html/
+    expire_in: 30 days
+
+pages:
+  stage: publish
+  script:
+  - cp -R doc_html/ public/
+  artifacts:
+    paths:
+    - public/
+    expire_in: 30 days
+  needs: [documentation]
+
+# Publish the release to PyPI. Requires the CI variable POETRY_PYPI_TOKEN_PYPI
+# (a PyPI API token scoped to this project) and runs on tagged commits only.
+publish-to-pypi:
+  stage: publish
+  before_script:
+  - poetry install
+  script:
+  - poetry build
+  - poetry run pip install --quiet twine
+  - poetry run twine check dist/*
+  - poetry publish --skip-existing
+  needs: [build, documentation, pages]
+  rules:
+  - if: '$CI_COMMIT_TAG'
+  environment:
+    name: pypi

ocgraph-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+exclude: |
+  (?x)^(
+    test/ocgraph/validation/(input|expected)/.*
+  )$
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-builtin-literals
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-shebang-scripts-are-executable
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: check-xml
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: debug-statements
+      - id: destroyed-symlinks
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: pretty-format-json
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.4          # Ruff version.
+    hooks:
+      - id: ruff         # Run the linter.
+        args: [ --fix, --config=pyproject.toml ]
+      - id: ruff-format  # Run the formatter.
+  - repo: https://github.com/doublify/pre-commit-clang-format
+    rev: 62302476d0da01515660132d76902359bed0f782
+    hooks:
+      - id: clang-format
+        types: [file]
+        files: \.(cpp|cc|cxx|c|h|hxx)$
+        args: [--style=file]

ocgraph-1.0.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+uses [semantic versioning](https://semver.org/spec/v2.0.0.html). The version is
+the `version` entry of `pyproject.toml`, and every release is tagged
+`v<version>` in the repository.
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-06
+
+The first release published to PyPI, and the first whose packaging, licensing,
+typing, and documentation are covered by the pipeline. The tool itself grew from
+the single-architecture renderer of 0.3.0 into an analyzer of five object-code
+architectures with runtime coverage, and the release engineering of this section
+is what makes that behavior verifiable by someone who did not write it.
+
+### Added
+
+* RISC-V support, and instruction lists of ARM, PowerPC, and SPARC V8 extended to
+  cover the instructions that carry a delay slot, including the `bgeu` and `blu`
+  aliases.
+* TSIM `.cov` files as coverage input next to the OCCTRE reports, with an
+  address-space offset for images linked away from zero, a manual coverage type
+  selection, and `--assert-coverage` for the coverage of a graph.
+* `get_export_structure()` gives a caller the graph as data, with the taken jump,
+  the jump destination in the middle of a basic block, the edge coverage, and the
+  sinks distinguished from unresolved targets.
+* Branch delay slots are tracked per architecture, an unresolved call ends a
+  block, and several observed targets of one conditional branch are rendered as
+  several edges.
+* `--version`, `python -m ocgraph`, and `--view` to open the generated PDF.
+* Sphinx documentation, published on GitLab Pages, covering the command line, the
+  accepted disassembly, the coverage formats, the graph reading guide, and the
+  extension of an architecture.
+* A container image per supported distribution, so the suite runs on the
+  interpreter of each distribution that the classifiers claim: 3.11, 3.12, 3.13,
+  and 3.14.
+* The strict type check is a gate of the pipeline, and `ocgraph/py.typed`
+  advertises the annotations to downstream type checks.
+* A test ties the version of the package to the `version` entry of
+  `pyproject.toml`, the file the build backend reads.
+* `CHANGELOG.md` and `CONTRIBUTING.md`.
+
+### Changed
+
+* The modules are reorganised into `ocgraph.interface` and `ocgraph.internal`,
+  with factory patterns for the architecture and the disassembler.
+* Python 3.11 is the minimum supported version, and `requires-python` caps the
+  interpreter below 4.0.
+* The distributions are described with a PEP 621 `[project]` table and carry PEP
+  639 license metadata, and the source distribution carries the test suite, the
+  documentation sources, the container images, the pipeline definition, the
+  pre-commit configuration, the contributor guide, and the lock file.
+* The license is named by the SPDX identifier `MIT` in every source file. The
+  text of the two notices of `LICENSES/` is the MIT License verbatim, and
+  `LICENSE` collects both copyright statements, the upstream asm2cfg one and the
+  Celeres one.
+* Generated PDFs are reproducible: the metadata of the document is normalised, and
+  the snapshot tests ignore the Graphviz layout coordinates.
+* The `--type` argument is required only when coverage is given, and the coverage
+  colors distinguish executed, uncovered, and sink instructions.
+
+### Fixed
+
+* SPARC trap opcodes are decoded, and the SPARC instruction lists no longer
+  contain duplicates.
+* A disassembly line whose jump target is followed by more text is parsed, and
+  malformed disassembly is reported as an input error instead of a traceback.
+* Delay slot handling, the handling of an unconditional branch that coverage
+  reports with more than one target, and the drawer initialization.
+* Coverage state is restored when an update is rolled back, and non-branch
+  instructions observed with more than one successor are invalidated.
+* Empty blocks are guarded against in the rendering, blocks that are not directly
+  reached are no longer dropped, and edges to address zero are rendered.
+* The reproducibility test no longer compares the creation timestamp that Graphviz
+  embeds in the PDF, which made the suite fail at random.
+* `--version` works from a source tree without installed distribution metadata.
+
+### Removed
+
+* `ocrecord`, the GDB helper of 0.3.0. It imports the `Configuration` module that
+  this release removes, so it could not run, and nothing in the package, the
+  documentation, the tests, or the distribution referenced it.
+* The GitHub workflow files and the helper scripts of the pre-Packaging era, and
+  the obsolete `Configuration` module.
+
+## [0.3.0] - 2025-01-10
+
+The release in which the tool became a Python package. The releases before it were
+not tagged, so this is the first point that a packager can name.
+
+### Added
+
+* Packaging with Poetry, the `ocgraph` console command, and the container image
+  that the pipeline builds.
+* Unit tests and validation tests built from the earlier examples, and the test
+  template generators that produce the inputs of a test.
+* Abstract base classes for the architecture and the disassembler, with parsing of
+  the instructions in a single step and non-coverable code excluded.
+* `ocrecord`, a GDB helper that produces the disassembly that ocgraph reads.
+
+### Changed
+
+* The configuration moved from `setup.cfg` to `pyproject.toml`, and the
+  re-exports of the package `__init__` files simplify the imports.
+
+[Unreleased]: https://gitlab.com/gtd-gmbh/ocgraph/-/compare/v1.0.0...main
+[1.0.0]: https://gitlab.com/gtd-gmbh/ocgraph/-/compare/v0.3.0...v1.0.0
+[0.3.0]: https://gitlab.com/gtd-gmbh/ocgraph/-/tags/v0.3.0

ocgraph-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing to ocgraph
+
+This file describes the development environment of ocgraph. The tool itself, its
+options, and its graphs are documented in
+[README.md](README.md) and in the
+[Sphinx documentation](https://gtd-gmbh.gitlab.io/ocgraph/), whose
+development chapter explains the analysis flow and the extension points.
+
+## System Dependencies
+
+ocgraph needs the Graphviz binaries to render a graph, and the suite renders real
+PDFs, so a development machine needs the same package:
+
+```
+sudo apt-get update
+sudo apt-get install python3 python3-pip python3-venv graphviz
+```
+
+On Arch Linux, use pacman:
+
+```
+sudo pacman -Sy python python-pip graphviz
+```
+
+Install Poetry 2.5 with [pipx](https://pipx.pypa.io/), `pipx install poetry`. The
+Poetry of a Debian stable release predates PEP 621 support, and only poetry-core
+2.5 writes the PEP 639 metadata of a release, which the
+`poetry-core>=2.5.0` floor of `pyproject.toml` asks for.
+
+## Setting up a virtual environment
+
+After cloning the repository, create and populate the Python virtualenv:
+
+```
+poetry install
+```
+
+## Installing and updating Python dependencies
+
+All explicit dependencies are listed in `pyproject.toml`. Exact versions and the
+dependencies of your dependencies are in `poetry.lock`.
+
+Adding or removing packages is done through the `poetry add` command or by
+editing `pyproject.toml`, followed by `poetry lock`. Updating all existing
+dependencies is done with `poetry update`. Commit the lock file with the change
+that requires it, because the pipeline installs from it.
+
+## Release notes
+
+`CHANGELOG.md` documents every release in the format of
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Add an entry to the
+`Unreleased` section together with the commit that changes the behaviour of the
+tool, so that the section of the next release is complete when the version is
+bumped.
+
+## Commit hooks
+
+The repository uses git pre-commit hooks so that no obvious error is committed.
+Install them after activating the virtualenv:
+
+```
+poetry run pre-commit install
+```
+
+The hooks run Ruff as linter and formatter, and check the plain things: syntax,
+trailing whitespace, merge conflict markers, large files, private keys.
+
+## Running the test suite
+
+The suite is run with pytest:
+
+```
+poetry run pytest
+```
+
+It needs no target, debugger, or emulator, but it does render real graphs, so the
+Graphviz binaries of the section above are required. The unit tests cover the
+disassemblers, the architectures, the analyzer, the coverage readers, and the
+drawer; the validation tests render a graph per architecture and compare the
+generated `.gv` file with the expected file in `test/ocgraph/validation`.
+
+The pipeline runs the suite once per supported distribution, on the interpreter of
+that distribution: 3.11 on Debian bookworm, 3.12 on Ubuntu 24.04, 3.13 on Debian
+trixie, and the rolling 3.14 of Arch Linux.
+
+Add a unit test when changing parsing, instruction classification, coverage, or
+block formation, and a validation fixture when a change alters a rendered graph.
+
+The pipeline also runs `mypy -p ocgraph` with the strict settings of
+`pyproject.toml`. Because the package ships `ocgraph/py.typed`, a type error
+fails the pipeline, so run the same command before pushing:
+
+```
+poetry run mypy -p ocgraph
+```
+
+`pylint` and `ruff check` publish review reports on the merge request, and a
+finding in the internal modules does not block a change:
+
+```
+poetry run pylint -j0 --allow-reexport-from-package y ocgraph
+poetry run ruff check ocgraph test
+```
+
+## Building the documentation
+
+The Sphinx HTML documentation is built with:
+
+```
+poetry run sphinx-build -W -b html doc doc_html
+```
+
+The generated entry page is `doc_html/index.html`. The `-W` option turns
+documentation warnings into errors, as the pipeline does.
+
+## Building a release
+
+Releases are built with Poetry 2.5, the version the container images install and
+the `poetry-core>=2.5.0` floor of `pyproject.toml` asks for: only poetry-core 2.5
+writes the PEP 639 metadata of the release, with `License-Expression: MIT` and
+the three license files listed in the wheel. Build the archives and check them
+before publishing:
+
+```
+poetry build
+poetry run pip install twine && poetry run twine check dist/*
+```
+
+The sdist carries the test suite, the test templates, the documentation sources,
+the container images, the pipeline definition, and the lock file, so a release
+built from the sdist can be verified with the commands above. The wheel contains
+only the `ocgraph` package and its `py.typed` marker.
+
+Releases are published to PyPI by the pipeline on tagged commits. The pipeline
+needs the `POETRY_PYPI_TOKEN_PYPI` CI variable, a PyPI API token scoped to this
+project.

ocgraph-1.0.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2021 Mauri Mustonen
+Copyright (c) 2023-2026 Celeres
+
+ocgraph originates in asm2cfg by Mauri Mustonen and was extended by Celeres. The
+two notices are kept apart in `LICENSES/MauriMustonen.md` and
+`LICENSES/Celeres.md`, which carry the same text as below.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ocgraph-0.3.0/LICENSES/GTDGmbH.md → ocgraph-1.0.0/LICENSES/Celeres.md

@@ -1,7 +1,7 @@
-Valid-License-Identifier: GTDGmbH
+Valid-License-Identifier: Celeres
 License-Text:
 
-Copyright (c) 2023 GTD GmbH. All rights reserved.
+Copyright (c) 2023-2026 Celeres. All rights reserved.
 
 MIT License
 

ocgraph-1.0.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: ocgraph
+Version: 1.0.0
+Summary: Tool to visualize object code as control flow graph
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSES/Celeres.md
+License-File: LICENSES/MauriMustonen.md
+Keywords: Object Code,Control Flow Graph,ECSS Category A,asm2cfg,Coverage
+Author: Mauri Mustonen
+Author-email: kazooiebombchu@gmail.com
+Maintainer: Christoph Weiss
+Maintainer-email: christoph.weiss@celeres.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Dist: graphviz (>=0.21,<0.22)
+Project-URL: Changelog, https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://gtd-gmbh.gitlab.io/ocgraph/
+Project-URL: Forked from asm2cfg, https://github.com/Kazhuu/asm2cfg
+Project-URL: Homepage, https://gitlab.com/gtd-gmbh/ocgraph
+Project-URL: Issues, https://gitlab.com/gtd-gmbh/ocgraph/-/issues
+Project-URL: Repository, https://gitlab.com/gtd-gmbh/ocgraph
+Description-Content-Type: text/markdown
+
+# 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](https://pypi.org/project/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](https://pipx.pypa.io/), which keeps it in its own virtual environment:
+
+```console
+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](https://gtd-gmbh.gitlab.io/ocgraph/)
+- [Documentation sources](https://gitlab.com/gtd-gmbh/ocgraph/-/tree/main/doc)
+
+Build it locally with:
+
+```console
+poetry install
+poetry run sphinx-build -W -b html doc doc_html
+```
+
+The generated entry page is `doc_html/index.html`.
+
+## Development
+
+[CONTRIBUTING.md](https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/CONTRIBUTING.md)
+describes the development environment, and the
+[development chapter](https://gitlab.com/gtd-gmbh/ocgraph/-/tree/main/doc/development)
+explains the analysis flow and the extension points. The short version:
+
+```console
+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](https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/LICENSE).
+The project was forked from [asm2cfg](https://github.com/Kazhuu/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](https://gitlab.com/gtd-gmbh/ocgraph/-/tree/main/LICENSES).
+
+## Links
+
+- [Documentation](https://gtd-gmbh.gitlab.io/ocgraph/)
+- [PyPI](https://pypi.org/project/ocgraph/)
+- [Source repository](https://gitlab.com/gtd-gmbh/ocgraph)
+- [Issues](https://gitlab.com/gtd-gmbh/ocgraph/-/issues)
+- [Changelog](https://gitlab.com/gtd-gmbh/ocgraph/-/blob/main/CHANGELOG.md)
+- [asm2cfg, the upstream project](https://github.com/Kazhuu/asm2cfg)
+