# riscv-vela/vela architecture

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

- Interactive diagram: https://gitdiagram.com/riscv-vela/vela
- Repository: https://github.com/riscv-vela/vela

## Overview

##### Project type and purpose
- This is a small tooling project whose sole purpose is to prepare and launch an Ubuntu virtual machine under QEMU (likely for RISC-V or similar targets since it installs opensbi and u-boot-qemu).
- There is no “application” inside; it’s an environment-provisioning tool.

##### File structure
- README.md: explains dependencies and usage.
- init.sh: prepares an Ubuntu disk image.
- run.sh: launches QEMU with the built image, firmware, bootloader, and network forwarding.

##### README for additional insights
- Dependencies: opensbi, qemu-system-misc, u-boot-qemu.
- Usage:
- `./init.sh` → build a disk image
- `./run.sh` → start QEMU with SBI + U-Boot chain and forward host port 2222 → VM’s SSH 22
- The intended flow: Host packages → init.sh → disk.img → run.sh → VM up → ssh.

##### Main components
a. Host machine
- OS (e.g., Ubuntu)
- Installed packages: QEMU, OpenSBI, U-Boot
- Scripts: init.sh, run.sh
b. Disk image preparation
- init.sh steps (e.g., debootstrap or `dd` operations → ubuntu.img)
c. Emulation/VM stack (run.sh)
- QEMU process
- OpenSBI firmware
- U-Boot bootloader
- Kernel and initrd inside ubuntu.img
d. Networking
- QEMU user-mode or TAP networking
- Host port 2222 forwarded → VM port 22
e. Client interaction
- SSH client on host → SSH server in VM

##### Relationships and interactions
- init.sh writes and configures ubuntu.img
- run.sh invokes `qemu-system-...` with flags pointing to:
- OpenSBI binary (–bios)
- U-Boot binary (–kernel or –bios chain)
- Disk image (–drive file=ubuntu.img)
- Network forwarding (–net user,hostfwd=…)
- QEMU spawns a virtual machine, OpenSBI hands off to U-Boot, which loads the Linux kernel from the disk image.
- The VM runs SSHd; the host’s SSH client connects via localhost:2222.

##### Architectural patterns and design principles
- Clear separation of concerns:
- Image preparation (init.sh)
- VM provisioning (run.sh)
- Boot chain layering: OpenSBI → U-Boot → Linux Kernel → Userland
- Reproducibility: script-driven, minimal manual steps
- Network isolation with controlled port forwarding

##### Technologies, frameworks, libraries
- QEMU system emulator
- OpenSBI (RISC-V SBI implementation)
- U-Boot (bootloader)
- Ubuntu disk image & debootstrap (presumed in init.sh)
- SSH (network service)

##### Essential details to capture
- The bootloader chain (OpenSBI → U-Boot → Linux)
- The fact that init.sh is decoupled from run.sh
- The network forwarding configuration
- Which binary flags in run.sh point to which components

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Host Tooling"
        OS["Host OS\nUbuntu"]:::hostTooling
        DOC["README.md"]:::hostTooling
        SCRIPT_INIT["init.sh"]:::hostTooling
        SCRIPT_RUN["run.sh"]:::hostTooling
    end

    subgraph "Disk Image Preparation"
        SCRIPT_INIT -->|"creates"| IMG["ubuntu.img"]:::disk
    end

    subgraph "VM Provisioning"
        SCRIPT_RUN -->|"invokes"| QC["QEMU Emulator"]:::hostTooling
    end

    subgraph "Firmware & Bootloader Chain"
        QC -->|"loads BIOS"| SBI["OpenSBI"]:::firmware
        SBI -->|"handoff"| UBOOT["U-Boot"]:::firmware
        UBOOT -->|"loads"| KERN["Linux Kernel + Userland"]:::guest
    end

    KERN -->|"runs SSHd"| SSHD["SSH Server (VM)"]:::guest
    SSHC["SSH Client (Host)"]:::hostTooling -->|"ssh localhost:2222"| NET[/ "Port Forward 2222↔22" /]:::network
    NET -->|"connects"| SSHD

    click DOC "https://github.com/riscv-vela/vela/blob/ubuntu/README.md"
    click SCRIPT_INIT "https://github.com/riscv-vela/vela/blob/ubuntu/init.sh"
    click SCRIPT_RUN "https://github.com/riscv-vela/vela/blob/ubuntu/run.sh"

    classDef hostTooling fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef disk fill:#FDEDEC,stroke:#922B21,color:#641E16
    classDef firmware fill:#FEF9E7,stroke:#B7950B,color:#7D6608
    classDef guest fill:#EAFAF1,stroke:#239B56,color:#186A3B
    classDef network fill:#EBF5FB,stroke:#21618C,color:#1B4F72
```
