Metadata-Version: 2.4
Name: occtre
Version: 1.0.0
Summary: A tool for producing, collecting and analyzing test coverage on assembler level
License-Expression: MPL-2.0
License-File: COPYING.md
License-File: LICENSE
Keywords: Target,Coverage,Coverage Tracer,GDB,Embedded,Disassembly
Author: Celeres GmbH
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 :: Embedded Systems
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Dist: dataclass-binder (>=0.3.5,<0.4.0)
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
Requires-Dist: tomlkit (>=0.14.0,<0.15.0)
Project-URL: Changelog, https://gitlab.com/gtd-gmbh/occtre/-/blob/main/CHANGELOG.md
Project-URL: Documentation, https://gtd-gmbh.gitlab.io/occtre/
Project-URL: Homepage, https://gitlab.com/gtd-gmbh/occtre
Project-URL: Issues, https://gitlab.com/gtd-gmbh/occtre/-/issues
Project-URL: Repository, https://gitlab.com/gtd-gmbh/occtre
Description-Content-Type: text/markdown

# OCCTRE

OCCTRE (**Object Code Coverage Trace Enlighter**) records instruction-level
execution information from a program that is controlled through GDB. It starts
or attaches to a target, single-steps the program between two labels, and maps
every observed instruction back to its source location.

It answers the questions that come up when the tests of an embedded target run
only on a simulator, a debug probe, or in a qualification setup:

* Which machine instructions of the test binary were actually executed, and how
  often was each of them seen?
* Which source file and line belong to every executed instruction?
* Which successor address did a conditional branch actually take?
* Which load and store instructions were observed, and at which decoded data
  address?

Every run writes two equivalent reports next to the test binary, `<binary>.csv`
for scripts and CI, and `<binary>.md` for review. OCCTRE reports what one
execution showed; it does not calculate a coverage percentage.

A useful setup needs three external programs next to OCCTRE itself: a target
such as QEMU, SIS, `gdbserver`, or a hardware debug monitor; a GDB that
understands the test binary and its architecture; and an `addr2line` for the
same binary format.

## Installation

