# xilinx/wireless-xorif architecture

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

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

## Overview

##### Project type and purpose
- This is an embedded‐software IP driver and demo application project for Xilinx’s ORAN Radio Interface IP. It provides:
- A C driver library (libxorif) using LibMetal for register‐level access to the FPGA IP.
- A kernel‐space PTP timer module (xlnx‐ptp‐timer).
- A CLI/configuration application (xorif‐app) in C and Python demos.
- Top‐level build & deploy flows (Vivado, PetaLinux, Yocto recipes).

##### File structure
- Top‐level directories:
- doc: Doxygen‐generated HTML & design docs
- scripts: Vivado / PetaLinux build and deployment scripts
- src: source for three subcomponents: libxorif, xlnx‐ptp‐timer, xorif‐app (plus helper scripts)
- xsa: hardware definition (XSA/HDF) for Vivado
- yocto‐recipes: PetaLinux/Yocto recipes for packaging library, app, scripts

##### Main components
a. Hardware layer
- ORAN Radio IF IP (FPGA IP core)
- CPU subsystem (Zynq PS or Versal) running Linux
b. Kernel layer
- xlnx‐ptp‐timer kernel module (for PTP timestamping)
- Device trees (from yocto/recipes‐bsp/device‐tree)
c. Userspace libraries & applications
- C driver library (libxorif + pylibxorif Python bindings)
- CLI App (xorif‐app server & client)
- Python demos (fhi_example, ocp_example)
d. Build & deployment
- Vivado flow (scripts/xil_vivado_*.tcl) → hardware bitstream + XSA
- PetaLinux flow (scripts/runvp*.bash) → Linux image including kernel modules
- Yocto recipes (under yocto‐recipes) → Debian/RPM packages or rootfs

##### Relationships & interactions
- The build scripts invoke Vivado to generate the hardware definition (XSA).
- PetaLinux/Yocto consume XSA to build kernel + rootfs + device tree, include xlnx‐ptp‐timer.
- On target boot, device tree loads kernel modules.
- libxorif uses LibMetal to map FPGA registers (MMIO) and read/write control registers.
- xorif‐app (C) calls libxorif API; Python demos use pylibxorif wrappers.
- Scripts/utilities automate configuration, testing, and validation.

##### Architectural patterns & design principles
- Layered separation: hardware IP ←→ kernel module ←→ userspace C library ←→ applications/demos
- Modularity: independent subprojects (lib, app, kernel module) with own Makefiles & tests
- Reuse & extensibility: Python bindings, test suites, Yocto recipes for packaging

