fix(linux): Consolidate XDP documentation to a unified location for ICSSG and CPSW

MeghanaMalladiTI · claude · MeghanaMalladiTI · commit aeac88beb67f · 2026-04-21T14:54:13.000+05:30
- Add new centralized XDP documentation at
  Kernel/Kernel_Drivers/Network/XDP.rst
- Add kernel_xdp reference label that can be used throughout the docs
- Update PRU_ICSSG_XDP.rst to redirect to the consolidated XDP docs
- Update features supported in PRU_ICSSG_Ethernet.rst
- Update CPSW-Ethernet.rst to reference kernel_xdp instead of
  pru_icssg_xdp
- Add XDP.rst to AM64X device-specific table of contents
- Add XDP.rst to main Kernel Drivers toctree

The new XDP documentation covers:
- XDP introduction and concepts
- Use cases and kernel configuration
- AF_XDP sockets and zero-copy mode
- Testing with xdp-tools (xdp-bench, xdp-trafficgen)
- Performance comparison for CPSW and ICSSG drivers

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
Signed-off-by: Meghana Malladi &lt;m-malladi@ti.com&gt;
diff --git a/configs/AM64X/AM64X_linux_toc.txt b/configs/AM64X/AM64X_linux_toc.txt
@@ -66,6 +66,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Network/NETCONF-YANG
 linux/Foundational_Components/Kernel/Kernel_Drivers/Network/HSR_PRP_Non_Offload
 linux/Foundational_Components/Kernel/Kernel_Drivers/Network/HSR_Offload
 linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload
+linux/Foundational_Components/Kernel/Kernel_Drivers/Network/XDP
 linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
 linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_End_Point
 linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
@@ -107,7 +108,6 @@ linux/Foundational_Components/PRU-ICSS/Linux_Drivers/RemoteProc
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet_Switch
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/RPMsg
-linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_XDP
 linux/Foundational_Components/PRU-ICSS/RPMsg_Quick_Start_Guide
 linux/Foundational_Components/PRU-ICSS-Hardware
 linux/Foundational_Components/PRU-ICSS/PRU-EVMs
diff --git a/configs/AM65X/AM65X_linux_toc.txt b/configs/AM65X/AM65X_linux_toc.txt
@@ -87,7 +87,6 @@ linux/Foundational_Components/PRU-ICSS/Linux_Drivers/RemoteProc
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/RPMsg
 linux/Foundational_Components/PRU-ICSS/RPMsg_Quick_Start_Guide
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet
-linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_XDP
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet_Switch
 linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet_sr10
 linux/Foundational_Components/PRU-ICSS-Hardware
diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW-Ethernet.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW-Ethernet.rst
@@ -90,5 +90,5 @@ For further details regarding the TSN features and testing, refer :ref:`tsn_with
 
 XDP and zero copy
 """""""""""""""""
-The CPSW Ethernet Subsystem supports XDP and zero copy features similar to PRU-ICSS Ethernet Subsystem.
-For more details refer :ref:`pru_icssg_xdp`.
+The CPSW Ethernet Subsystem supports XDP Native Mode, XDP Generic Mode, and Zero-copy mode.
+For detailed setup and testing information, refer to :ref:`kernel_xdp`.
diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/XDP.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/XDP.rst
@@ -1,37 +1,36 @@
-.. _pru_icssg_xdp:
+.. _kernel_xdp:
 
-#############
-PRU_ICSSG XDP
-#############
+===
+XDP
+===
 
 .. contents:: :local:
     :depth: 3
 
-************
 Introduction
-************
+============
 
-XDP (eXpress Data Path) provides a framework for BPF that enables high-performance programmable packet processing in the Linux kernel. It runs the BPF program at the earliest possible point in software, namely at the moment the network driver receives the packet.
+eXpress Data Path (XDP) provides a framework for extended Berkeley Packet Filters (eBPF) that enables high-performance programmable packet processing in the Linux kernel. It runs the eBPF program at the earliest possible point in software, namely at the moment the network driver receives the packet.
 
-XDP allows running a BPF program just before the skbs are allocated in the driver, the BPF program can look at the packet and return the following things.
+XDP allows running an eBPF program just before the socket buffers (skbs) are allocated in the driver. The eBPF program can examine the packet and return one of the following actions.
 
-- XDP_DROP :- The packet is dropped right away, without wasting any resources. Useful for firewall etc.
-- XDP_ABORTED :- Similar to drop, an exception is generated.
-- XDP_PASS :- Pass the packet to kernel stack, i.e. the skbs are allocated and it works normally.
-- XDP_TX :- Send the packet back to same NIC with modification(if done by the program).
-- XDP_REDIRECT :- Send the packet to another NIC or to the user space through AF_XDP Socket(discussed below).
+- ``XDP_DROP`` :- The packet is dropped right away, without wasting any resources. Useful for firewall etc.
+- ``XDP_ABORTED`` :- Similar to drop, an exception is generated.
+- ``XDP_PASS`` :- Pass the packet to kernel stack, i.e. the skbs are allocated and it works normally.
+- ``XDP_TX`` :- Send the packet back to same NIC with modification(if done by the program).
+- ``XDP_REDIRECT`` :- Send the packet to another NIC or to the user space through AF_XDP Socket(discussed below).
 
-.. Image:: /images/XDP-packet-processing.png
+.. image:: /images/XDP-packet-processing.png
 
-As explained before, the XDP_REDIRECT sends packets directly to the user space.
+As explained before, the ``XDP_REDIRECT`` sends packets directly to the user space.
 This works by using the AF_XDP socket type which was introduced specifically for this usecase.
 
 In this process, the packet is directly sent to the user space without going through the kernel network stack.
 
-.. Image:: /images/xdp-packet.png
+.. image:: /images/xdp-packet.png
 
 Use cases for XDP
-=================
+-----------------
 
 XDP is particularly useful for these common networking scenarios:
 
@@ -42,10 +41,10 @@ XDP is particularly useful for these common networking scenarios:
 5. **Network Analytics**: Real-time traffic analysis and monitoring
 6. **Custom Network Functions**: Specialized packet handling for unique requirements
 
-How to run XDP with PRU_ICSSG
-=============================
+How to run XDP on EVM
+---------------------
 
-The kernel configuration requires the following changes to use XDP with PRU_ICSSG:
+The kernel configuration requires the following changes to use XDP:
 
 .. code-block:: console
 
@@ -59,7 +58,7 @@ The kernel configuration requires the following changes to use XDP with PRU_ICSS
    CONFIG_XDP_SOCKETS=y
 
 Tools for debugging XDP Applications
-====================================
+-------------------------------------
 
 Debugging tools for XDP development:
 
@@ -68,9 +67,8 @@ Debugging tools for XDP development:
 - perf - For performance monitoring and analysis
 - bpftrace - For tracing BPF program execution
 
-**************
 AF_XDP Sockets
-**************
+==============
 
 AF_XDP is a socket address family specifically designed to work with the XDP framework.
 These sockets provide a high-performance interface for user space applications to receive
@@ -84,13 +82,13 @@ Key characteristics of AF_XDP sockets include:
 - Optimized for high-throughput, low-latency applications
 
 How AF_XDP Works
-================
+----------------
 
 AF_XDP sockets operate through a shared memory mechanism:
 
 1. XDP program intercepts packets at driver level
-2. XDP_REDIRECT action sends packets to the socket
-3. Shared memory rings (RX/TX/FILL/COMPLETION) manage packet data
+2. ``XDP_REDIRECT`` action sends packets to the socket
+3. Shared memory rings (``RX``/``TX``/``FILL``/``COMPLETION``) manage packet data
 4. Userspace application directly accesses the packet data
 5. Zero or minimal copying depending on the mode used
 
@@ -99,30 +97,20 @@ The AF_XDP architecture uses several ring buffers:
 - **RX Ring**: Received packets ready for consumption
 - **TX Ring**: Packets to be transmitted
 - **FILL Ring**: Pre-allocated buffers for incoming packets
-- **COMPLETION Ring**: Tracks completed TX operations
+- **COMPLETION Ring**: Tracks completed ``TX`` operations
 
 For more details on AF_XDP please refer to the official documentation: `AF_XDP <https://www.kernel.org/doc/html/latest/networking/af_xdp.html>`_.
 
-Current Support Status in PRU_ICSSG
-===================================
-
-The PRU_ICSSG Ethernet driver currently supports:
-
-- Native XDP mode
-- Generic XDP mode (SKB-based)
-- Zero-copy mode
-
-**************************
-XDP Zero-Copy in PRU_ICSSG
-**************************
+XDP Zero-Copy
+=============
 
 Introduction to Zero-Copy Mode
