# 0xharry/rtl2gds architecture

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

- Interactive diagram: https://gitdiagram.com/0xharry/rtl2gds
- Repository: https://github.com/0xharry/rtl2gds

## Overview

The RTL2GDS project is an automated flow that converts RTL (Verilog) designs into GDSII layout files. Based on both the file tree and the README content, this is a specialized EDA tool that integrates synthesis and layout generation using external tools (iEDA and Yosys) along with a custom Python-based flow management system.

##### Main Components to Highlight
- User Input & Design Examples:
- RTL input files (Verilog) and configuration YAML files.
- Design example directory (design_zoo) where several sample designs like “gcd”, “aes”, and “picorv32a” are provided.

- Core Flow Engine (Python-based):
- “src/rtl2gds” directory that contains the main modules:
- The main entrypoint (__main__.py) for launching the flow.
- Chip management (chip.py), design constraints (design_constrain.py), and design path computation (design_path.py).
- The flow orchestration inside “src/rtl2gds/flow” which contains the actual flow logic (rtl2gds_flow.py, cloud_flow.py, step_runner.py).
- “metrics.py” and “global_configs.py” for monitoring and configuring the flow.

- Modular Steps:
- Under “src/rtl2gds/step”, break down different processing steps such as synthesis, floorplanning, placement, and routing.
- These modules (e.g., synthesis.py, floorplan.py, dump_layout_gds.py) represent discrete stages in the RTL to GDSII conversion.

- External Tools Integration:
- iEDA: There is both a prebuilt binary under “bin/iEDA” and several tools/scripts under “tools/iEDA”. This integration is responsible for layout generation aspects.
- Yosys: A prebuilt Yosys binary is provided in “bin/yosys”, including its own support files, which are used for synthesis and Verilog processing.
- Additional conversion/integration tools like sv2v (for SystemVerilog-to-Verilog conversion) appear in “bin/sv2v-Linux”.

- Foundry and Tech Libraries:
- The “foundry/sky130” directory includes LEF, LIB, and verilog files needed to define technology-specific cells and constraints.

- Cloud & Docker Integration:
- The project is designed to run in a containerized environment (with Docker support) as outlined in the README.
- Components such as “cloud_flow.py” in the flow directory indicate that the flow can incorporate cloud execution aspects, probably for scaling or remote processing.

##### Relationships and Interactions
- Flow starting with user-provided RTL and configuration files. These are read by the Python entrypoint.
- The orchestrator then sequences through several steps (synthesis, constraint generation, floorplanning, placement/routing, and finally GDSII generation). Each step is encapsulated in its own module.
- At key points, the orchestrator calls out to external tools (iEDA and Yosys) using prebuilt binaries or scripts found in “bin/” and “tools/iEDA” and “tools/yosys”.
- The foundry files (LEF/Lib/Verilog) feed into the steps to bring technology-specific details into the design.

##### Architectural Patterns and Design Principles
- The project follows a modular, step-based design, essentially an orchestration pattern where the flow is broken into distinct stages that can be developed, tested, and extended independently.
- It uses a clear separation of concerns:
- Input handling and configuration (design_zoo, YAML config files).
- Flow coordination (src/rtl2gds, flow, and step directories).
- Integration with external executables and EDA tools (iEDA, Yosys, and associated scripts).
- The use of Docker and cloud flow modules indicates attention to reproducibility and scalability.

