# xilinx/runx architecture

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

- Interactive diagram: https://gitdiagram.com/xilinx/runx
- Repository: https://github.com/xilinx/runx

## Overview

##### Project Type & Purpose
- RunX is an OCI Runtime Spec–compliant container runtime.
- It lives in Dom0, is invoked by containerd, and creates Xen VMs for isolation.
- It supplies a minimal Linux kernel + BusyBox initrd, or accepts a user-supplied kernel/initrd.

##### File Structure
Top-level entries:
- build.sh, gobuild/Makefile + src/serial_fd_handler.go → build tooling for the Go “RunX” binary
- files/ (start, delete, serial_bridge, serial_start, state) → shell scripts that orchestrate VM lifecycle
- kernel/ (make-*, init-initrd, cutdown-config.*, patches/) → kernel build & customized initrd generation
- runX → the compiled runtime binary
Indicators of architecture:
- A clear Dom0 component (runX + support scripts)
- Kernel toolchain under kernel/
- No in-VM agent: all logic lives in Dom0

##### Pull Insights from the README
- Notes on CNI-based networking, passed via NETCONF env var
- Runtime hooks, no side-channel or in-VM agent

a. Main Components
1. Host / Dom0
- containerd (OCI runtime client)
- RunX binary & support scripts
- xl (Xen CLI)
- CNI plugin (bridge, ipam)
2. Xen Hypervisor
3. VM / DomU per container
- Tiny Linux Kernel (custom configs from kernel/)
- Initrd (BusyBox)
- Container rootfs (from OCI image)
b. Relationships & Interactions
- containerd → invokes RunX (via OCI runtime API)
- RunX → calls xl to create/boot VM
- xl → loads Tiny Kernel + initrd → boots VM
- VM mounts container’s rootfs
- CNI plugin config passed as NETCONF → network namespace config in Dom0 and DomU
c. Architectural Patterns & Principles
- Single-responsibility: RunX handles lifecycle, kernel building delegated to kernel/ scripts
- Micro-VM per container: strict isolation, minimal attack surface
- No in-VM agent: one-way control from Dom0
d. Key Technologies & Libraries
- Go (RunX binary via gobuild)
- Bash scripts (files/)
- Xen hypervisor (xl CLI)
- BusyBox (initrd)
- Kernel toolchain (custom configs + patches)
- CNI v2.0 for networking

