# fpganinja/taxi architecture

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

- Interactive diagram: https://gitdiagram.com/fpganinja/taxi
- Repository: https://github.com/fpganinja/taxi

## Overview

#### Purpose and entry points
Taxi is a SystemVerilog transport/IP library spanning on-chip buses, streaming data paths, Ethernet, PCIe, DMA, timing, and control. It also contains Corundum NIC implementations, Zircon IP-stack stages, host drivers, and board-targeted FPGA designs. Primary integration entry points are RTL top modules and file lists under `src/*/rtl`, plus board build targets such as `src/cndm/board/Alveo/fpga/fpga_AU250/Makefile` and `src/eth/example/ZCU106/fpga/fpga_10g/Makefile`.

#### Common transport fabric
APB, AXI, AXI-Lite, and AXI-Stream form the compositional boundary between components. Interface definitions establish typed bus contracts; adapters, interconnects/crossbars, FIFOs, registers, RAMs, and switches handle protocol conversion, routing, buffering, and clock-domain boundaries.
- `src/axi/rtl/taxi_axi_if.sv`
- `src/axi/rtl/taxi_axi_crossbar.sv`
- `src/axis/rtl/taxi_axis_async_fifo.sv`

#### DMA and PCIe host boundary
The DMA layer translates descriptors and segmented RAM accesses between client streams, AXI memory, and Xilinx UltraScale PCIe transports. The PCIe layer supplies host-controlled AXI-Lite access, MSI/MSI-X, configuration, VPD/VSEC, and interrupt-rate control. This is the principal FPGA-to-host boundary used by NIC designs.
- `src/dma/rtl/taxi_dma_if_pcie_us.sv`
- `src/dma/rtl/taxi_axi_dma.sv`
- `src/pcie/rtl/taxi_pcie_us_axil_master.sv`

#### Ethernet datapath and physical interfaces
Ethernet modules transform AXI-Stream frames through MAC, PCS/encoding, and PHY/transceiver-facing interfaces across MII/GMII/RGMII, 1000BASE-X, 10GBASE-R, 25GBASE-R, and USXGMII variants. MAC wrappers optionally include FIFOs and integrate control, pause handling, timestamps, and statistics; vendor-specific UltraScale GT wrappers form the hardware-facing edge.
- `src/eth/rtl/taxi_eth_mac_10g.sv`
- `src/eth/rtl/taxi_eth_phy_10g.sv`
- `src/eth/rtl/us/taxi_eth_mac_25g_us.sv`

#### Timing, statistics, and management plane
PTP distributes a central hardware clock into local clock domains; statistics collectors emit aggregated values over AXI-Stream and counters expose them through control registers. XFCP is a source-routed AXI-Stream control fabric, with UART ingress and bridges to APB, AXI, AXI-Lite, and I2C. Low-speed serial modules provide the physical/control endpoints.
- `src/ptp/rtl/taxi_ptp_td_phc.sv`
- `src/stats/rtl/taxi_stats_collect.sv`
- `src/xfcp/rtl/taxi_xfcp_switch.sv`

#### Corundum NIC and host software
`cndm` implements Corundum variants around PCIe, DMA queues, completion/event handling, and Ethernet ports. FPGA cores are wrapped per target board; the repository also ships a Linux kernel driver and a DPDK PMD, which define the host software boundary. `cndm_proto` is a separate simplified prototype path with its own RTL and driver.
- `src/cndm/rtl/cndm_micro_core.sv`
- `src/cndm/modules/cndm/cndm_main.c`
- `src/cndm/dpdk/cndm/cndm_ethdev.c`

#### Zircon and deployment/runtime environment
Zircon supplies pipelined IP RX parsing/egress and TX ingress/buffering/deparsing stages for application-facing packet processing. Board designs compose Taxi/CNDM or Ethernet blocks into Xilinx FPGA top levels, constraints, generated PCIe/DDR/GT IP, and Vivado builds. RTL is simulated with Cocotb/Python and Verilator; production synthesis depends on Xilinx Vivado and board-specific hardware.
- `src/zircon/rtl/zircon_ip_rx_parse.sv`
- `src/zircon/rtl/zircon_ip_tx_deparse.sv`
- `src/cndm/board/Alveo/fpga/rtl/fpga_core.sv`