##### Technologies, Frameworks, and Libraries
- Python for flow orchestration and control logic.
- Yosys (open-source synthesis tool) and iEDA (for physical design).
- Docker for environment reproducibility and containerized execution.
- Standard EDA file formats and libraries (LEF, LIB, GDSII).
- Additional utility tools such as klayout (for layout viewing) and third-party Python packages (pyyaml, orjson).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U["User Inputs (RTL & YAML)"]:::input

    %% Flow Orchestrator (Python)
    subgraph "Flow Orchestrator (Python)"
        E["Entrypoint (__main__.py)"]:::orchestrator
        C["Chip Management (chip.py)"]:::orchestrator
        DC["Design Constraints (design_constrain.py)"]:::orchestrator
        DP["Design Path (design_path.py)"]:::orchestrator
        M["Metrics (metrics.py)"]:::orchestrator
        GC["Global Configs (global_configs.py)"]:::orchestrator
        subgraph "Flow Orchestration"
            R["RTL2GDS Flow (rtl2gds_flow.py)"]:::orchestrator
            CF["Cloud Flow (cloud_flow.py)"]:::orchestrator
            SR["Step Runner (step_runner.py)"]:::orchestrator
        end
        CM["Cloud Main (cloud_main.py)"]:::orchestrator
    end

    %% Processing Steps
    subgraph "Processing Steps"
        SY["Synthesis (synthesis.py)"]:::step
        FP["Floorplanning (floorplan.py)"]:::step
        GD["GDSII Dump (dump_layout_gds.py)"]:::step
    end

    %% External Tools
    subgraph "External Tools"
        IE["iEDA Binary"]:::external
        IS["iEDA Scripts"]:::external
        YB["Yosys Binary"]:::external
        YS["Yosys Support (yosys.tcl)"]:::external
        SV["sv2v Converter"]:::external
    end

    %% Foundry/Tech Libraries
    F["Foundry/Tech Libraries (sky130)"]:::foundry

    %% Cloud & Docker
    subgraph "Cloud & Docker"
        DCfg["Docker Config (Dockerfile)"]:::cloud
    end

    %% Final Output
    O["GDSII Layout (Output)"]:::output

    %% Connections
    U -->|"launches"| E
    U --> E
    E --> C
    E --> DC
    E --> DP
    E --> M
    E --> GC
    E --> R
    C --> R
    DC --> R
    DP --> R
    R --> SY
    R --> FP
    R --> GD
    CF --> R
    CM --> CF
    SY -->|"uses"| IE
    SY -->|"calls"| YB
    FP -->|"integrates"| IE
    FP -->|"calls"| YB
    GD -->|"produces"| O
    F -->|"supplies tech data to"| SY
    F --> FP
    F --> GD
    IE --- IS
    YB --- YS
    CF -->|"cloud exec"| DCfg

    %% Styles
    classDef input fill:#f4d03f,stroke:#000,stroke-width:2px
    classDef orchestrator fill:#aed6f1,stroke:#000,stroke-width:2px
    classDef step fill:#d5f5e3,stroke:#000,stroke-width:2px
    classDef external fill:#fadbd8,stroke:#000,stroke-width:2px
    classDef foundry fill:#f9e79f,stroke:#000,stroke-width:2px
    classDef cloud fill:#d2b4de,stroke:#000,stroke-width:2px
    classDef output fill:#f5b7b1,stroke:#000,stroke-width:2px

    %% Click Events
    click U "https://github.com/0xharry/rtl2gds/tree/master/design_zoo/"
    click E "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/__main__.py"
    click C "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/chip.py"
    click DC "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/design_constrain.py"
    click DP "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/design_path.py"
    click M "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/metrics.py"
    click GC "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/global_configs.py"
    click R "https://github.com/0xharry/rtl2gds/tree/master/src/rtl2gds/flow/"
    click SY "https://github.com/0xharry/rtl2gds/tree/master/src/rtl2gds/step/"
    click IE "https://github.com/0xharry/rtl2gds/tree/master/bin/iEDA/"
    click IS "https://github.com/0xharry/rtl2gds/tree/master/tools/iEDA/"
    click YB "https://github.com/0xharry/rtl2gds/tree/master/bin/yosys/"
    click YS "https://github.com/0xharry/rtl2gds/blob/master/tools/yosys/yosys.tcl"
    click SV "https://github.com/0xharry/rtl2gds/tree/master/bin/sv2v-Linux/"
    click F "https://github.com/0xharry/rtl2gds/tree/master/foundry/sky130/"
    click DCfg "https://github.com/0xharry/rtl2gds/tree/master/Dockerfile"
    click CM "https://github.com/0xharry/rtl2gds/blob/master/src/rtl2gds/cloud_main.py"
```
