Skip to main content
skill CX Codex

af-xdp — Claude Code skill: what it does, how to install

Configures AF_XDP sockets and shared UMEM buffers for low-latency packet processing. Helps implement fast network filtering directly in userspace.

MIT 359 installs ★ 298 updated 2026-06-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mohitmishra786/low-level-dev-skills --skill af-xdp -a claude-code
Open on GitHub

What af-xdp does

The skill equips coding assistants with architectural patterns for AF_XDP sockets using libbpf. It explains memory allocation for UMEM, setting up RX, TX, fill, and completion rings, alongside socket binding with xsk_socket__create. Guidance covers building the companion BPF program that routes traffic via bpf_redirect_map and BPF_MAP_TYPE_XSKMAP.

It also details hardware trade-offs between XDP_COPY and XDP_ZEROCOPY. Zero-copy mode demands NIC driver support such as mlx5 or i40e, and processes without CAP_NET_RAW fail immediately. The guide highlights operational hazards: failing to replenish the fill ring causes the Linux kernel to drop incoming frames silently.

What it helps with

  • Allocate UMEM memory areas and initialize XSK ring buffers in C
  • Write an eBPF program redirecting queue packets with XDP_REDIRECT
  • Build an RX processing loop that recycles descriptors to the fill ring
  • Diagnose socket bind errors like EBUSY and permission rejections

Example prompts for the agent

  • Write C code to configure an AF_XDP socket and UMEM rings with libbpf
  • Show an eBPF redirect program using BPF_MAP_TYPE_XSKMAP for eth0
  • Explain why zero-copy AF_XDP falls back to copy mode on my network card

How to install af-xdp

1Skills CLI (Vercel)

npx skills add mohitmishra786/low-level-dev-skills --skill af-xdp -a claude-code

2Manually: put the files in place

~/.claude/skills/af-xdp/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/af-xdp/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about af-xdp

How to install af-xdp in Claude Code?

Run npx skills add mohitmishra786/low-level-dev-skills --skill af-xdp -a claude-code. The skill file will be placed in ~/.claude/skills/af-xdp/SKILL.md.

How does AF_XDP differ from DPDK?

AF_XDP keeps the standard kernel driver intact without full hardware bypass or hugepages setup. It combines in-kernel XDP packet filtering with direct delivery to userspace memory.

Why does the socket drop packets under load?

Drops occur when the fill ring runs empty. Userspace must continuously replenish empty frame addresses into the fill ring so the kernel has buffers ready for incoming packets.

Source text

SKILL.md · MIT
---
name: af-xdp
description: AF_XDP skill for high-performance XDP sockets. Use when creating AF_XDP sockets, configuring UMEM and XSK rings, XDP_REDIRECT programs, copy vs zero-copy mode, or comparing with DPDK. Activates on queries about AF_XDP, xsk_umem, XDP_REDIRECT, libbpf xsk, or zero-copy XDP.
---

# AF_XDP

## Purpose

Guide agents through AF_XDP sockets for high-performance packet I/O: socket creation, UMEM setup, fill/completion/RX/TX rings, XDP programs with `XDP_REDIRECT` to XSK, copy vs zero-copy modes, libbpf helpers, performance comparison with DPDK, and production use cases.

## When to Use

- Building a userspace packet processor with lower overhead than raw sockets
- Redirecting XDP-filtered traffic to userspace without DPDK complexity
- Implementing a custom load balancer or IDS dataplane
- Comparing zero-copy vs copy mode on your NIC/driver
- Integrating with existing libbpf/XDP infrastructure
- Need kernel cooperation (firewall rules) plus userspace processing

## Workflow

### 1. Architecture overview

```
NIC → XDP program (BPF) → XDP_REDIRECT → AF_XDP socket → userspace
                ↓
           XDP_DROP/PASS/TX
```

Components:
- **UMEM** — shared memory region for frames
- **Fill ring** — userspace provides empty frame addresses to kernel
- **Completion ring** — kernel returns completed TX frames
- **RX ring** — kernel delivers received packets
- **TX ring** — userspace submits packets for transmission

### 2. UMEM and XSK socket creation

