# tuoreste/evaluating-necessary-instrumentation-for-verification architecture

> Architecture diagram of the GitHub repository tuoreste/evaluating-necessary-instrumentation-for-verification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuoreste/evaluating-necessary-instrumentation-for-verification
- Repository: https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification

## Overview

This repository evaluates MPI verification instrumentation: MPI test programs are compiled and instrumented with CoVer, then executed to observe race violations; the minimizer removes memory callbacks one at a time and records which removals preserve detection. A separate LLVM pass lists or removes callbacks by ID. The README documents interactive CoVer use, while the sampled scripts show the automated IR, linking, and minimization workflow. The sampled code does not establish that the custom pass is wired into that workflow, so no such connection is asserted.

Main entry points: [`scripts/cover/cover_ir.py`](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/cover_ir.py) (CoVer IR driver), [`scripts/minimize.py`](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/minimize.py) (Callback minimizer), [`pass/src/RemoveCallbacks.cpp`](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/pass/src/RemoveCallbacks.cpp) (RemoveCallbacks pass), [`scripts/cover/link_ir.py`](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/link_ir.py) (IR linker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["MPI test inputs"]
  node_test_programs["MPI test programs"]
end

subgraph group_instrumentation["Instrumentation and IR"]
  node_cover_script["CoVer IR driver<br/>[cover_ir.py]"]
  node_instrumented_ir["Instrumented LLVM IR"]
  node_linker_script["IR linker<br/>[link_ir.py]"]
  node_link_shell["IR link launcher<br/>[link_ir.sh]"]
end

subgraph group_evaluation["Execution and minimization"]
  node_mpi_program["Instrumented MPI program"]
  node_minimizer["Callback minimizer<br/>[minimize.py]"]
  node_results["Evaluation results"]
end

subgraph group_analysis["Callback analysis"]
  node_callback_pass["RemoveCallbacks pass"]
  node_callback_ids["Callback ID file"]
end

node_user(("Engineer"))
node_cover["CoVer toolchain"]
node_mpi_runtime["MPI runtime"]
node_llvm["LLVM opt"]

node_user -->|"selects tests"| node_test_programs
node_user -->|"runs instrumentation"| node_cover_script
node_cover_script -->|"compiles"| node_test_programs
node_cover_script -->|"invokes instrumentation"| node_cover
node_cover_script -->|"writes IR"| node_instrumented_ir
node_cover_script -->|"invokes linker"| node_linker_script
node_linker_script -->|"reads IR"| node_instrumented_ir
node_linker_script -->|"links executable"| node_mpi_program
node_user -->|"runs minimization"| node_minimizer
node_minimizer -->|"rebuilds trials"| node_link_shell
node_minimizer -->|"runs trials"| node_mpi_runtime
node_minimizer -->|"writes minimized IR and summary"| node_results
node_user -.->|"runs LLVM pass"| node_callback_pass
node_llvm -->|"loads plugin"| node_callback_pass
node_callback_pass -->|"scans callbacks"| node_instrumented_ir
node_callback_pass -->|"reads removal IDs"| node_callback_ids

click node_test_programs "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/tests"
click node_cover_script "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/cover_ir.py"
click node_instrumented_ir "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/results"
click node_linker_script "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/link_ir.py"
click node_mpi_program "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/results"
click node_minimizer "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/minimize.py"
click node_link_shell "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/link_ir.sh"
click node_results "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/results"
click node_callback_pass "https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/pass/src/RemoveCallbacks.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_test_programs toneBlue
class node_cover_script,node_instrumented_ir,node_linker_script,node_link_shell toneAmber
class node_mpi_program,node_minimizer,node_results toneMint
class node_callback_pass,node_callback_ids toneRose
class node_user,node_cover,node_mpi_runtime,node_llvm toneIndigo
```

## Components

### MPI test inputs

- [MPI test programs](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/tests): `tests`

### Instrumentation and IR

- [CoVer IR driver](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/cover_ir.py): `scripts/cover/cover_ir.py`
- [Instrumented LLVM IR](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/results): `results`
- [IR linker](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/link_ir.py): `scripts/cover/link_ir.py`
- [IR link launcher](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/cover/link_ir.sh): `scripts/cover/link_ir.sh`

### Execution and minimization

- [Instrumented MPI program](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/results): `results`
- [Callback minimizer](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/scripts/minimize.py): `scripts/minimize.py`
- [Evaluation results](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/tree/main/results): `results`

### Callback analysis

- [RemoveCallbacks pass](https://github.com/tuoreste/evaluating-necessary-instrumentation-for-verification/blob/main/pass/src/RemoveCallbacks.cpp): `pass/src/RemoveCallbacks.cpp`
- **Callback ID file**

### Other components

- **Engineer**
- **CoVer toolchain**
- **MPI runtime**
- **LLVM opt**

## Connections

- Engineer → MPI test programs: selects tests (evidence: `README.md`)
- Engineer → CoVer IR driver: runs instrumentation (evidence: `README.md`)
- CoVer IR driver → MPI test programs: compiles (evidence: `scripts/cover/cover_ir.py`)
- CoVer IR driver → CoVer toolchain: invokes instrumentation (evidence: `scripts/cover/cover_ir.py`)
- CoVer IR driver → Instrumented LLVM IR: writes IR (evidence: `scripts/cover/cover_ir.py`)
- CoVer IR driver → IR linker: invokes linker (evidence: `scripts/cover/cover_ir.py`)
- IR linker → Instrumented LLVM IR: reads IR (evidence: `scripts/cover/link_ir.py`)
- IR linker → Instrumented MPI program: links executable (evidence: `scripts/cover/link_ir.py`)
- Engineer → Callback minimizer: runs minimization (evidence: `scripts/minimize.py`)
- Callback minimizer → IR link launcher: rebuilds trials (evidence: `scripts/minimize.py`)
- Callback minimizer → MPI runtime: runs trials (evidence: `scripts/minimize.py`)
- Callback minimizer → Evaluation results: writes minimized IR and summary (evidence: `scripts/minimize.py`)
- Engineer → RemoveCallbacks pass: runs LLVM pass
- LLVM opt → RemoveCallbacks pass: loads plugin (evidence: `pass/src/RemoveCallbacks.cpp`)
- RemoveCallbacks pass → Instrumented LLVM IR: scans callbacks (evidence: `pass/src/RemoveCallbacks.cpp`)
- RemoveCallbacks pass → Callback ID file: reads removal IDs (evidence: `pass/src/RemoveCallbacks.cpp`)
