# lichtfeind/ch56x-svd-patch architecture

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

- Interactive diagram: https://gitdiagram.com/lichtfeind/ch56x-svd-patch
- Repository: https://github.com/lichtfeind/ch56x-svd-patch

## Overview

##### Project type and purpose
- This is a CLI-driven code-generation pipeline specialized in taking a vendor SVD (System View Description) for the CH569/CH565 microcontrollers, applying a series of patches (via YAML definitions), and then generating a Rust hardware-access crate via svd2rust.
- Its purpose is to correct and augment the raw SVD file, then produce a tidy, idiomatic Rust Peripheral Access Crate (PAC).

##### File structure
- Top-level scripts:
- build.sh        – orchestrates the full build: fetch, patch, generate, format, package
- patch.sh        – applies YAML-based patches to the raw SVD
- Configuration and data:
- CH56Xxx.svd.sha1, CH56Xxx.svd – the input SVD and its checksum
- ch569-rs.toml   – toml settings for svd2rust/form
- Patch definitions:
- devices/ch569.yaml           – device-wide patches (register blocks, addresses)
- peripherals/*.yaml           – individual peripheral patches (fields, enums)
- Licenses, README, and build instructions sit at the top level.
- There are no “frontend”/“backend” folders—this is a standalone generation tool.

##### Key insights from the README
- External toolchain dependencies: wget, svdtools, svd2rust, form, cargo, rustfmt.
- Workflow: fetch original SVD → verify checksum → run patch.sh → run build.sh to drive svd2rust → output Rust code.
- The project is WIP and relies heavily on YAML patches to correct the baseline SVD.

a. Main components
1. Input SVD source
2. Patch Engine (patch.sh + YAML definitions)
3. svd2rust code generator (+ form, rustfmt)
4. Cargo packaging tool
5. Output: Rust PAC crate
6. External services/tools: wget, svdtools
b. Relationships & data flow
- build.sh starts → invokes wget (if needed) to retrieve SVD
↓
- patch.sh reads CH56Xxx.svd + devices/*.yaml + peripherals/*.yaml → svdtools transforms → produces patched SVD
↓
- svd2rust (with ch569-rs.toml) generates Rust source → form and rustfmt format it
↓
- cargo package/publish produces final crate
c. Architectural patterns & design principles
– Pipeline pattern: discrete stages chained by scripts
– Configuration-as-code: patches are pure YAML, easily extended
– Idempotent, reproducible builds driven by shell scripts
d. Key technologies
– Shell scripting (bash)
– YAML (patch definitions)
– svdtools (Python SVD manipulation)
– svd2rust & form (Rust codegen)
– cargo & rustfmt (Rust packaging/formatting)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Scripts
    subgraph "Scripts"
        Build["build.sh"]:::script
        Patch["patch.sh"]:::script
    end

    %% Data and Configuration
    subgraph "Data & Config"
        SVD["CH56Xxx.svd"]:::data
        SVDsha["CH56Xxx.svd.sha1"]:::data
        TOML["ch569-rs.toml"]:::config
    end

    %% Patch Definitions
    subgraph "Patch Definitions"
        DeviceYAML["devices/ch569.yaml"]:::yaml
        EmmcYAML["peripherals/emmc.yaml"]:::yaml
        GpioYAML["peripherals/gpio.yaml"]:::yaml
        PficYAML["peripherals/pfic.yaml"]:::yaml
        PwmxYAML["peripherals/pwmx.yaml"]:::yaml
        SysYAML["peripherals/sys.yaml"]:::yaml
        TmrYAML["peripherals/tmr.yaml"]:::yaml
        UartYAML["peripherals/uart.yaml"]:::yaml
        UsbhsYAML["peripherals/usbhs.yaml"]:::yaml
        UsbssYAML["peripherals/usbss.yaml"]:::yaml
    end

    %% External Tools
    subgraph "External Tools"
        Wget["wget"]:::tool
        SVDTools["svdtools"]:::tool
        SVD2Rust["svd2rust"]:::tool
        Form["form"]:::tool
        RustFmt["rustfmt"]:::tool
        Cargo["cargo"]:::tool
    end

    %% Project Metadata
    subgraph "Metadata"
        LicenseAP["LICENSE-APACHE"]:::data
        LicenseMIT["LICENSE-MIT"]:::data
        Readme["README.md"]:::data
    end

    %% Output
    Output["Rust PAC Crate"]:::output

    %% Connections
    Build -->|"invokes"| Wget
    Wget -->|"fetches"| SVD
    Wget -->|"fetches"| SVDsha
    Build -->|"invokes"| Patch
    SVD -->|"input to"| Patch
    SVDsha -->|"verified by"| Patch
    DeviceYAML -->|"used by"| Patch
    EmmcYAML -->|"used by"| Patch
    GpioYAML -->|"used by"| Patch
    PficYAML -->|"used by"| Patch
    PwmxYAML -->|"used by"| Patch
    SysYAML -->|"used by"| Patch
    TmrYAML -->|"used by"| Patch
    UartYAML -->|"used by"| Patch
    UsbhsYAML -->|"used by"| Patch
    UsbssYAML -->|"used by"| Patch
    SVDTools -->|"transforms"| Patch
    Patch -->|"generates patched SVD"| SVD2Rust
    TOML -->|"configures"| SVD2Rust
    SVD2Rust -->|"generates Rust code"| Form
    Form -->|"formats code"| RustFmt
    RustFmt -->|"packages"| Cargo
    Cargo -->|"outputs crate"| Output

    %% Click Events
    click Build "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/build.sh"
    click Patch "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/patch.sh"
    click SVD "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/CH56Xxx.svd"
    click SVDsha "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/CH56Xxx.svd.sha1"
    click TOML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/ch569-rs.toml"
    click DeviceYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/devices/ch569.yaml"
    click EmmcYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/emmc.yaml"
    click GpioYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/gpio.yaml"
    click PficYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/pfic.yaml"
    click PwmxYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/pwmx.yaml"
    click SysYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/sys.yaml"
    click TmrYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/tmr.yaml"
    click UartYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/uart.yaml"
    click UsbhsYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/usbhs.yaml"
    click UsbssYAML "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/peripherals/usbss.yaml"
    click LicenseAP "https://github.com/lichtfeind/ch56x-svd-patch/tree/main/LICENSE-APACHE"
    click LicenseMIT "https://github.com/lichtfeind/ch56x-svd-patch/tree/main/LICENSE-MIT"
    click Readme "https://github.com/lichtfeind/ch56x-svd-patch/blob/main/README.md"

    %% Styles
    classDef script fill:#aed9e0,stroke:#333,stroke-width:1px
    classDef data fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef config fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef yaml fill:#f0f4c3,stroke:#333,stroke-width:1px
    classDef tool fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef output fill:#f8bbd0,stroke:#333,stroke-width:1px
```