```c
#include <bpf/xsk.h>
#include <bpf/libbpf.h>
#include <xdp/xsk.h>

#define NUM_FRAMES     4096
#define FRAME_SIZE     XSK_UMEM__DEFAULT_FRAME_SIZE
#define RX_BATCH_SIZE  64

struct xsk_umem_info {
    struct xsk_ring_prod fill;
    struct xsk_ring_cons comp;
    struct xsk_umem *umem;
    void *buffer;
};

struct xsk_socket_info {
    struct xsk_ring_cons rx;
    struct xsk_ring_prod tx;
    struct xsk_socket *xsk;
};

int xsk_setup(struct xsk_umem_info *umem_info,
              struct xsk_socket_info *xsk_info,
              int ifindex, int queue_id, int xsk_flags)
{
    umem_info->buffer = mmap(NULL, NUM_FRAMES * FRAME_SIZE,
        PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);

    struct xsk_umem_config umem_cfg = {
        .fill_size = XSK_RING_PROD__DEFAULT_NUM_DESCS,
        .comp_size = XSK_RING_CONS__DEFAULT_NUM_DESCS,
        .frame_size = FRAME_SIZE,
        .frame_headroom = XSK_UMEM__DEFAULT_FRAME_HEADROOM,
        .flags = 0,
    };

    int ret = xsk_umem__create(&umem_info->umem, umem_info->buffer,
        NUM_FRAMES * FRAME_SIZE, &umem_info->fill, &umem_info->comp,
        &umem_cfg);
    if (ret)
        return ret;

    struct xsk_socket_config xsk_cfg = {
        .rx_size = XSK_RING_CONS__DEFAULT_NUM_DESCS,
        .tx_size = XSK_RING_PROD__DEFAULT_NUM_DESCS,
        .libbpf_flags = XSK_LIBBPF_FLAGS__INHIBIT_PROG_LOAD,
        .xdp_flags = XDP_FLAGS_UPDATE_IF_NOEXIST,
        .bind_flags = xsk_flags,  // XDP_ZEROCOPY or XDP_COPY
    };

    return xsk_socket__create(&xsk_info->xsk, "eth0", queue_id,
        umem_info->umem, &xsk_info->rx, &xsk_info->tx, &xsk_cfg);
}
```

### 3. Populate fill ring

```c
void populate_fill_ring(struct xsk_umem_info *umem) {
    uint32_t idx;
    uint32_t ret = xsk_ring_prod__reserve(&umem->fill, RX_BATCH_SIZE, &idx);
    for (uint32_t i = 0; i < ret; i++)
        *xsk_ring_prod__fill_addr(&umem->fill, idx + i) = i * FRAME_SIZE;
    xsk_ring_prod__submit(&umem->fill, ret);
}
```

Must keep fill ring stocked — kernel drops packets if no buffers available.

### 4. XDP redirect program

```c
// xdp_redirect.c
#include <linux/bpf.h>
#include <bpf/bpf_helpers.h>

struct {
    __uint(type, BPF_MAP_TYPE_XSKMAP);
    __uint(max_entries, 64);
    __type(key, int);
    __type(value, int);
} xsks_map SEC(".maps");

SEC("xdp")
int xdp_redirect_prog(struct xdp_md *ctx)
{
    int index = ctx->rx_queue_index;
    return bpf_redirect_map(&xsks_map, index, 0);
}
```

```bash
# Load and attach
bpftool prog load xdp_redirect.o /sys/fs/bpf/xdp_redirect
ip link set dev eth0 xdp obj xdp_redirect.o sec xdp

# Pin xsks_map and update with socket fd
```

### 5. RX processing loop

```c
while (running) {
    uint32_t idx_rx = 0, rcvd;
    rcvd = xsk_ring_cons__peek(&xsk_info->rx, RX_BATCH_SIZE, &idx_rx);
    if (!rcvd)
        continue;

    for (uint32_t i = 0; i < rcvd; i++) {
        const struct xdp_desc *desc = xsk_ring_cons__rx_desc(&xsk_info->rx, idx_rx + i);
        uint64_t addr = desc->addr;
        uint32_t len = desc->len;
        uint8_t *pkt = (uint8_t *)xsk_umem__get_data(umem_info->buffer, addr);
        process_packet(pkt, len);
    }
    xsk_ring_cons__release(&xsk_info->rx, rcvd);

    // Return frames to fill ring
    refill_fill_ring(umem_info, rcvd);
}
```

### 6. Copy vs zero-copy

| Mode | Flag | Requirements |
|------|------|--------------|
| Copy | `XDP_COPY` (default) | Any driver; kernel copies to UMEM |
| Zero-copy | `XDP_ZEROCOPY` | Driver support (i40e, ixgbe, mlx5, etc.) |