The latest release is published on PyPI. Install it with
[pipx](https://pipx.pypa.io/), which keeps the tool in its own virtual
environment:

```
pipx install occtre
```

`pipx` is packaged as `pipx` or `python-pipx` by most distributions. Plain `pip`
works too, inside a virtual environment:

```
python3 -m venv .venv
. .venv/bin/activate
pip install occtre
```

Arch Linux users can install the `occtre` package from the AUR with an AUR
helper such as `yay -S occtre`.

OCCTRE requires Python 3.11 or newer. The target tools are deliberately not
Python dependencies: their executable paths are selected in the configuration
file, so native and cross-development toolchains can be used side by side.

## Quick start

### Trace a QEMU target

Copy the template that is closest to the target from
[occtre/configuration/templates](https://gitlab.com/gtd-gmbh/occtre/-/tree/main/occtre/configuration/templates),
adjust the tool paths, and run OCCTRE on the test binary:

```
occtre --binary build/test-program --config qemu_sparc.toml
```

The report is written next to the test binary. A Markdown report produced by the
instruction-jump recorder looks like this:

```
| Address    | Label(+off)            | Instruction (hex)   | Instruction                    | Opcode   |   Executed | Branch taken   |
|:-----------|:-----------------------|:--------------------|:-------------------------------|:---------|-----------:|:---------------|
| 0x0002026c | fmodf+4                | 05 1f df ff         | sethi  %hi(0x7f7ffc00), %g2    | sethi    |          1 | []             |
| 0x00003554 | nextafterf_test_fun+60 | d1 07 bf fc         | ld  [ %fp + -4 ], %f8          | ld       |          1 | []             |
| 0x000229c0 | nextafterf+136         | 22 bf ff f3         | be,a   0x2298c <nextafterf+84> | be,a     |          1 | ['0x000035dc'] |
| 0x000035dc | fmaxf_test_fun+20      | b8 17 20 38         | or  %i4, 0x38, %i4             | or       |          1 | []             |
```

The Markdown table shows the columns the selected recorder fills. The CSV report
carries all columns, `address`, `location`, `instruction_hex`,
`instruction_opcode`, `instruction_decoded`, `instruction_str`, `count`,
`source_code`, and `branch_jumps`, in a stable order. Existing files at those
two paths are replaced.

### Bound the traced region

The recorder single-steps from `start-label` to `stop-label`, so the test binary
should carry the symbols named there. Compile with debug information if the
report shall contain source files and lines.

```toml
[recorder]
name = "InstructionJumpRecorder"
binary-path = "{test_binary}"
start-label = "ExecuteTestRun"
stop-label  = "TearDownTestRun"
```

`{test_binary}`, `{task_host}`, `{task_port}`, and `{task_target}` are
substituted in process options and endpoints. The endpoint of an externally
started target can also be passed on the command line.

### Select what to record

| `name` in `[recorder]` | Fills | Notes |
| --- | --- | --- |
| `InstructionRecorder` | `count` per executed address | Answers which instructions ran and how often. |
| `InstructionJumpRecorder` | `branch_jumps` in addition | Records the observed successors of recognized control-flow instructions. |
| `DataAccessRecorder` | `instruction_decoded` in addition | Experimental, implemented for the SPARC V8 load and store set. |

The architecture in `[parser]` selects the instruction decoder. ARM, MSP430,
PowerPC, RISC-V, SPARC V8, and x86 are supported; SPARC V8 delay slots and
annulled branches are resolved before a successor is recorded.

### Machine-readable report

The CSV report is meant to be post-processed. Decoded data addresses, for
example, can be correlated with symbols by standard binary utilities:

```
mlr --csv cut -f instruction_decoded test-program.csv \
  | grep -E -i -o "0x[0-9a-f]+" | sort -u

nm -S -n -C --line-numbers test-program | grep ADDRESS_WITHOUT_0x
```

Those commands are examples rather than part of OCCTRE, and their options depend
on the binary format, relocation model, and toolchain.

## Command-line options

| Option | Purpose |
| --- | --- |
| `-b`, `--binary` | Test binary to trace. Required. |
| `-c`, `--config` | Path to the configuration file. Defaults to `./config.toml`. |
| `-H`, `--host` | Host part of the GDB endpoint, overriding the configuration. |
| `-p`, `--port` | Port part of the GDB endpoint, overriding the configuration. |
| `-t`, `--target` | Complete GDB endpoint, such as `HOST:PORT` or `/dev/tty`. |
| `-v`, `--version` | Print the version and exit. |

`--target` cannot be combined with `--host` or `--port`. The
[execution reference](https://gtd-gmbh.gitlab.io/occtre/execution.html)
documents the run lifecycle, the configuration sections, and the process
handling in detail.

## Exit status

| Status | Meaning |
| --- | --- |
| 0 | The trace completed and both reports were written. |
| N | The exit code of a target, debugger, or `addr2line` process that failed, propagated by OCCTRE. |
| 1 | A configuration file that cannot be read, an unknown recorder name, or another unhandled error. |
| 2 | Invalid arguments, including `--target` combined with `--host` or `--port`. |

## Scope and limitations

OCCTRE reports observed execution data, not a coverage measurement. Before using
a report as evidence:

* OCCTRE does not enumerate the instructions of the binary, so there is no
  denominator for a percentage; the expected instruction and branch sets have to
  be defined separately.
* `branch_jumps` lists the successors that were observed, not a static inventory
  of all possible branch outcomes.
* Data-access decoding is experimental and limited to SPARC V8.
* Optimisation, inlining, stripped symbols, relocation, PIE, and address space
  randomisation change how runtime addresses relate to the static binary.
* Confirm that the configured start and stop labels bound the intended code,
  compare a sample of rows against an independent GDB disassembly, and keep the
  configuration, binary, tool versions, and log with the report.

The
[evaluation guide](https://gtd-gmbh.gitlab.io/occtre/evaluation.html)
explains every column, the recorder modes, and this validation guidance.

## Links

* [Documentation](https://gtd-gmbh.gitlab.io/occtre/)
* [Changelog](https://gitlab.com/gtd-gmbh/occtre/-/blob/main/CHANGELOG.md)
* [Repository](https://gitlab.com/gtd-gmbh/occtre)
* [Issue tracker](https://gitlab.com/gtd-gmbh/occtre/-/issues)

## License

The OCCTRE source code implemented by Celeres is licensed under the
[Mozilla Public License 2.0](https://gitlab.com/gtd-gmbh/occtre/-/blob/main/COPYING.md),
identified by the SPDX expression `MPL-2.0`. Third-party libraries remain
subject to their own license terms.

## Development

Setup for the development environment, the test suite, the pre-commit hooks, the
documentation build, and the release build are described in
[CONTRIBUTING.md](https://gitlab.com/gtd-gmbh/occtre/-/blob/main/CONTRIBUTING.md).