##### Capturing Essential Elements
- Be explicit about each module under kernel/ (config generation, patches)
- Build step (gobuild/Makefile) feeding into runX
- How container rootfs is mounted in the VM

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Dom0 Layer
    subgraph "Dom0" 
        direction TB
        Containerd["containerd (OCI runtime client)"]:::dom0
        RunX["RunX: OCI runtime, Go binary"]:::dom0
        subgraph "Build Tooling"
            direction TB
            BuildScript["build.sh"]:::dom0
            GobuildMakefile["gobuild/Makefile"]:::dom0
            SerialFDHandler["serial_fd_handler.go"]:::dom0
        end
        subgraph "Lifecycle Scripts"
            direction TB
            FilesStart["files/start"]:::dom0
            FilesDelete["files/delete"]:::dom0
            FilesSerialBridge["files/serial_bridge"]:::dom0
            FilesSerialStart["files/serial_start"]:::dom0
            FilesState["files/state"]:::dom0
        end
        CNIPlugin["CNI Plugin (bridge, ipam)"]:::dom0
        README["README.md"]:::docs
        DEPENDENCIES["DEPENDENCIES"]:::docs
        LICENSE["LICENSE"]:::docs
    end

    %% Hypervisor Layer
    Xen["Xen Hypervisor (xl CLI)"]:::hypervisor

    %% VM Guest Layer
    subgraph "VM / DomU per container"
        direction TB
        VMGuest["VM Guest"]:::vm
        subgraph "Kernel Toolchain & Initrd"
            direction TB
            MakeKernel["kernel/make-kernel"]:::vm
            MakeInitrd["kernel/make-initrd"]:::vm
            InitInitrd["kernel/init-initrd"]:::vm
            CutConfigX86["kernel/cutdown-config.x86"]:::vm
            CutConfigARM["kernel/cutdown-config.arm"]:::vm
            CutConfigARM64["kernel/cutdown-config.arm64"]:::vm
            Patch1["0001-pvcalls_enable.patch"]:::vm
            Patch2["0002-pvcalls-front-introduce-a-per-sock_mapping-refcount.patch"]:::vm
            Patch3["0003-pvcalls-front-wait-for-other-operations-to-return-wh.patch"]:::vm
            Patch4["0004-patch-arm64_fix.patch"]:::vm
        end
        TinyKernel["Tiny Linux Kernel"]:::vm
        BusyBoxInitrd["BusyBox Initrd"]:::vm
        RootFS["Container RootFS"]:::storage
    end

    %% Connections
    Containerd -->|"invokes"| RunX
    RunX -->|"calls xl"| Xen
    RunX -->|"uses scripts"| FilesStart
    RunX --> FilesDelete
    RunX --> FilesSerialStart
    RunX --> FilesSerialBridge
    RunX --> FilesState
    RunX --> BuildScript
    BuildScript --> GobuildMakefile
    GobuildMakefile --> SerialFDHandler
    Xen -->|"boots"| VMGuest
    VMGuest --> TinyKernel
    VMGuest --> BusyBoxInitrd
    VMGuest --> RootFS
    NETCONF["NETCONF env var"]:::data -->|dashed| CNIPlugin
    CNIPlugin -->|configures| Xen
    Xen <-->|"serial console"| FilesSerialBridge
    FilesSerialBridge --> VMGuest

    %% Click Events
    click RunX "https://github.com/xilinx/runx/tree/master/runX"
    click BuildScript "https://github.com/xilinx/runx/blob/master/build.sh"
    click GobuildMakefile "https://github.com/xilinx/runx/tree/master/gobuild/Makefile"
    click SerialFDHandler "https://github.com/xilinx/runx/blob/master/gobuild/src/serial_fd_handler.go"
    click FilesStart "https://github.com/xilinx/runx/tree/master/files/start"
    click FilesDelete "https://github.com/xilinx/runx/tree/master/files/delete"
    click FilesSerialBridge "https://github.com/xilinx/runx/tree/master/files/serial_bridge"
    click FilesSerialStart "https://github.com/xilinx/runx/tree/master/files/serial_start"
    click FilesState "https://github.com/xilinx/runx/tree/master/files/state"
    click MakeKernel "https://github.com/xilinx/runx/tree/master/kernel/make-kernel"
    click MakeInitrd "https://github.com/xilinx/runx/tree/master/kernel/make-initrd"
    click InitInitrd "https://github.com/xilinx/runx/tree/master/kernel/init-initrd"
    click CutConfigX86 "https://github.com/xilinx/runx/blob/master/kernel/cutdown-config.x86"
    click CutConfigARM "https://github.com/xilinx/runx/blob/master/kernel/cutdown-config.arm"
    click CutConfigARM64 "https://github.com/xilinx/runx/blob/master/kernel/cutdown-config.arm64"
    click Patch1 "https://github.com/xilinx/runx/blob/master/kernel/patches/0001-patch-pvcalls_enable.patch"
    click Patch2 "https://github.com/xilinx/runx/blob/master/kernel/patches/0002-pvcalls-front-introduce-a-per-sock_mapping-refcount.patch"
    click Patch3 "https://github.com/xilinx/runx/blob/master/kernel/patches/0003-pvcalls-front-wait-for-other-operations-to-return-wh.patch"
    click Patch4 "https://github.com/xilinx/runx/blob/master/kernel/patches/0004-patch-arm64_fix.patch"
    click README "https://github.com/xilinx/runx/blob/master/README.md"
    click DEPENDENCIES "https://github.com/xilinx/runx/tree/master/DEPENDENCIES"
    click LICENSE "https://github.com/xilinx/runx/tree/master/LICENSE"

    %% Styles
    classDef dom0 fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef hypervisor fill:#E0E0E0,stroke:#888888,color:#333333;
    classDef vm fill:#E8FFE8,stroke:#2E8B57,color:#2E8B57;
    classDef storage fill:#FFF5BA,stroke:#DCA10F,color:#8B6508;
    classDef docs fill:#F0F0F0,stroke:#AAAAAA,color:#555555;
    classDef data stroke-dasharray: 5 5;
```