```bash
# Check driver ZC support
ethtool -i eth0
# Kernel log on bind:
dmesg | grep xsk
# "Zero-copy enabled" or "Copy mode"
```

Zero-copy: NIC DMAs directly into UMEM frames — lowest latency. Copy mode: safer, universal.

### 7. libbpf xsk.h helpers

```bash
# Modern libbpf includes xsk API
pkg-config --libs libbpf
# -lbpf -lxdp (if separate libxdp installed)
```

Key functions:
- `xsk_umem__create` / `xsk_umem__delete`
- `xsk_socket__create` / `xsk_socket__delete`
- `xsk_umem__get_data` — pointer from frame address
- `xsk_socket__fd` — for epoll/poll integration

### 8. Performance vs DPDK

| Factor | AF_XDP | DPDK |
|--------|--------|------|
| Setup complexity | Moderate | High (hugepages, EAL) |
| Kernel integration | XDP filter in kernel | Full bypass |
| Typical throughput | Near-DPDK with ZC | Highest |
| NIC binding | Stays on kernel driver | vfio/uio binding |
| Use case fit | Filter + selective userspace | Full dataplane takeover |

### 9. Production patterns

```
Common deployments
├── CDN edge cache — XDP_DROP junk, redirect cacheable to XSK
├── DDoS mitigation — XDP_DROP attack patterns
├── Load balancer — XDP_TX hairpin or redirect to backend XSK
└── Observability — mirror subset to XSK for analysis
```

```bash
# Multi-queue: one XSK per RX queue, pinned to CPU
taskset -c 2 ./xsk_app --queue 2
```

## Common Problems

| Symptom | Cause | Fix |
|---------|-------|-----|
| No packets in RX ring | XDP program not redirecting | Verify xsks_map entry for queue index |
| `EBUSY` on socket create | XDP already attached | `ip link set dev eth0 xdp off` first |
| Zero-copy fallback to copy | Driver lacks ZC | Check dmesg; use supported NIC |
| Packet drops | Fill ring empty | Aggressive refill; increase NUM_FRAMES |
| TX not working | Completion ring not polled | Process comp ring to recycle frames |
| Permission denied | CAP_NET_RAW needed | Run with appropriate capabilities |

## Related Skills

- `skills/observability/ebpf` — XDP/BPF program development
- `skills/async-io/dpdk` — full kernel bypass alternative
- `skills/async-io/io-uring` — async I/O for non-packet workloads
- `skills/observability/ebpf-rust` — Aya for XDP in Rust
- `skills/profilers/linux-perf` — profile XDP program CPU usage
- `skills/allocators/numa-programming` — NUMA-local UMEM allocation

© mohitmishra786 · MIT · mohitmishra786/low-level-dev-skills

Similar skills

All skills for Backend and APIs →

From the same set140

The whole set →
hypervisor-internals The hypervisor-internals skill explains Intel VT-x and AMD-V internals, from VMCS and VMCB to EPT/NPT and VMEXIT handling. Use it while studying or building a small hypervisor. CX Codex +1 365installs hip-rocm hip-rocm is a Claude Code skill for writing HIP kernels and moving CUDA code to AMD GPUs. It activates for HIP, ROCm, HIPIFY, profiling, and debugging tasks. CX Codex +1 364installs io-uring Skill for working with io_uring, the new asynchronous I/O interface in Linux. Use it when building high-performance servers and you need to reduce syscall overhead and enable zero-copy data transfer. CX Codex +1 361installs arm-sve arm-sve — a skill for Scalable Vector Extension programming on ARM servers. Teaches vector-length agnostic SIMD code that adapts to hardware vector width on Graviton, Apple M4, and other AArch64 platforms. CX Codex +1 361installs triton-lang triton-lang is a Claude Code skill that teaches agents to write Triton GPU kernels with @triton.jit, masked block operations, atomics, autotuning, and PyTorch integration. CX Codex +1 358installs containers-internals containers-internals is a Claude Code skill for Linux container internals, activated for queries about namespaces, runc, seccomp, and escape vulnerabilities. CX Codex +1 358installs rdma-verbs rdma-verbs guides coding agents through RDMA programming using libibverbs for InfiniBand and RoCE fabrics. Useful when setting up queue pairs or perftest benchmarks. CX Codex +1 356installs riscv-privileged The riscv-privileged skill supports RISC-V kernel and firmware development, covering privileged modes, CSRs, traps, interrupt controllers, OpenSBI, page tables, and QEMU testing. CX Codex +1 355installs

Project sponsors

Companies that keep this analytics open