# oddball/ipxact2systemverilog architecture

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

- Interactive diagram: https://gitdiagram.com/oddball/ipxact2systemverilog
- Repository: https://github.com/oddball/ipxact2systemverilog

## Overview

##### Project type and purpose
- This is an open-source CLI tool (Python package) named “ipxact2systemverilog” that ingests IP-XACT XML descriptions of register banks and emits synthesizable HDL packages (SystemVerilog & VHDL) plus documentation formats (RST, Markdown, C headers).
- Key use cases: on-the-fly code generation, integration into CI pipelines, example verification via simple test benches.

##### File structure
- Top-level directories:
- ipxact2systemverilog/ – core Python package (modules: cli.py, validate.py, ipxact2hdlCommon.py, xml/)
- example/ – sample inputs (XML, INI), expected outputs (docx, h, html, md, pdf, rst, rtf, SV/VHDL packages), and test benches
- Configuration & build:
- setup via pyproject.toml, Makefile (build, compile, sim), .github/workflows/ci.yml
- linting and style: .pep8, .prospector.yaml
- External integrations: uses lxml for XML parsing, docutils for RST, mdutils for Markdown; optional pandoc & Sphinx via Makefile.

##### README for additional insights
- Describes five CLI entry points: ipxact2systemverilog, ipxact2rst, ipxact2md, ipxact2vhdl, ipxact2c
- Notes XML schema validation, example test bench, CI badge, publishing via Twine.
- Mentions dependencies and optional tools for docs/tests.

