# xdp-project/xdp-tools architecture

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

- Interactive diagram: https://gitdiagram.com/xdp-project/xdp-tools
- Repository: https://github.com/xdp-project/xdp-tools

## Overview

xdp-tools combines libxdp, which manages Linux XDP programs, with command-line tools for loading, observing, filtering, forwarding, benchmarking, and generating traffic. The typical workflow is an operator invoking a utility, which configures or runs an XDP capability; the README identifies the utilities as using the library and lists their distinct roles. Common utility code and reusable XDP snippets support the tools. Source excerpts are partial, so tool-to-internal-subsystem links are limited to relationships documented by the README rather than inferred from filenames.

Main entry points: [`lib/libxdp/libxdp.c`](https://github.com/xdp-project/xdp-tools/blob/main/lib/libxdp/libxdp.c) (libxdp), [`xdp-filter/xdp-filter.c`](https://github.com/xdp-project/xdp-tools/blob/main/xdp-filter/xdp-filter.c) (Packet filter), [`xdp-forward/xdp-forward.c`](https://github.com/xdp-project/xdp-tools/blob/main/xdp-forward/xdp-forward.c) (Forwarding plane), [`xdp-dump/xdpdump.c`](https://github.com/xdp-project/xdp-tools/blob/main/xdp-dump/xdpdump.c) (Packet capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["XDP Library"]
  node_libxdp["libxdp<br/>[libxdp.c]"]
  node_xsk_api["AF_XDP sockets<br/>[xsk.c]"]
end

subgraph group_operations["Program Operations"]
  node_loader["Program loader<br/>[xdp-loader.c]"]
  node_monitor["Trace monitor<br/>[xdp-monitor.c]"]
end

subgraph group_packet_tools["Packet Tools"]
  node_filter["Packet filter<br/>[xdp-filter.c]"]
  node_filter_programs["Filter programs<br/>[xdpfilt_prog.h]"]
  node_forwarder["Forwarding plane<br/>[xdp-forward.c]"]
  node_forward_programs["Forwarding programs"]
  node_dump["Packet capture<br/>[xdpdump.c]"]
  node_dump_bpf["Capture programs<br/>[xdpdump_bpf.c]"]
  node_benchmark["XDP benchmark<br/>[xdp-bench.c]"]
  node_trafficgen["Traffic generator<br/>[xdp-trafficgen.c]"]
  node_trafficgen_bpf["Generator programs"]
end

subgraph group_shared["Shared Components"]
  node_common_util["Common utilities"]
  node_sample_helpers["XDP sample helpers"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_loader
node_operator -->|"invokes"| node_monitor
node_operator -->|"invokes"| node_filter
node_operator -->|"invokes"| node_forwarder
node_operator -->|"invokes"| node_dump
node_operator -->|"invokes"| node_benchmark
node_operator -->|"invokes"| node_trafficgen
node_loader -->|"uses"| node_libxdp
node_monitor -->|"uses"| node_libxdp
node_filter -->|"uses"| node_libxdp
node_forwarder -->|"uses"| node_libxdp
node_dump -->|"uses"| node_libxdp
node_benchmark -->|"uses"| node_libxdp
node_trafficgen -->|"uses"| node_libxdp
node_filter -.->|"configures"| node_filter_programs
node_forwarder -.->|"uses"| node_forward_programs
node_dump -.->|"uses"| node_dump_bpf
node_trafficgen -.->|"uses"| node_trafficgen_bpf

click node_libxdp "https://github.com/xdp-project/xdp-tools/blob/main/lib/libxdp/libxdp.c"
click node_xsk_api "https://github.com/xdp-project/xdp-tools/blob/main/lib/libxdp/xsk.c"
click node_loader "https://github.com/xdp-project/xdp-tools/blob/main/xdp-loader/xdp-loader.c"
click node_monitor "https://github.com/xdp-project/xdp-tools/blob/main/xdp-monitor/xdp-monitor.c"
click node_filter "https://github.com/xdp-project/xdp-tools/blob/main/xdp-filter/xdp-filter.c"
click node_filter_programs "https://github.com/xdp-project/xdp-tools/blob/main/xdp-filter/xdpfilt_prog.h"
click node_forwarder "https://github.com/xdp-project/xdp-tools/blob/main/xdp-forward/xdp-forward.c"
click node_forward_programs "https://github.com/xdp-project/xdp-tools/blob/main/xdp-forward/xdp_flowtable.bpf.c"
click node_dump "https://github.com/xdp-project/xdp-tools/blob/main/xdp-dump/xdpdump.c"
click node_dump_bpf "https://github.com/xdp-project/xdp-tools/blob/main/xdp-dump/xdpdump_bpf.c"
click node_benchmark "https://github.com/xdp-project/xdp-tools/blob/main/xdp-bench/xdp-bench.c"
click node_trafficgen "https://github.com/xdp-project/xdp-tools/blob/main/xdp-trafficgen/xdp-trafficgen.c"
click node_trafficgen_bpf "https://github.com/xdp-project/xdp-tools/blob/main/xdp-trafficgen/xdp_trafficgen.bpf.c"
click node_common_util "https://github.com/xdp-project/xdp-tools/tree/main/lib/util"
click node_sample_helpers "https://github.com/xdp-project/xdp-tools/tree/main/headers/xdp"

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_libxdp,node_xsk_api toneBlue
class node_loader,node_monitor toneAmber
class node_filter,node_filter_programs,node_forwarder,node_forward_programs,node_dump,node_dump_bpf,node_benchmark,node_trafficgen,node_trafficgen_bpf toneMint
class node_common_util,node_sample_helpers toneRose
class node_operator toneIndigo
```

## Components

### XDP Library

- [libxdp](https://github.com/xdp-project/xdp-tools/blob/main/lib/libxdp/libxdp.c): `lib/libxdp/libxdp.c`
- [AF_XDP sockets](https://github.com/xdp-project/xdp-tools/blob/main/lib/libxdp/xsk.c): `lib/libxdp/xsk.c`

### Program Operations

- [Program loader](https://github.com/xdp-project/xdp-tools/blob/main/xdp-loader/xdp-loader.c): `xdp-loader/xdp-loader.c`
- [Trace monitor](https://github.com/xdp-project/xdp-tools/blob/main/xdp-monitor/xdp-monitor.c): `xdp-monitor/xdp-monitor.c`

### Packet Tools

- [Packet filter](https://github.com/xdp-project/xdp-tools/blob/main/xdp-filter/xdp-filter.c): `xdp-filter/xdp-filter.c`
- [Filter programs](https://github.com/xdp-project/xdp-tools/blob/main/xdp-filter/xdpfilt_prog.h): `xdp-filter/xdpfilt_prog.h`
- [Forwarding plane](https://github.com/xdp-project/xdp-tools/blob/main/xdp-forward/xdp-forward.c): `xdp-forward/xdp-forward.c`
- [Forwarding programs](https://github.com/xdp-project/xdp-tools/blob/main/xdp-forward/xdp_flowtable.bpf.c): `xdp-forward/xdp_flowtable.bpf.c`
- [Packet capture](https://github.com/xdp-project/xdp-tools/blob/main/xdp-dump/xdpdump.c): `xdp-dump/xdpdump.c`
- [Capture programs](https://github.com/xdp-project/xdp-tools/blob/main/xdp-dump/xdpdump_bpf.c): `xdp-dump/xdpdump_bpf.c`
- [XDP benchmark](https://github.com/xdp-project/xdp-tools/blob/main/xdp-bench/xdp-bench.c): `xdp-bench/xdp-bench.c`
- [Traffic generator](https://github.com/xdp-project/xdp-tools/blob/main/xdp-trafficgen/xdp-trafficgen.c): `xdp-trafficgen/xdp-trafficgen.c`
- [Generator programs](https://github.com/xdp-project/xdp-tools/blob/main/xdp-trafficgen/xdp_trafficgen.bpf.c): `xdp-trafficgen/xdp_trafficgen.bpf.c`

### Shared Components

- [Common utilities](https://github.com/xdp-project/xdp-tools/tree/main/lib/util): `lib/util`
- [XDP sample helpers](https://github.com/xdp-project/xdp-tools/tree/main/headers/xdp): `headers/xdp`

### Other components

- **Operator**

## Connections

- Operator → Program loader: invokes
- Operator → Trace monitor: invokes
- Operator → Packet filter: invokes
- Operator → Forwarding plane: invokes
- Operator → Packet capture: invokes
- Operator → XDP benchmark: invokes
- Operator → Traffic generator: invokes
- Program loader → libxdp: uses
- Trace monitor → libxdp: uses
- Packet filter → libxdp: uses
- Forwarding plane → libxdp: uses
- Packet capture → libxdp: uses
- XDP benchmark → libxdp: uses
- Traffic generator → libxdp: uses
- Packet filter → Filter programs: configures
- Forwarding plane → Forwarding programs: uses
- Packet capture → Capture programs: uses
- Traffic generator → Generator programs: uses