-==============================
+-------------------------------
 
 Zero-copy mode is an optimization in AF_XDP that eliminates packet data copying between the kernel and user space. This results in significantly improved performance for high-throughput network applications.
 
 How Zero-Copy Works
-===================
+-------------------
 
 In standard XDP operation (copy mode), packet data is copied from kernel memory to user space memory when processed. Zero-copy mode eliminates this copy operation by:
 
@@ -131,31 +119,88 @@ In standard XDP operation (copy mode), packet data is copied from kernel memory
 3. Managing memory ownership through descriptor rings rather than data movement
 
 This approach provides several benefits:
+
 - Reduced CPU utilization
 - Lower memory bandwidth consumption
 - Decreased latency for packet processing
 - Improved overall throughput
 
-Requirements for Zero-Copy
-==========================
+Performance Considerations
+--------------------------
+
+When implementing XDP applications, consider these performance factors:
+
+1. **Memory Alignment**: Buffers should be aligned to page boundaries for optimal performance
+2. **Batch Processing**: Process multiple packets in batches when possible
+3. **Poll Mode**: Use poll() or similar mechanisms to avoid blocking on socket operations
+4. **Core Affinity**: Bind application threads to specific CPU cores to reduce cache contention
+
+Testing XDP on EVM
+==================
+
+The `xdp-tools <https://github.com/xdp-project/xdp-tools>`__ package provides
+utility tools for testing XDP and AF_XDP such as `xdp-bench`, `xdp-trafficgen` etc.
+
+TI SDK packages the latest version of ``xdp-tools`` utilities and provides it as part of the SDK.
+This allows users to easily test XDP functionality on EVM using these tools.
 
-For zero-copy to function properly with PRU_ICSSG, ensure:
+Both CPSW and ICSSG Ethernet drivers supports Native XDP, Generic XDP, and Zero-copy mode.
 
-1. **Driver Support**: Verify the PRU_ICSSG driver is loaded with zero-copy support enabled
-2. **Memory Alignment**: Buffer addresses must be properly aligned to page boundaries
-3. **UMEM Configuration**: The UMEM area must be correctly configured:
-   - Properly aligned memory allocation
-   - Sufficient number of packet buffers
-   - Appropriate buffer sizes
-4. **Hugepages**: Using hugepages for UMEM allocation is recommended for optimal performance
+.. note::
+
+   In case of testing with CPSW please note that when running XDP in Zero-copy mode, non-XDP traffic will be dropped.
+
+**XDP Transmit test** — generate traffic using XDP (copy mode):
+
+.. code-block:: console
+
+   xdp-trafficgen udp -m ff:ff:ff:ff:ff:ff <interface>
+
+**XDP Drop test** — receive and drop packets using XDP (copy mode):
+
+.. code-block:: console
+
+   xdp-bench xdp-bench drop <interface>
+
+**XDP Pass test** — receive and pass packets through XDP allowing normal network stack processing (copy mode):
+
+.. code-block:: console
+
+   xdp-bench xdp-bench pass <interface>
+
+**XDP TX test** — Hairpins (bounces back) received packets on the same interface (copy mode):
+
+.. code-block:: console
+
+   xdp-bench xdp-bench tx <interface>
+
+**XDP Redirect test** — Redirects received packets on the from one interface to another (copy mode):
+
+.. code-block:: console
+
+   xdp-bench xdp-bench redirect <interface1> <interface2>
+
+**XSK Drop test** — receive and drop packets using AF_XDP socket in zero-copy mode:
+
+.. code-block:: console
+
+   xdp-bench xsk-drop -q 0 -C zero-copy <interface>
+
+**XSK Transmit test** — generate traffic using AF_XDP socket in zero-copy mode:
+
+.. code-block:: console
+
+   xdp-trafficgen xsk-udp -m ff:ff:ff:ff:ff:ff -q 0 -C zero-copy <interface>
+
+While xdpsock is not packaged into the SDK, the same functionality can be done with xsk-trafficgen and xsk-bench from the xdp-tools package.
+For more details on xdpsock and how it performs XDP zero copy testing refer to `xdpsock <https://github.com/xdp-project/bpf-examples/tree/main/AF_XDP-example>`_
 
 Performance Comparison
