# valrek-sol/scanchain architecture

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

- Interactive diagram: https://gitdiagram.com/valrek-sol/scanchain
- Repository: https://github.com/valrek-sol/scanchain

## Overview

1. **Repository purpose**
   - This repo is a small RTL/DFT experiment, not an application stack.
   - The core goal is to show how a simple sequential design—a 4-bit synchronous counter—can be modified into a **scan-enabled** design for testability.

2. **Main design boundary: functional RTL vs scan RTL**
   - `src/four_bit_counter.v` is the plain functional counter implementation.
   - `src/four_bit_counter_scan.v` is the scan-inserted version, where flip-flops are effectively wrapped with scan capability.
   - The architectural shift is from normal state storage to a design that supports both normal operation and test-mode shifting.

3. **Scan chain structure**
   - The scan version uses a chain of scan DFF behavior: each register bit can load either normal functional data or a scan input through a 2:1 mux.
   - The register outputs are chained so that one flip-flop’s `Q` feeds the next flip-flop’s scan input, enabling serial shift-in and shift-out of internal state.
   - This makes the internal counter state observable and controllable from the outside.

4. **Operational modes**
   - The design has two meaningful modes:
     - **Functional mode:** the counter behaves as a synchronous 4-bit counter.
     - **Scan/test mode:** internal state is shifted through the scan chain using `test_si` and `test_so`-style connectivity.
   - The README describes a capture/shift example using a scan-in pattern of `1010` and checking the resulting shifted-out state.

5. **Verification subsystem**
   - `src/four_bit_counter_scan_tb.v` is the testbench used to stimulate the scan design.
   - It exercises the scan interface and produces simulation output for waveform inspection.
   - `src/scan_sim.vcd` is the waveform dump generated by simulation and viewed in GTKWave.

6. **Synthesis flow**
   - `synth.ys` is the Yosys synthesis script that drives the flow.
   - It reads `four_bit_counter_scan.v`, synthesizes `four_bit_counter_scan` as the top module, and emits both:
     - `src/synth_netlist.v` for gate-level/post-synthesis simulation
     - `src/counter_scan.blif` for logic-network export
   - `src/synth_stats.txt` captures synthesis statistics, which is useful for understanding how the scan logic affects cell count and structure.

7. **Post-synthesis simulation boundary**
   - The repo explicitly separates RTL-level scan behavior from synthesized netlist behavior.
   - `src/post_synth_sim` is the executable produced by Icarus Verilog using the synthesized netlist plus the testbench.
   - This gives a check that the scan behavior still works after synthesis, not just at the RTL level.

8. **Toolchain dependency**
   - The architecture depends on a standard open-source EDA flow:
     - **Yosys** for synthesis and netlist generation
     - **Icarus Verilog** for simulation
     - **GTKWave** for waveform debug
   - These tools are not part of the design itself, but they define the repo’s build/analysis pipeline.

9. **Generated vs source artifacts**
   - Source files are the hand-authored RTL, testbench, and synthesis script.
   - Generated artifacts are the netlist, BLIF, statistics, waveform, and simulation executable.
   - For an architecture diagram, it helps to draw a clear boundary between authored design inputs and tool-generated outputs.

10. **Overall data flow**
   - RTL scan design → Yosys synthesis → synthesized netlist/BLIF/stats → Icarus simulation with testbench → VCD waveform → GTKWave inspection.
   - The key architectural idea is that the scan chain provides a controllable path into and out of sequential state, enabling deterministic test access to the counter’s internal registers.

11. **What this repo is demonstrating**
   - This is a pedagogical DFT example rather than a production scan insertion flow.
   - The emphasis is on understanding the mechanics of scan chains in a small sequential circuit and validating them through synthesis and simulation.