Main entry points: [`src/eth/rtl/taxi_eth_mac_10g.sv`](https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/taxi_eth_mac_10g.sv) (10G Ethernet MAC), [`src/dma/rtl/taxi_dma_if_pcie_us.sv`](https://github.com/fpganinja/taxi/blob/master/src/dma/rtl/taxi_dma_if_pcie_us.sv) (PCIe DMA interface), [`src/cndm/rtl/cndm_micro_core.sv`](https://github.com/fpganinja/taxi/blob/master/src/cndm/rtl/cndm_micro_core.sv) (Corundum micro core), [`src/pcie/rtl/taxi_pcie_us_axil_master.sv`](https://github.com/fpganinja/taxi/blob/master/src/pcie/rtl/taxi_pcie_us_axil_master.sv) (PCIe AXI-Lite master)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fabric["Transport Fabric"]
  node_axi_if["AXI interfaces<br/>SystemVerilog interfaces<br/>[taxi_axi_if.sv]"]
  node_axi_crossbar["AXI crossbar<br/>interconnect"]
  node_axis_async_fifo["AXIS async FIFO<br/>CDC buffer"]
  node_ptp_phc["PTP hardware clock<br/>timing core<br/>[taxi_ptp_td_phc.sv]"]
  node_stats_collect["Statistics collector<br/>telemetry core"]
  node_xfcp_switch["XFCP switch<br/>control fabric"]
end

subgraph group_host["Host Boundary"]
  node_pcie_axil["PCIe AXI-Lite master<br/>PCIe control bridge"]
  node_dma_pcie_if["PCIe DMA interface<br/>DMA transport"]
  node_axi_dma["AXI DMA<br/>DMA engine<br/>[taxi_axi_dma.sv]"]
  node_cndm_core{{"Corundum micro core<br/>NIC core<br/>[cndm_micro_core.sv]"}}
  node_kernel_driver["Linux kernel driver<br/>host driver<br/>[cndm_main.c]"]
  node_dpdk_pmd["DPDK PMD<br/>userspace driver<br/>[cndm_ethdev.c]"]
end

subgraph group_network["Network Data Plane"]
  node_eth_mac_10g["10G Ethernet MAC<br/>MAC datapath"]
  node_eth_phy_10g["10G Ethernet PHY<br/>PCS/PHY interface"]
  node_eth_mac_25g_us["25G UltraScale MAC<br/>vendor MAC wrapper"]
  node_zircon_rx["Zircon RX parse<br/>IP pipeline stage"]
  node_zircon_tx["Zircon TX deparse<br/>IP pipeline stage"]
end

subgraph group_deployment["FPGA Deployment"]
  node_alveo_core{{"Alveo FPGA core<br/>board top integration<br/>[fpga_core.sv]"}}
  node_au250_build["AU250 Vivado build<br/>board build target"]
  node_zcu106_build["ZCU106 10G build<br/>board build target"]
end

node_axi_if -->|"transaction contracts"| node_axi_crossbar
node_axi_if -->|"stream contracts"| node_axis_async_fifo
node_axis_async_fifo -->|"clock-crossed frames"| node_eth_mac_10g
node_ptp_phc -->|"timestamps"| node_eth_mac_10g
node_eth_mac_10g -->|"MAC frames"| node_eth_phy_10g
node_eth_mac_25g_us -->|"Ethernet ports"| node_cndm_core
node_eth_mac_10g -->|"received frames"| node_zircon_rx
node_zircon_tx -->|"egress frames"| node_eth_mac_10g
node_stats_collect -->|"management telemetry"| node_xfcp_switch
node_xfcp_switch -->|"control bridges"| node_axi_crossbar
node_pcie_axil -->|"host register access"| node_axi_crossbar
node_dma_pcie_if -->|"descriptors and RAM access"| node_axi_dma
node_axi_dma -->|"client streams"| node_axis_async_fifo
node_pcie_axil -->|"NIC control"| node_cndm_core
node_dma_pcie_if -->|"host DMA"| node_cndm_core
node_kernel_driver -->|"PCIe control"| node_pcie_axil
node_kernel_driver -->|"DMA queues"| node_dma_pcie_if
node_dpdk_pmd -->|"userspace queues"| node_dma_pcie_if
node_cndm_core -->|"board integration"| node_alveo_core
node_alveo_core -->|"synthesized target"| node_au250_build
node_eth_mac_10g -->|"example integration"| node_zcu106_build

click node_axi_if "https://github.com/fpganinja/taxi/blob/master/src/axi/rtl/taxi_axi_if.sv"
click node_axi_crossbar "https://github.com/fpganinja/taxi/blob/master/src/axi/rtl/taxi_axi_crossbar.sv"
click node_axis_async_fifo "https://github.com/fpganinja/taxi/blob/master/src/axis/rtl/taxi_axis_async_fifo.sv"
click node_ptp_phc "https://github.com/fpganinja/taxi/blob/master/src/ptp/rtl/taxi_ptp_td_phc.sv"
click node_stats_collect "https://github.com/fpganinja/taxi/blob/master/src/stats/rtl/taxi_stats_collect.sv"
click node_xfcp_switch "https://github.com/fpganinja/taxi/blob/master/src/xfcp/rtl/taxi_xfcp_switch.sv"
click node_pcie_axil "https://github.com/fpganinja/taxi/blob/master/src/pcie/rtl/taxi_pcie_us_axil_master.sv"
click node_dma_pcie_if "https://github.com/fpganinja/taxi/blob/master/src/dma/rtl/taxi_dma_if_pcie_us.sv"
click node_axi_dma "https://github.com/fpganinja/taxi/blob/master/src/dma/rtl/taxi_axi_dma.sv"
click node_cndm_core "https://github.com/fpganinja/taxi/blob/master/src/cndm/rtl/cndm_micro_core.sv"
click node_kernel_driver "https://github.com/fpganinja/taxi/blob/master/src/cndm/modules/cndm/cndm_main.c"
click node_dpdk_pmd "https://github.com/fpganinja/taxi/blob/master/src/cndm/dpdk/cndm/cndm_ethdev.c"
click node_eth_mac_10g "https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/taxi_eth_mac_10g.sv"
click node_eth_phy_10g "https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/taxi_eth_phy_10g.sv"
click node_eth_mac_25g_us "https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/us/taxi_eth_mac_25g_us.sv"
click node_zircon_rx "https://github.com/fpganinja/taxi/blob/master/src/zircon/rtl/zircon_ip_rx_parse.sv"
click node_zircon_tx "https://github.com/fpganinja/taxi/blob/master/src/zircon/rtl/zircon_ip_tx_deparse.sv"
click node_alveo_core "https://github.com/fpganinja/taxi/blob/master/src/cndm/board/Alveo/fpga/rtl/fpga_core.sv"
click node_au250_build "https://github.com/fpganinja/taxi/blob/master/src/cndm/board/Alveo/fpga/fpga_AU250/Makefile"
click node_zcu106_build "https://github.com/fpganinja/taxi/blob/master/src/eth/example/ZCU106/fpga/fpga_10g/Makefile"

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_axi_if,node_axi_crossbar,node_axis_async_fifo,node_ptp_phc,node_stats_collect,node_xfcp_switch toneBlue
class node_pcie_axil,node_dma_pcie_if,node_axi_dma,node_cndm_core,node_kernel_driver,node_dpdk_pmd toneAmber
class node_eth_mac_10g,node_eth_phy_10g,node_eth_mac_25g_us,node_zircon_rx,node_zircon_tx toneMint
class node_alveo_core,node_au250_build,node_zcu106_build toneRose
```

## Components

### Transport Fabric

Shared typed buses and datapath primitives.

- [AXI interfaces](https://github.com/fpganinja/taxi/blob/master/src/axi/rtl/taxi_axi_if.sv): SystemVerilog interfaces · Typed APB, AXI, AXI-Lite, and stream contracts. · `src/axi/rtl/taxi_axi_if.sv`
- [AXI crossbar](https://github.com/fpganinja/taxi/blob/master/src/axi/rtl/taxi_axi_crossbar.sv): interconnect · Routes AXI memory and control transactions. · `src/axi/rtl/taxi_axi_crossbar.sv`
- [AXIS async FIFO](https://github.com/fpganinja/taxi/blob/master/src/axis/rtl/taxi_axis_async_fifo.sv): CDC buffer · Buffers stream traffic across clock domains. · `src/axis/rtl/taxi_axis_async_fifo.sv`
- [PTP hardware clock](https://github.com/fpganinja/taxi/blob/master/src/ptp/rtl/taxi_ptp_td_phc.sv): timing core · Distributes synchronized time to local domains. · `src/ptp/rtl/taxi_ptp_td_phc.sv`
- [Statistics collector](https://github.com/fpganinja/taxi/blob/master/src/stats/rtl/taxi_stats_collect.sv): telemetry core · Aggregates counters onto AXI-Stream and registers. · `src/stats/rtl/taxi_stats_collect.sv`
- [XFCP switch](https://github.com/fpganinja/taxi/blob/master/src/xfcp/rtl/taxi_xfcp_switch.sv): control fabric · Source-routed AXI-Stream management fabric. · `src/xfcp/rtl/taxi_xfcp_switch.sv`

### Host Boundary

PCIe, DMA, and host-side NIC software.

- [PCIe AXI-Lite master](https://github.com/fpganinja/taxi/blob/master/src/pcie/rtl/taxi_pcie_us_axil_master.sv): PCIe control bridge · Exposes host-controlled register access. · `src/pcie/rtl/taxi_pcie_us_axil_master.sv`
- [PCIe DMA interface](https://github.com/fpganinja/taxi/blob/master/src/dma/rtl/taxi_dma_if_pcie_us.sv): DMA transport · Connects descriptors and segmented RAM to UltraScale PCIe. · `src/dma/rtl/taxi_dma_if_pcie_us.sv`
- [AXI DMA](https://github.com/fpganinja/taxi/blob/master/src/dma/rtl/taxi_axi_dma.sv): DMA engine · Moves client stream data through AXI memory. · `src/dma/rtl/taxi_axi_dma.sv`
- [Corundum micro core](https://github.com/fpganinja/taxi/blob/master/src/cndm/rtl/cndm_micro_core.sv): NIC core · Integrates queues, completions, PCIe DMA, and ports. · `src/cndm/rtl/cndm_micro_core.sv`
- [Linux kernel driver](https://github.com/fpganinja/taxi/blob/master/src/cndm/modules/cndm/cndm_main.c): host driver · Host control and datapath software boundary. · `src/cndm/modules/cndm/cndm_main.c`
- [DPDK PMD](https://github.com/fpganinja/taxi/blob/master/src/cndm/dpdk/cndm/cndm_ethdev.c): userspace driver · Userspace Corundum network driver. · `src/cndm/dpdk/cndm/cndm_ethdev.c`

### Network Data Plane

Ethernet and application-facing packet processing.

- [10G Ethernet MAC](https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/taxi_eth_mac_10g.sv): MAC datapath · Processes streamed frames with control and statistics. · `src/eth/rtl/taxi_eth_mac_10g.sv`
- [10G Ethernet PHY](https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/taxi_eth_phy_10g.sv): PCS/PHY interface · Connects MAC traffic to 10G physical links. · `src/eth/rtl/taxi_eth_phy_10g.sv`
- [25G UltraScale MAC](https://github.com/fpganinja/taxi/blob/master/src/eth/rtl/us/taxi_eth_mac_25g_us.sv): vendor MAC wrapper · Hardware-facing 25G MAC/GT integration. · `src/eth/rtl/us/taxi_eth_mac_25g_us.sv`
- [Zircon RX parse](https://github.com/fpganinja/taxi/blob/master/src/zircon/rtl/zircon_ip_rx_parse.sv): IP pipeline stage · Parses received IP packets for applications. · `src/zircon/rtl/zircon_ip_rx_parse.sv`
- [Zircon TX deparse](https://github.com/fpganinja/taxi/blob/master/src/zircon/rtl/zircon_ip_tx_deparse.sv): IP pipeline stage · Reconstructs egress IP packets. · `src/zircon/rtl/zircon_ip_tx_deparse.sv`

### FPGA Deployment

Board composition and production build targets.

- [Alveo FPGA core](https://github.com/fpganinja/taxi/blob/master/src/cndm/board/Alveo/fpga/rtl/fpga_core.sv): board top integration · Composes board-level NIC RTL. · `src/cndm/board/Alveo/fpga/rtl/fpga_core.sv`
- [AU250 Vivado build](https://github.com/fpganinja/taxi/blob/master/src/cndm/board/Alveo/fpga/fpga_AU250/Makefile): board build target · Produces the Alveo AU250 FPGA image. · `src/cndm/board/Alveo/fpga/fpga_AU250/Makefile`
- [ZCU106 10G build](https://github.com/fpganinja/taxi/blob/master/src/eth/example/ZCU106/fpga/fpga_10g/Makefile): board build target · Builds the Ethernet example FPGA image. · `src/eth/example/ZCU106/fpga/fpga_10g/Makefile`

## Connections

- AXI interfaces → AXI crossbar: transaction contracts
- AXI interfaces → AXIS async FIFO: stream contracts
- AXIS async FIFO → 10G Ethernet MAC: clock-crossed frames
- PTP hardware clock → 10G Ethernet MAC: timestamps
- 10G Ethernet MAC → 10G Ethernet PHY: MAC frames
- 25G UltraScale MAC → Corundum micro core: Ethernet ports
- 10G Ethernet MAC → Zircon RX parse: received frames
- Zircon TX deparse → 10G Ethernet MAC: egress frames
- Statistics collector → XFCP switch: management telemetry
- XFCP switch → AXI crossbar: control bridges
- PCIe AXI-Lite master → AXI crossbar: host register access
- PCIe DMA interface → AXI DMA: descriptors and RAM access
- AXI DMA → AXIS async FIFO: client streams
- PCIe AXI-Lite master → Corundum micro core: NIC control
- PCIe DMA interface → Corundum micro core: host DMA
- Linux kernel driver → PCIe AXI-Lite master: PCIe control
- Linux kernel driver → PCIe DMA interface: DMA queues
- DPDK PMD → PCIe DMA interface: userspace queues
- Corundum micro core → Alveo FPGA core: board integration
- Alveo FPGA core → AU250 Vivado build: synthesized target
- 10G Ethernet MAC → ZCU106 10G build: example integration