# rakeshmonkee/dma architecture

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

- Interactive diagram: https://gitdiagram.com/rakeshmonkee/dma
- Repository: https://github.com/rakeshmonkee/dma

## Overview

##### Project Type and Purpose
- This is primarily an educational “guide” repository for DMA firmware creation, flashing, and troubleshooting, augmented by a small set of helper scripts (Vivado customization, COE conversion).
- It’s not a classic full-stack web app or microservice suite but a “pipeline plus documentation” project that walks a user through firmware generation, bitstream conversion, device flashing, speed testing, and troubleshooting.

##### File-Structure Analysis
- Top-level directories each correspond to a stage or topic in the guide:
- “Vivado Customisations” – Python and TCL scripts to auto-generate FPGA/Vivado projects
- “.tlscan to .coe” – Python script to convert scan data into COE memory‐init files
- “Anti-Cheese FW Creation” & “VGK FW Creation” – user exercises for crafting two styles of DMA firmware
- “How to Flash” – archived tools (CH341PAR, OpenOCD builds, etc.) and instructions for flashing the firmware onto devices
- “Speed Test” – sample test harness and data for validating DMA throughput
- “DMA FAQ” & “DMA Troubleshooting” – static Markdown FAQs and common‐issue walk-throughs
- Configuration files and scripts are clearly separated from static docs and archives.

##### Key Components
a. Input & Preparation
- Hardware design files or exported scan data (e.g. from real device)
- Vivado scripts (.py, .tcl) in “Vivado Customisations”
b. Bitstream & Memory Init Generation
- Vivado runs → generates .bit or .elf → outputs raw memory data
- .tlscan to .coe script converts scan dumps into .coe format
c. Firmware Creation
- Two parallel flows: “Anti-Cheese FW Creation” and “VGK FW Creation”
- Each produces a custom DMA firmware image (hex, bin)
d. Flashing Tools & Processes
- CH341PAR, GhostDMA‐OpenOCD, MVPDMA, flash_screamer archives
- User runs host‐PC tools to write firmware image to hardware over USB/JTAG
e. Verification & Troubleshooting
- Speed Test harness measures throughput
- DMA FAQ & Troubleshooting docs guide the user through issues

##### Relationships & Data Flow
- Sequential pipeline:
1. Hardware Scan →
2. Vivado Project →
3. Bitstream/Mem-Init →
4. Firmware Creation →
5. Flashing →
6. Speed Test →
7. Troubleshooting
- Branch for two firmware types (Anti-Cheese vs VGK) after Mem-Init

##### Architectural Patterns & Design Principles
- Clear separation of concerns:
- “Generation” (Vivado + COE)
- “Firmware logic” (two custom flows)
- “Deployment” (flashing tools)
- “Validation & Support” (tests + docs)
- Modularity: each top-level folder is a self-contained guide or script set
- Reusability: .tlscan→.coe and Vivado scripts can be reused across firmware flows

##### Technologies & Frameworks to Highlight
- Python scripts for automation (“Vivado.py”, “generate-project.py”, “telescan_to_coe.py”)
- Tcl scripting for Vivado .tcl automation
- FPGA/Vivado toolchain producing .bit/.coe
- Host-side flashing utilities (CH341 drivers, OpenOCD variants, GhostDMA)
- Markdown docs as the primary user interface

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Preparation"
        A["Hardware Scan Data"]:::script
    end

    subgraph "Generation"
        B["Vivado Automation Scripts\n(Vivado Customisations/)"]:::script
        C["Scan-to-COE Conversion\n(telescan_to_coe.py)"]:::script
    end

    subgraph "Firmware Creation"
        D["Anti-Cheese FW Creation"]:::firmware
        E["VGK FW Creation"]:::firmware
    end

    subgraph "Deployment"
        F["Flashing Tools & Processes"]:::tools
    end

    subgraph "Validation & Support"
        G["Throughput Verification\n(Speed Test)"]:::tools
        H["DMA FAQ"]:::doc
        I["DMA Troubleshooting"]:::doc
        J["Project Overview"]:::doc
    end

    A --> B
    B -->|"generates .bit/.elf"| C
    C -->|"generates .coe"| D
    C -->|"generates .coe"| E
    D -->|"firmware image (.bin/.hex)"| F
    E -->|"firmware image (.bin/.hex)"| F
    F -->|"flashed via USB/JTAG"| G
    G -->|"results & logs"| H
    H --> I
    I --> G
    J -.-> A

    click A "https://github.com/rakeshmonkee/dma/tree/main/1:1 CFG of real device/"
    click B "https://github.com/rakeshmonkee/dma/tree/main/Vivado Customisations/"
    click C "https://github.com/rakeshmonkee/dma/blob/main/.tlscan to .coe/telescan_to_coe.py"
    click D "https://github.com/rakeshmonkee/dma/tree/main/Anti-Cheese FW Creation/"
    click E "https://github.com/rakeshmonkee/dma/tree/main/VGK FW Creation/"
    click F "https://github.com/rakeshmonkee/dma/tree/main/How to Flash/"
    click G "https://github.com/rakeshmonkee/dma/tree/main/Speed Test/"
    click H "https://github.com/rakeshmonkee/dma/blob/main/DMA FAQ.md"
    click I "https://github.com/rakeshmonkee/dma/blob/main/DMA Troubleshooting/readme.md"
    click J "https://github.com/rakeshmonkee/dma/blob/main/readme.md"

    classDef script fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef firmware fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef tools fill:#FFFF99,stroke:#333,stroke-width:1px;
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