-======================
+----------------------
 
 Performance testing shows that zero-copy mode can provide substantial throughput improvements compared to copy mode:
 
-`xdpsock <https://github.com/xdp-project/bpf-examples/tree/main/AF_XDP-example>`_ opensource tool was used for testing XDP zero copy.
-AF_XDP performance while using 64 byte packets in Kpps:
+AF_XDP performance while using 64 byte packets for ICSSG (in Kpps):
 
 .. list-table::
    :header-rows: 1
@@ -173,13 +218,20 @@ AF_XDP performance while using 64 byte packets in Kpps:
      - 354
      - 855
 
-Performance Considerations
-==========================
+AF_XDP performance while using 64 byte packets for CPSW (in Kpps):
 
-When implementing XDP applications, consider these performance factors:
+.. list-table::
+   :header-rows: 1
 
-1. **Memory Alignment**: Buffers should be aligned to page boundaries for optimal performance
-2. **Batch Processing**: Process multiple packets in batches when possible
-3. **Poll Mode**: Use poll() or similar mechanisms to avoid blocking on socket operations
-4. **Core Affinity**: Bind application threads to specific CPU cores to reduce cache contention
-5. **NUMA Awareness**: Consider NUMA topology when allocating memory for packet buffers
+   * - Benchmark
+     - XDP-SKB
+     - XDP-Native
+     - XDP-Native(ZeroCopy)
+   * - rxdrop
+     - 322
+     - 491
+     - 845
+   * - txonly
+     - 390
+     - 394
+     - 723
diff --git a/source/linux/Foundational_Components/PRU-ICSS-Linux-Drivers.rst b/source/linux/Foundational_Components/PRU-ICSS-Linux-Drivers.rst
@@ -9,7 +9,6 @@ Linux Drivers
    PRU-ICSS/Linux_Drivers/PRU-ICSS_Ethernet
    PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet
    PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet_Switch
-   PRU-ICSS/Linux_Drivers/PRU_ICSSG_XDP
    PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet_sr10
    PRU-ICSS/Linux_Drivers/pru-sw-uart
    PRU-ICSS/Linux_Drivers/pruss-uart
diff --git a/source/linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet.rst b/source/linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_Ethernet.rst
@@ -44,7 +44,7 @@ Features supported
 - Different MII modes for Real-Time Ethernet ports (MII_G_RT1 and MII_G_RT2) on different PRU_ICSSG instances. For example, MII on a PRU_ICSSG1 port, and RGMII on a PRU_ICSSG2 port, is supported.
 - IRQ Coalescing also known as interrupt pacing.
 - Multi-cast HW filtering
-- XDP Native Mode and XDP Generic Mode
+- XDP Native Mode, XDP Generic Mode and Zero-copy mode
 - Cut Through forwarding
 - PHY Interrupt mode for ICSSG2
 - Multicast filtering support for VLAN interfaces
@@ -54,7 +54,6 @@ Features supported
 - VLAN HW filtering
 - All-multi mode is always enabled
 - Different MII modes for Real-Time Ethernet ports (MII_G_RT1 and MII_G_RT2) on a single PRU_ICSSG instance. For example, MII_G_RT1=MII and MII_G_RT2=RGMII.
-- XDP with Zero-copy mode
 
 Driver Configuration
 ####################
@@ -713,8 +712,8 @@ To turn off PPS,
 XDP
 ###
 
-The PRU_ICSSG Ethernet driver supports Native XDP as well as Generic XDP. XDP with Zero-copy mode is not supported yet.
-For detailed setup and how to test XDP please refer to :ref:`pru_icssg_xdp`.
+The PRU_ICSSG Ethernet driver supports Native XDP, Generic XDP, and Zero-copy mode.
+Refer to :ref:`kernel_xdp` for more details.
 
 
 Tips
diff --git a/source/linux/Foundational_Components_Kernel_Drivers.rst b/source/linux/Foundational_Components_Kernel_Drivers.rst
@@ -32,6 +32,7 @@ Kernel Drivers
    Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW-Ethernet
    Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW2g
    Foundational_Components/Kernel/Kernel_Drivers/Network/NETCONF-YANG
+   Foundational_Components/Kernel/Kernel_Drivers/Network/XDP
    Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_End_Point
    Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Backplane
    Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