Main entry points: [`src/four_bit_counter_scan.v`](https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter_scan.v) (Scan counter), [`README.md`](https://github.com/valrek-sol/scanchain/blob/master/README.md) (README), [`src/four_bit_counter_scan_tb.v`](https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter_scan_tb.v) (Testbench), [`src/post_synth_sim`](https://github.com/valrek-sol/scanchain/tree/master/src/post_synth_sim) (Post-synth sim)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Authored RTL"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_counter["Counter<br/>rtl<br/>[four_bit_counter.v]"]
  node_scan_counter["Scan counter<br/>rtl"]
  node_tb["Testbench<br/>sim"]
  node_synth_script["Synthesis script<br/>flow script<br/>[synth.ys]"]
end

subgraph group_flow["Tool Flow"]
  node_yosys{{"Yosys<br/>synth tool"}}
  node_iverilog{{"Icarus Verilog<br/>sim tool"}}
  node_gtkwave{{"GTKWave<br/>wave viewer"}}
end

subgraph group_generated["Generated Artifacts"]
  node_synth_netlist["Netlist<br/>post-synth v<br/>[synth_netlist.v]"]
  node_blif["BLIF<br/>logic export<br/>[counter_scan.blif]"]
  node_stats["Stats<br/>synth report<br/>[synth_stats.txt]"]
  node_post_sim["Post-synth sim<br/>sim binary"]
  node_vcd["VCD<br/>waveform<br/>[scan_sim.vcd]"]
  node_diagram["Synthesis diagram<br/>dot graph<br/>[synth_diagram.dot]"]
end

node_readme -->|"describes"| node_counter
node_readme -->|"explains"| node_scan_counter
node_readme -->|"shows"| node_tb
node_readme -->|"outlines"| node_synth_script
node_counter -->|"baseline"| node_scan_counter
node_scan_counter -->|"verified by"| node_tb
node_scan_counter -->|"input"| node_synth_script
node_synth_script -->|"drives"| node_yosys
node_yosys -->|"emits"| node_synth_netlist
node_yosys -->|"emits"| node_blif
node_yosys -->|"reports"| node_stats
node_synth_netlist -->|"linked into"| node_post_sim
node_tb -->|"drives"| node_post_sim
node_post_sim -->|"dumps"| node_vcd
node_vcd -->|"viewed in"| node_gtkwave
node_tb -->|"run by"| node_iverilog
node_iverilog -->|"builds"| node_post_sim
node_scan_counter -->|"visualized by"| node_diagram

click node_readme "https://github.com/valrek-sol/scanchain/blob/master/README.md"
click node_counter "https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter.v"
click node_scan_counter "https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter_scan.v"
click node_tb "https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter_scan_tb.v"
click node_synth_script "https://github.com/valrek-sol/scanchain/blob/master/synth.ys"
click node_synth_netlist "https://github.com/valrek-sol/scanchain/blob/master/src/synth_netlist.v"
click node_blif "https://github.com/valrek-sol/scanchain/blob/master/src/counter_scan.blif"
click node_stats "https://github.com/valrek-sol/scanchain/blob/master/src/synth_stats.txt"
click node_post_sim "https://github.com/valrek-sol/scanchain/tree/master/src/post_synth_sim"
click node_vcd "https://github.com/valrek-sol/scanchain/blob/master/src/scan_sim.vcd"
click node_diagram "https://github.com/valrek-sol/scanchain/blob/master/src/synth_diagram.dot"

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_readme,node_counter,node_scan_counter,node_tb,node_synth_script toneBlue
class node_yosys,node_iverilog,node_gtkwave toneAmber
class node_synth_netlist,node_blif,node_stats,node_post_sim,node_vcd,node_diagram toneMint
```

## Components

### Authored RTL

Hand-written design, testbench, and flow script.

- [README](https://github.com/valrek-sol/scanchain/blob/master/README.md): docs · Explains the scan-chain example and workflow. · `README.md`
- [Counter](https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter.v): rtl · Plain 4-bit synchronous counter. · `src/four_bit_counter.v`
- [Scan counter](https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter_scan.v): rtl · 4-bit counter with scan-inserted state storage. · `src/four_bit_counter_scan.v`
- [Testbench](https://github.com/valrek-sol/scanchain/blob/master/src/four_bit_counter_scan_tb.v): sim · Stimulus for scan and post-synthesis simulation. · `src/four_bit_counter_scan_tb.v`
- [Synthesis script](https://github.com/valrek-sol/scanchain/blob/master/synth.ys): flow script · Yosys script that drives synthesis of the scan design. · `synth.ys`

### Tool Flow

Synthesis and simulation tools that transform the design.

- **Yosys**: synth tool · Synthesizes RTL into netlist and BLIF outputs.
- **Icarus Verilog**: sim tool · Runs RTL and gate-level simulation.
- **GTKWave**: wave viewer · Inspects dumped simulation waveforms.

### Generated Artifacts

Outputs produced by synthesis and simulation.

- [Netlist](https://github.com/valrek-sol/scanchain/blob/master/src/synth_netlist.v): post-synth v · Synthesized Verilog netlist for gate-level simulation. · `src/synth_netlist.v`
- [BLIF](https://github.com/valrek-sol/scanchain/blob/master/src/counter_scan.blif): logic export · Logic-network export from synthesis. · `src/counter_scan.blif`
- [Stats](https://github.com/valrek-sol/scanchain/blob/master/src/synth_stats.txt): synth report · Synthesis statistics for the scan design. · `src/synth_stats.txt`
- [Post-synth sim](https://github.com/valrek-sol/scanchain/tree/master/src/post_synth_sim): sim binary · Executable that simulates the synthesized netlist with the testbench. · `src/post_synth_sim`
- [VCD](https://github.com/valrek-sol/scanchain/blob/master/src/scan_sim.vcd): waveform · Simulation waveform dump for debug. · `src/scan_sim.vcd`
- [Synthesis diagram](https://github.com/valrek-sol/scanchain/blob/master/src/synth_diagram.dot): dot graph · Graphviz view of the synthesized structure. · `src/synth_diagram.dot`

## Connections

- README → Counter: describes · Documents the functional counter baseline.
- README → Scan counter: explains · Documents the scan-enabled variant and test mode.
- README → Testbench: shows · Describes the scan testbench and capture/shift example.
- README → Synthesis script: outlines · Explains the synthesis flow and emitted artifacts.
- Counter → Scan counter: baseline · Functional RTL is the starting point for scan insertion.
- Scan counter → Testbench: verified by · The testbench exercises scan-in and scan-out behavior.
- Scan counter → Synthesis script: input · The scan RTL is the synthesis target.
- Synthesis script → Yosys: drives · Yosys executes the synthesis flow.
- Yosys → Netlist: emits · Produces the synthesized Verilog netlist.
- Yosys → BLIF: emits · Produces a BLIF logic-network export.
- Yosys → Stats: reports · Produces synthesis statistics.
- Netlist → Post-synth sim: linked into · The synthesized netlist is used for gate-level simulation.
- Testbench → Post-synth sim: drives · The testbench stimulates the post-synthesis executable.
- Post-synth sim → VCD: dumps · Simulation generates a waveform trace.
- VCD → GTKWave: viewed in · Waveform output is inspected in GTKWave.
- Testbench → Icarus Verilog: run by · Icarus Verilog compiles and runs the simulation.
- Icarus Verilog → Post-synth sim: builds · Produces the post-synthesis simulation executable.
- Scan counter → Synthesis diagram: visualized by · A structural diagram of the synthesized scan logic.