# nvlabs/nvbitfi architecture

> Architecture diagram of the GitHub repository nvlabs/nvbitfi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvlabs/nvbitfi
- Repository: https://github.com/nvlabs/nvbitfi
- Video tour (about a minute): https://gitdiagram.com/nvlabs/nvbitfi/video

## Overview

NVBitFI is a GPU fault-injection campaign framework for evaluating application resilience. Its main workflow profiles a workload, selects dynamic instruction sites and fault models, executes individual instrumented runs, classifies outcomes, and summarizes campaign results. The graph also preserves the separate PF injector and instruction-group/model definitions. The README documents several capabilities whose implementation was not sampled; those subsystems are represented at their supported directory paths, with uncertain wiring omitted.

Main entry points: [`scripts/run_one_injection.py`](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py) (Single injection run), [`scripts/parse_results.py`](https://github.com/nvlabs/nvbitfi/blob/master/scripts/parse_results.py) (Result parser), [`scripts/common_functions.py`](https://github.com/nvlabs/nvbitfi/blob/master/scripts/common_functions.py) (Profile and environment helpers), [`scripts/run_profiler.py`](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_profiler.py) (Profiler runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_campaign["Campaign orchestration"]
  node_profile_runner["Profiler runner<br/>[run_profiler.py]"]
  node_profile_data["Instruction profile"]
  node_site_generator["Site list generator"]
  node_site_lists["Injection site lists"]
  node_campaign_runner["Campaign dispatcher<br/>[run_injections.py]"]
  node_single_run["Single injection run"]
  node_common_helpers["Profile and environment helpers"]
end

subgraph group_instrumentation["GPU instrumentation"]
  node_profiler["Instruction profiler<br/>[profiler.cu]"]
  node_injector["Instruction injector<br/>[injector.cu]"]
  node_fault_models["Groups and fault models<br/>[arch.h]"]
  node_injector_state["Injection parameters<br/>[injector.h]"]
  node_pf_injector["PF injector variant<br/>[pf_injector.cu]"]
  node_pf_state["PF injection state<br/>[pf_injector.h]"]
end

subgraph group_analysis["Results analysis"]
  node_run_outputs["Run outputs and logs"]
  node_outcome_classifier["Outcome classification"]
  node_result_parser["Result parser<br/>[parse_results.py]"]
  node_summaries["Campaign summaries<br/>[parse_results.py]"]
end

subgraph group_workloads["Workload and configuration"]
  node_workload["GPU workload<br/>[simple_add.cu]"]
  node_workload_scripts["Workload run/check<br/>[run.sh]"]
  node_params["Campaign parameters<br/>[params.py]"]
end

node_user(("Campaign operator"))
node_nvbit["NVBit"]

node_user -->|"starts profiling"| node_profile_runner
node_profile_runner -->|"sets environment"| node_common_helpers
node_profile_runner -->|"runs workload"| node_workload_scripts
node_workload_scripts -->|"launches"| node_workload
node_profile_runner -->|"preloads"| node_profiler
node_profiler -->|"instruments kernels"| node_nvbit
node_profiler -->|"writes counts"| node_profile_data
node_user -->|"generates sites"| node_site_generator
node_site_generator -->|"reads settings"| node_params
node_site_generator -->|"reads profile"| node_common_helpers
node_common_helpers -->|"reads counts"| node_profile_data
node_site_generator -->|"writes selections"| node_site_lists
node_user -->|"launches campaign"| node_campaign_runner
node_campaign_runner -->|"reads settings"| node_params
node_campaign_runner -->|"reads selections"| node_site_lists
node_campaign_runner -->|"dispatches jobs"| node_single_run
node_single_run -->|"reads configuration"| node_params
node_single_run -->|"writes parameters"| node_injector_state
node_single_run -->|"sets environment"| node_common_helpers
node_single_run -->|"runs workload"| node_workload_scripts
node_workload_scripts -->|"preloads"| node_injector
node_injector -->|"instruments kernels"| node_nvbit
node_injector -->|"uses definitions"| node_fault_models
node_injector -->|"uses run state"| node_injector_state
node_single_run -->|"records outputs"| node_run_outputs
node_single_run -->|"classifies run"| node_outcome_classifier
node_outcome_classifier -->|"checks outputs"| node_run_outputs
node_user -->|"parses campaign"| node_result_parser
node_result_parser -->|"reads settings"| node_params
node_result_parser -->|"reads results"| node_run_outputs
node_result_parser -->|"reads profile counts"| node_common_helpers
node_result_parser -->|"writes TSV summaries"| node_summaries
node_pf_injector -.->|"instruments kernels"| node_nvbit
node_pf_injector -->|"uses run state"| node_pf_state

click node_workload "https://github.com/nvlabs/nvbitfi/blob/master/test-apps/simple_add/simple_add.cu"
click node_workload_scripts "https://github.com/nvlabs/nvbitfi/blob/master/test-apps/simple_add/run.sh"
click node_params "https://github.com/nvlabs/nvbitfi/blob/master/scripts/params.py"
click node_profile_runner "https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_profiler.py"
click node_profiler "https://github.com/nvlabs/nvbitfi/blob/master/profiler/profiler.cu"
click node_profile_data "https://github.com/nvlabs/nvbitfi/blob/master/scripts/common_functions.py"
click node_site_generator "https://github.com/nvlabs/nvbitfi/blob/master/scripts/generate_injection_list.py"
click node_site_lists "https://github.com/nvlabs/nvbitfi/blob/master/scripts/generate_injection_list.py"
click node_campaign_runner "https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_injections.py"
click node_single_run "https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py"
click node_injector "https://github.com/nvlabs/nvbitfi/blob/master/injector/injector.cu"
click node_fault_models "https://github.com/nvlabs/nvbitfi/blob/master/common/arch.h"
click node_injector_state "https://github.com/nvlabs/nvbitfi/blob/master/injector/injector.h"
click node_pf_injector "https://github.com/nvlabs/nvbitfi/blob/master/pf_injector/pf_injector.cu"
click node_pf_state "https://github.com/nvlabs/nvbitfi/blob/master/pf_injector/pf_injector.h"
click node_run_outputs "https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py"
click node_outcome_classifier "https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py"
click node_result_parser "https://github.com/nvlabs/nvbitfi/blob/master/scripts/parse_results.py"
click node_summaries "https://github.com/nvlabs/nvbitfi/blob/master/scripts/parse_results.py"
click node_common_helpers "https://github.com/nvlabs/nvbitfi/blob/master/scripts/common_functions.py"

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_profile_runner,node_profile_data,node_site_generator,node_site_lists,node_campaign_runner,node_single_run,node_common_helpers toneBlue
class node_profiler,node_injector,node_fault_models,node_injector_state,node_pf_injector,node_pf_state toneAmber
class node_run_outputs,node_outcome_classifier,node_result_parser,node_summaries toneMint
class node_workload,node_workload_scripts,node_params toneRose
class node_user,node_nvbit toneIndigo
```

## Components

### Campaign orchestration

- [Profiler runner](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_profiler.py): `scripts/run_profiler.py`
- [Instruction profile](https://github.com/nvlabs/nvbitfi/blob/master/scripts/common_functions.py): `scripts/common_functions.py`
- [Site list generator](https://github.com/nvlabs/nvbitfi/blob/master/scripts/generate_injection_list.py): `scripts/generate_injection_list.py`
- [Injection site lists](https://github.com/nvlabs/nvbitfi/blob/master/scripts/generate_injection_list.py): `scripts/generate_injection_list.py`
- [Campaign dispatcher](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_injections.py): `scripts/run_injections.py`
- [Single injection run](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py): `scripts/run_one_injection.py`
- [Profile and environment helpers](https://github.com/nvlabs/nvbitfi/blob/master/scripts/common_functions.py): `scripts/common_functions.py`

### GPU instrumentation

- [Instruction profiler](https://github.com/nvlabs/nvbitfi/blob/master/profiler/profiler.cu): `profiler/profiler.cu`
- [Instruction injector](https://github.com/nvlabs/nvbitfi/blob/master/injector/injector.cu): `injector/injector.cu`
- [Groups and fault models](https://github.com/nvlabs/nvbitfi/blob/master/common/arch.h): `common/arch.h`
- [Injection parameters](https://github.com/nvlabs/nvbitfi/blob/master/injector/injector.h): `injector/injector.h`
- [PF injector variant](https://github.com/nvlabs/nvbitfi/blob/master/pf_injector/pf_injector.cu): `pf_injector/pf_injector.cu`
- [PF injection state](https://github.com/nvlabs/nvbitfi/blob/master/pf_injector/pf_injector.h): `pf_injector/pf_injector.h`

### Results analysis

- [Run outputs and logs](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py): `scripts/run_one_injection.py`
- [Outcome classification](https://github.com/nvlabs/nvbitfi/blob/master/scripts/run_one_injection.py): `scripts/run_one_injection.py`
- [Result parser](https://github.com/nvlabs/nvbitfi/blob/master/scripts/parse_results.py): `scripts/parse_results.py`
- [Campaign summaries](https://github.com/nvlabs/nvbitfi/blob/master/scripts/parse_results.py): `scripts/parse_results.py`

### Workload and configuration

- [GPU workload](https://github.com/nvlabs/nvbitfi/blob/master/test-apps/simple_add/simple_add.cu): `test-apps/simple_add/simple_add.cu`
- [Workload run/check](https://github.com/nvlabs/nvbitfi/blob/master/test-apps/simple_add/run.sh): `test-apps/simple_add/run.sh`
- [Campaign parameters](https://github.com/nvlabs/nvbitfi/blob/master/scripts/params.py): `scripts/params.py`

### Other components

- **Campaign operator**
- **NVBit**

## Connections

- Campaign operator → Profiler runner: starts profiling
- Profiler runner → Profile and environment helpers: sets environment
- Profiler runner → Workload run/check: runs workload
- Workload run/check → GPU workload: launches
- Profiler runner → Instruction profiler: preloads
- Instruction profiler → NVBit: instruments kernels
- Instruction profiler → Instruction profile: writes counts
- Campaign operator → Site list generator: generates sites
- Site list generator → Campaign parameters: reads settings
- Site list generator → Profile and environment helpers: reads profile
- Profile and environment helpers → Instruction profile: reads counts
- Site list generator → Injection site lists: writes selections
- Campaign operator → Campaign dispatcher: launches campaign
- Campaign dispatcher → Campaign parameters: reads settings
- Campaign dispatcher → Injection site lists: reads selections
- Campaign dispatcher → Single injection run: dispatches jobs
- Single injection run → Campaign parameters: reads configuration
- Single injection run → Injection parameters: writes parameters
- Single injection run → Profile and environment helpers: sets environment
- Single injection run → Workload run/check: runs workload
- Workload run/check → Instruction injector: preloads
- Instruction injector → NVBit: instruments kernels
- Instruction injector → Groups and fault models: uses definitions
- Instruction injector → Injection parameters: uses run state
- Single injection run → Run outputs and logs: records outputs
- Single injection run → Outcome classification: classifies run
- Outcome classification → Run outputs and logs: checks outputs
- Campaign operator → Result parser: parses campaign
- Result parser → Campaign parameters: reads settings
- Result parser → Run outputs and logs: reads results
- Result parser → Profile and environment helpers: reads profile counts
- Result parser → Campaign summaries: writes TSV summaries
- PF injector variant → NVBit: instruments kernels
- PF injector variant → PF injection state: uses run state