##### Final checklist
- Components: ORAN IP, Zynq PS, xlnx‐ptp‐timer, libxorif, pylibxorif, xorif‐app, demos, build scripts, Yocto.
- Interfaces: Vivado→XSA, XSA→Yocto, OS→Kernel Module, App→LibMetal/MMIO.
- Tech/Framework: LibMetal, Doxygen, Make, Yocto, PetaLinux, Vivado.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer" 
        direction TB
        ORAN_IP["ORAN Radio IF IP Core"]:::hw
    end
    click ORAN_IP "https://github.com/xilinx/wireless-xorif/tree/master/xsa/"

    %% Build Flows
    subgraph "Vivado Build Flow" 
        direction TB
        VIV1["xil_vivado_build.tcl"]:::build
        VIV2["xil_vivado_simple.tcl"]:::build
        VIV3["xil_vivado_utils.tcl"]:::build
        VIV4["xil_vivado_configs.yml"]:::build
    end
    click VIV1 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/xil_vivado_build.tcl"
    click VIV2 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/xil_vivado_simple.tcl"
    click VIV3 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/xil_vivado_utils.tcl"
    click VIV4 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/xil_vivado_configs.yml"

    VIV1 -->|"generate XSA"| ORAN_IP
    VIV2 --> ORAN_IP
    VIV3 --> ORAN_IP
    VIV4 --> ORAN_IP

    %% OS Image Build Flow
    subgraph "OS Image Build Flow" 
        direction TB
        PETA1["runvp.bash"]:::build
        PETA2["runvp_slv.bash"]:::build
        PETA3["runvp_help.bash"]:::build
        YOCTO["Yocto Recipes"]:::build
    end
    click PETA1 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/runvp.bash"
    click PETA2 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/runvp_slv.bash"
    click PETA3 "https://github.com/xilinx/wireless-xorif/blob/master/scripts/runvp_help.bash"
    click YOCTO "https://github.com/xilinx/wireless-xorif/tree/master/yocto-recipes/recipes-bsp/device-tree/"

    ORAN_IP -->|"XSA input"| YOCTO
    PETA1 --> YOCTO
    PETA2 --> YOCTO
    PETA3 --> YOCTO

    YOCTO -->|"produce Linux Image"| OS_IMAGE["Linux OS Image"]

    %% Kernel Layer
    subgraph "Kernel Layer"
        direction TB
        DT_OVERLAY["Device Tree Overlays"]:::kernel
        PTP_MODULE["xlnx-ptp-timer Module"]:::kernel
    end
    click DT_OVERLAY "https://github.com/xilinx/wireless-xorif/tree/master/yocto-recipes/recipes-bsp/device-tree/"
    click PTP_MODULE "https://github.com/xilinx/wireless-xorif/blob/master/src/xlnx-ptp-timer/xlnx-ptp-timer.c"
    click PTP_MODULE "https://github.com/xilinx/wireless-xorif/blob/master/yocto-recipes/recipes-modules/xlnx-ptp-timer/xlnx-ptp-timer.bb"

    OS_IMAGE -->|"boot with DT"| DT_OVERLAY
    OS_IMAGE -->|"loads module"| PTP_MODULE

    %% Userspace Layer
    subgraph "Userspace Libraries & Applications"
        direction TB
        LIB["libxorif C Library"]:::user
        PYBIND["pylibxorif Python Bindings"]:::user
        APP["xorif-app CLI Application"]:::user
        DEMOS["Python Demos"]:::user
    end
    click LIB "https://github.com/xilinx/wireless-xorif/tree/master/src/libxorif/"
    click LIB "https://github.com/xilinx/wireless-xorif/blob/master/src/libxorif/xorif_api.h"
    click PYBIND "https://github.com/xilinx/wireless-xorif/blob/master/src/libxorif/pylibxorif.py"
    click APP "https://github.com/xilinx/wireless-xorif/blob/master/src/xorif-app/xorif_app.c/.h"
    click DEMOS "https://github.com/xilinx/wireless-xorif/blob/master/src/libxorif/fhi_example1.py"

    PTP_MODULE -->|"kernel timestamps"| LIB
    LIB -->|"LibMetal MMIO"| ORAN_IP
    APP -->|"calls libxorif API"| LIB
    DEMOS -->|"use pylibxorif"| PYBIND
    PYBIND -->|"wrap lib API"| LIB

    %% Helper Scripts & Startup
    subgraph "Helper Scripts & Startup"
        direction TB
        HSCRIPTS["xorif-scripts"]:::build
        STARTUP["xorif-startup.service"]:::build
    end
    click HSCRIPTS "https://github.com/xilinx/wireless-xorif/tree/master/src/xorif-scripts/"
    click STARTUP "https://github.com/xilinx/wireless-xorif/blob/master/src/xorif-startup/xorif-startup.service"

    OS_IMAGE --> STARTUP
    STARTUP --> LIB
    HSCRIPTS --> APP

    %% Packaging
    subgraph "Yocto Packaging"
        direction TB
        PKG_LIB["libxorif.bb"]:::build
        PKG_APP["xorif-app.bb"]:::build
        PKG_SCR["xorif-scripts.bb"]:::build
        PKG_ST["xorif-startup-systemd.bb"]:::build
    end
    click PKG_LIB "https://github.com/xilinx/wireless-xorif/blob/master/yocto-recipes/recipes-apps/libxorif/libxorif.bb"
    click PKG_APP "https://github.com/xilinx/wireless-xorif/blob/master/yocto-recipes/recipes-apps/xorif-app/xorif-app.bb"
    click PKG_SCR "https://github.com/xilinx/wireless-xorif/blob/master/yocto-recipes/recipes-apps/xorif-scripts/xorif-scripts.bb"
    click PKG_ST "https://github.com/xilinx/wireless-xorif/blob/master/yocto-recipes/recipes-apps/xorif-startup/xorif-startup-systemd.bb"

    YOCTO --> PKG_LIB
    YOCTO --> PKG_APP
    YOCTO --> PKG_SCR
    YOCTO --> PKG_ST

    %% Legend
    subgraph "Legend"
        direction TB
        HW["Hardware Layer"]:::hw
        KERNEL["Kernel Layer"]:::kernel
        USER["Userspace"]:::user
        BUILD["Build/Deploy"]:::build
    end

    classDef hw fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef kernel fill:#d4edda,stroke:#333,stroke-width:1px
    classDef user fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef build fill:#ebebeb,stroke:#333,stroke-width:1px
```
