# xilinx/xup_vitis_network_example architecture

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

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

## Overview

VNx is an FPGA networking example platform: it provides reusable 100-Gbit Ethernet and UDP network-layer IP, plus basic data-transfer and benchmark designs and host-side control tools. The principal workflow is to configure an FPGA from a notebook or host application, move or generate traffic through the application kernels and shared network infrastructure, then inspect configuration or measurements. The README documents the subsystem capabilities and connections; some implementation paths are unsampled, so those links are cited to the README rather than inferred from filenames.

Main entry points: [`NetLayers/src/networklayer.v`](https://github.com/xilinx/xup_vitis_network_example/blob/master/NetLayers/src/networklayer.v) (UDP Network Layer), [`Notebooks`](https://github.com/xilinx/xup_vitis_network_example/tree/master/Notebooks) (PYNQ Notebooks), [`xrt_host_api/src/networklayer.cpp`](https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/networklayer.cpp) (XRT Host API), [`Ethernet/src/template_top.v`](https://github.com/xilinx/xup_vitis_network_example/blob/master/Ethernet/src/template_top.v) (100G CMAC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host Control"]
  node_notebooks["PYNQ Notebooks"]
  node_utils["Network Utilities<br/>[vnx_utils.py]"]
  node_dask["Dask Device<br/>[dask_pynq.py]"]
  node_hostapi["XRT Host API<br/>[networklayer.cpp]"]
  node_cmacapi["CMAC Controls<br/>[cmac.cpp]"]
  node_macapi["MAC Lookup<br/>[mac.cpp]"]
end

subgraph group_shared["Shared Network IP"]
  node_cmac["100G CMAC<br/>[template_top.v]"]
  node_netlayer["UDP Network Layer<br/>[networklayer.v]"]
  node_counters["Traffic Counters<br/>[krnl_counters.cpp]"]
end

subgraph group_basic["Basic Transfer"]
  node_mm2s["Memory to Stream<br/>[krnl_mm2s.cpp]"]
  node_s2mm["Stream to Memory<br/>[krnl_s2mm.cpp]"]
  node_basicresult["Transfer Data"]
end

subgraph group_bench["Benchmarking"]
  node_trafficgen["Traffic Generator"]
  node_collector["Latency Collector<br/>[collector.cpp]"]
  node_benchmarkresult["Benchmark Results"]
end

node_user(("Engineer"))
node_externalnet(("Ethernet Network"))

node_user -->|"runs examples"| node_notebooks
node_notebooks -->|"uses helpers"| node_utils
node_notebooks -.->|"schedules workers"| node_dask
node_notebooks -.->|"configures network"| node_hostapi
node_hostapi -->|"configures tables"| node_netlayer
node_cmacapi -.->|"reads registers"| node_cmac
node_macapi -.->|"provides MAC"| node_hostapi
node_cmac -->|"sends and receives"| node_externalnet
node_netlayer -->|"uses Ethernet"| node_cmac
node_mm2s -->|"sends UDP stream"| node_netlayer
node_netlayer -->|"delivers UDP stream"| node_s2mm
node_mm2s -->|"reads payload"| node_basicresult
node_s2mm -->|"writes payload"| node_basicresult
node_trafficgen -->|"generates traffic"| node_netlayer
node_netlayer -.->|"returns summaries"| node_collector
node_collector -->|"records latency"| node_benchmarkresult
node_notebooks -->|"measures throughput"| node_benchmarkresult
node_notebooks -->|"measures latency"| node_benchmarkresult
node_netlayer -.->|"exposes statistics"| node_counters

click node_notebooks "https://github.com/xilinx/xup_vitis_network_example/tree/master/Notebooks"
click node_utils "https://github.com/xilinx/xup_vitis_network_example/blob/master/Notebooks/vnx_utils.py"
click node_dask "https://github.com/xilinx/xup_vitis_network_example/blob/master/Notebooks/dask_pynq.py"
click node_hostapi "https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/networklayer.cpp"
click node_cmacapi "https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/cmac.cpp"
click node_macapi "https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/mac.cpp"
click node_cmac "https://github.com/xilinx/xup_vitis_network_example/blob/master/Ethernet/src/template_top.v"
click node_netlayer "https://github.com/xilinx/xup_vitis_network_example/blob/master/NetLayers/src/networklayer.v"
click node_counters "https://github.com/xilinx/xup_vitis_network_example/blob/master/Basic_kernels/src/krnl_counters.cpp"
click node_mm2s "https://github.com/xilinx/xup_vitis_network_example/blob/master/Basic_kernels/src/krnl_mm2s.cpp"
click node_s2mm "https://github.com/xilinx/xup_vitis_network_example/blob/master/Basic_kernels/src/krnl_s2mm.cpp"
click node_basicresult "https://github.com/xilinx/xup_vitis_network_example/tree/master/Basic_kernels"
click node_trafficgen "https://github.com/xilinx/xup_vitis_network_example/blob/master/Benchmark_kernel/src/traffic_generator.v"
click node_collector "https://github.com/xilinx/xup_vitis_network_example/blob/master/Benchmark_kernel/src/collector.cpp"
click node_benchmarkresult "https://github.com/xilinx/xup_vitis_network_example/tree/master/Benchmark_kernel"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notebooks,node_utils,node_dask,node_hostapi,node_cmacapi,node_macapi toneBlue
class node_cmac,node_netlayer,node_counters toneAmber
class node_mm2s,node_s2mm,node_basicresult toneMint
class node_trafficgen,node_collector,node_benchmarkresult toneRose
class node_user,node_externalnet toneIndigo
```

## Components

### Host Control

- [PYNQ Notebooks](https://github.com/xilinx/xup_vitis_network_example/tree/master/Notebooks): `Notebooks`
- [Network Utilities](https://github.com/xilinx/xup_vitis_network_example/blob/master/Notebooks/vnx_utils.py): `Notebooks/vnx_utils.py`
- [Dask Device](https://github.com/xilinx/xup_vitis_network_example/blob/master/Notebooks/dask_pynq.py): `Notebooks/dask_pynq.py`
- [XRT Host API](https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/networklayer.cpp): `xrt_host_api/src/networklayer.cpp`
- [CMAC Controls](https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/cmac.cpp): `xrt_host_api/src/cmac.cpp`
- [MAC Lookup](https://github.com/xilinx/xup_vitis_network_example/blob/master/xrt_host_api/src/mac.cpp): `xrt_host_api/src/mac.cpp`

### Shared Network IP

- [100G CMAC](https://github.com/xilinx/xup_vitis_network_example/blob/master/Ethernet/src/template_top.v): `Ethernet/src/template_top.v`
- [UDP Network Layer](https://github.com/xilinx/xup_vitis_network_example/blob/master/NetLayers/src/networklayer.v): `NetLayers/src/networklayer.v`
- [Traffic Counters](https://github.com/xilinx/xup_vitis_network_example/blob/master/Basic_kernels/src/krnl_counters.cpp): `Basic_kernels/src/krnl_counters.cpp`

### Basic Transfer

- [Memory to Stream](https://github.com/xilinx/xup_vitis_network_example/blob/master/Basic_kernels/src/krnl_mm2s.cpp): `Basic_kernels/src/krnl_mm2s.cpp`
- [Stream to Memory](https://github.com/xilinx/xup_vitis_network_example/blob/master/Basic_kernels/src/krnl_s2mm.cpp): `Basic_kernels/src/krnl_s2mm.cpp`
- [Transfer Data](https://github.com/xilinx/xup_vitis_network_example/tree/master/Basic_kernels): `Basic_kernels`

### Benchmarking

- [Traffic Generator](https://github.com/xilinx/xup_vitis_network_example/blob/master/Benchmark_kernel/src/traffic_generator.v): `Benchmark_kernel/src/traffic_generator.v`
- [Latency Collector](https://github.com/xilinx/xup_vitis_network_example/blob/master/Benchmark_kernel/src/collector.cpp): `Benchmark_kernel/src/collector.cpp`
- [Benchmark Results](https://github.com/xilinx/xup_vitis_network_example/tree/master/Benchmark_kernel): `Benchmark_kernel`

### Other components

- **Engineer**
- **Ethernet Network**

## Connections

- Engineer → PYNQ Notebooks: runs examples (evidence: `README.md`)
- PYNQ Notebooks → Network Utilities: uses helpers (evidence: `README.md`)
- PYNQ Notebooks → Dask Device: schedules workers
- PYNQ Notebooks → XRT Host API: configures network
- XRT Host API → UDP Network Layer: configures tables (evidence: `README.md`)
- CMAC Controls → 100G CMAC: reads registers
- MAC Lookup → XRT Host API: provides MAC
- 100G CMAC → Ethernet Network: sends and receives (evidence: `README.md`)
- UDP Network Layer → 100G CMAC: uses Ethernet (evidence: `README.md`)
- Memory to Stream → UDP Network Layer: sends UDP stream (evidence: `README.md`)
- UDP Network Layer → Stream to Memory: delivers UDP stream (evidence: `README.md`)
- Memory to Stream → Transfer Data: reads payload (evidence: `README.md`)
- Stream to Memory → Transfer Data: writes payload (evidence: `README.md`)
- Traffic Generator → UDP Network Layer: generates traffic (evidence: `README.md`)
- UDP Network Layer → Latency Collector: returns summaries
- Latency Collector → Benchmark Results: records latency (evidence: `Benchmark_kernel/src/collector.cpp`)
- PYNQ Notebooks → Benchmark Results: measures throughput (evidence: `README.md`)
- PYNQ Notebooks → Benchmark Results: measures latency (evidence: `README.md`)
- UDP Network Layer → Traffic Counters: exposes statistics
