# secworks/gcm architecture

> Architecture diagram of the GitHub repository secworks/gcm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/secworks/gcm
- Repository: https://github.com/secworks/gcm

## Overview

##### Project type and purpose
- This is an RTL hardware project implementing the Galois/Counter Mode (GCM) block‐cipher mode for AES (128/256-bit keys, 64/96/128-bit tag).
- It consists of Verilog RTL modules, testbenches, a Python reference model for the Galois multiplication (gcm_gmult.py), and a Makefile driving builds, linting, and simulation.

##### File structure
- src/rtl: contains the Verilog source
- gcm.v          ← top-level wrapper for GCM
- gcm_core.v     ← core datapath + control, instantiates an AES submodule
- gcm_ghash.v    ← GHASH multiplier and accumulator
- src/model: Python golden-reference for the Galois multiplication
- src/tb: testbenches for each module (tb_gcm.v, tb_gcm_core.v, tb_gcm_ghash.v)
- toolruns/Makefile: build targets for simulation, linting, maybe synthesis

##### README for additional insights
- The GHASH module is incomplete.
- The top-level and core are under active development; AES instance is integrated in gcm_core.v.
- There is a testbench for the top level to validate basic connectivity.
- Uses standard NIST and IETF references for behavior.

##### Elements
- Clear labels: module names, bus widths, signal names.
- Rectangles for RTL modules
- Rounded rectangles for external models (Python)
- Clouds for toolchain (Makefile, simulator, lint)
- Clock/reset distribution: show a global clock net feeding all modules.

##### Detailed capture of essential architecture
- Top-level I/O (AES data interface, key load interface, IV load, start/done signals).
- Drill into gcm_core.v: separate the AES submodule block, the input counter logic, and the FSM steering rounds.
- Python gcm_gmult model to gcm_ghash for golden-model comparison in your simulation flow.
- Finally, illustrate the Makefile targets: “make sim” to run tb_gcm.v, “make lint,” etc., linked to the RTL and testbench components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clock and Reset
    clk["Clock"]:::signal
    rst["Reset"]:::signal

    %% Top-Level Module
    Top["GCM Top Level\ndata_in[127:0], key, IV, start/done, ciphertext, tag_out"]:::rtl
    click Top "https://github.com/secworks/gcm/blob/master/src/rtl/gcm.v"

    %% Hierarchy: Core and GHASH
    subgraph "GCM Core Module" 
        Core["GCM Core\nAES rounds datapath + Control FSM"]:::rtl
        click Core "https://github.com/secworks/gcm/blob/master/src/rtl/gcm_core.v"
        subgraph "AES Submodule"
            AES["AES Submodule\n(128/256-bit)"]:::rtl
            click AES "https://github.com/secworks/gcm/blob/master/src/rtl/gcm_core.v"
        end
        FSM["Control FSM"]:::ctrl
        Counter["Counter Logic"]:::dp
    end

    GHASH["GHASH Module\nMultiplier + Accumulator"]:::rtl
    click GHASH "https://github.com/secworks/gcm/blob/master/src/rtl/gcm_ghash.v"

    %% Python Golden Model
    Python["Python Galois Model"]:::ext
    click Python "https://github.com/secworks/gcm/blob/master/src/model/gcm_gmult.py"

    %% Testbenches
    subgraph "Testbench Environment"
        TBTop["tb_gcm.v"]:::tb
        click TBTop "https://github.com/secworks/gcm/blob/master/src/tb/tb_gcm.v"
        TBCore["tb_gcm_core.v"]:::tb
        click TBCore "https://github.com/secworks/gcm/blob/master/src/tb/tb_gcm_core.v"
        TBGHASH["tb_gcm_ghash.v"]:::tb
        click TBGHASH "https://github.com/secworks/gcm/blob/master/src/tb/tb_gcm_ghash.v"
    end

    %% Toolchain
    Tools["Makefile & Toolchain\n(sim, lint, synth)"]:::tool
    click Tools "https://github.com/secworks/gcm/tree/master/toolruns/Makefile"

    %% Connections
    clk --> Top
    rst --> Top

    Top -->|"data & control"| Core
    Core -->|"ciphertext"| Top
    Core -->|"tag_partial"| GHASH
    Core -->|"counter value"| Counter
    Core --> AES
    FSM --> AES
    Counter --> AES

    GHASH -->|"tag_final"| Top

    GHASH -.verification.-> Python

    TBTop --> Top
    TBCore --> Core
    TBGHASH --> GHASH

    Tools --> TBTop
    Tools --> TBCore
    Tools --> TBGHASH
    Tools --> Top
    Tools --> Core
    Tools --> GHASH

    %% Styles
    classDef rtl fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef ctrl fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef dp fill:#D5F5E3,stroke:#27AE60,color:#1D8348;
    classDef ext fill:#FADBD8,stroke:#C0392B,color:#78281F;
    classDef tb fill:#D6EAF8,stroke:#2471A3,color:#154360;
    classDef tool fill:#E8DAEF,stroke:#8E44AD,color:#512E5F;
    classDef signal fill:#F4F6F7,stroke:#ABB2B9,color:#566573;
```