##### Main components & their relationships
a. CLI Frontend
– Five console scripts.
– Parses flags (--srcFile, --destDir).
b. XML Loader & Validator
– xml/* modules + validate.py.
– Uses lxml to parse and validate against XSD.
c. Intermediate Representation (IR)
– ipxact2hdlCommon.py builds an in-memory model of registers, fields, banks.
d. Generator Plugins
– Separate generator modules invoked by cli.py:
- SystemVerilog generator
- VHDL generator
- RST generator
- Markdown generator
- C header generator
– Each consumes IR and writes files to destDir.
e. Output Artifacts
– HDL packages (.sv, .vh, .vhd), documentation (.rst, .md, .html, .pdf, .docx, etc.).
f. Example/Test Harness
– example/tb/*.sv, *.vhd: simple test benches showing package usage.
– Makefile orchestrates build, compile (Modelsim), sim, docs via pandoc/Sphinx.

##### Architectural patterns and design principles
- Modular plugin pattern: separate generators share a common IR interface.
- Separation of concerns: parsing/validation, model construction, code generation.
- Single responsibility per module.
- CLI-core separation: entry point only handles I/O; core logic is importable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        ipx2sv["ipxact2systemverilog (CLI)"]:::cli
        ipx2rst["ipxact2rst (CLI)"]:::cli
        ipx2md["ipxact2md (CLI)"]:::cli
        ipx2vhdl["ipxact2vhdl (CLI)"]:::cli
        ipx2c["ipxact2c (CLI)"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        Parser["XML Parser modules"]:::core
        Validator["Schema Validator"]:::core
        IR["Intermediate Representation Model"]:::core
    end

    %% Generator Plugins
    subgraph "Generator Plugins"
        SVGen["SystemVerilog Generator"]:::gen
        VHDLGen["VHDL Generator"]:::gen
        RSTGen["RST Generator"]:::gen
        MDGen["Markdown Generator"]:::gen
        CGen["C Header Generator"]:::gen
    end

    %% Output Artifacts
    Artifacts["Output Artifacts (.sv, .vhd, .rst, .md, .html, .pdf, .docx, .h)"]:::artifact

    %% Example/Test Harness
    subgraph "Example/Test Harness"
        TB["Test Benches"]:::example
        SampleIn["Sample Inputs"]:::example
        ExpOut["Expected Outputs"]:::example
        TestCH["Test C Harness"]:::example
        MF["Makefile"]:::build
    end

    %% Build & CI Configuration
    subgraph "Build & CI Configuration"
        PyProj["pyproject.toml"]:::config
        CI["CI Workflow"]:::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        LXML["lxml"]:::external
        Docutils["docutils"]:::external
        MDutils["mdutils"]:::external
        Pandoc["pandoc (optional)"]:::external
        Sphinx["Sphinx (optional)"]:::external
        Models["Modelsim"]:::external
    end

    %% Data Flow
    ipx2sv -->|"parse"| Parser
    ipx2rst -->|"parse"| Parser
    ipx2md -->|"parse"| Parser
    ipx2vhdl -->|"parse"| Parser
    ipx2c -->|"parse"| Parser

    Parser -->|"validate"| Validator
    Validator -->|"build IR"| IR

    IR -->|"generate SV"| SVGen
    IR -->|"generate VHDL"| VHDLGen
    IR -->|"generate RST"| RSTGen
    IR -->|"generate MD"| MDGen
    IR -->|"generate C"| CGen

    SVGen -->|".sv/.vh"| Artifacts
    VHDLGen -->|".vhd"| Artifacts
    RSTGen -->|".rst/.html"| Artifacts
    MDGen -->|".md/.html"| Artifacts
    CGen -->|".h"| Artifacts

    %% Makefile orchestration
    MF -->|"invoke CLI"| ipx2sv
    MF -->|"invoke CLI"| ipx2rst
    MF -->|"invoke CLI"| ipx2md
    MF -->|"invoke CLI"| ipx2vhdl
    MF -->|"invoke CLI"| ipx2c
    MF -->|"build docs"| Pandoc
    MF -->|"build docs"| Sphinx
    MF -->|"run simulation"| Models

    %% CI triggers build
    CI -->|"run Makefile"| MF

    %% Example/Test Harness connections
    TB -->|uses| Artifacts
    SampleIn -->|input to| ipx2sv
    ExpOut -->|compared with| Artifacts
    TestCH -->|compiles with| CGen

    %% External dependency arrows
    Parser -->|uses| LXML
    Validator -->|uses| LXML
    RSTGen -->|uses| Docutils
    MDGen -->|uses| MDutils

    %% Click Events
    click ipx2sv "https://github.com/oddball/ipxact2systemverilog/blob/master/ipxact2systemverilog/cli.py"
    click Parser "https://github.com/oddball/ipxact2systemverilog/tree/master/ipxact2systemverilog/xml/"
    click Validator "https://github.com/oddball/ipxact2systemverilog/blob/master/ipxact2systemverilog/validate.py"
    click IR "https://github.com/oddball/ipxact2systemverilog/blob/master/ipxact2systemverilog/ipxact2hdlCommon.py"
    click TB "https://github.com/oddball/ipxact2systemverilog/tree/master/example/tb/"
    click SampleIn "https://github.com/oddball/ipxact2systemverilog/tree/master/example/input/"
    click ExpOut "https://github.com/oddball/ipxact2systemverilog/tree/master/example/output/"
    click TestCH "https://github.com/oddball/ipxact2systemverilog/blob/master/example/test/example.c"
    click MF "https://github.com/oddball/ipxact2systemverilog/tree/master/Makefile"
    click PyProj "https://github.com/oddball/ipxact2systemverilog/blob/master/pyproject.toml"
    click CI "https://github.com/oddball/ipxact2systemverilog/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef cli fill:#ffe4b2,stroke:#b65c00
    classDef core fill:#bbdefb,stroke:#0d47a1
    classDef gen fill:#c8e6c9,stroke:#1b5e20
    classDef artifact fill:#dcedc8,stroke:#33691e,shape:cylinder
    classDef example fill:#ffecb3,stroke:#ff8f00
    classDef build fill:#ffe082,stroke:#ff6f00
    classDef config fill:#f0f4c3,stroke:#827717
    classDef external fill:#eceff1,stroke:#37474f,stroke-dasharray: 5 5
```
