From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 7F00E489C9; Fri, 24 Oct 2025 23:55:48 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 795994068A; Fri, 24 Oct 2025 23:55:12 +0200 (CEST) Received: from mail-pf1-f181.google.com (mail-pf1-f181.google.com [209.85.210.181]) by mails.dpdk.org (Postfix) with ESMTP id 6704340652 for ; Fri, 24 Oct 2025 23:55:07 +0200 (CEST) Received: by mail-pf1-f181.google.com with SMTP id d2e1a72fcca58-77f67ba775aso3230724b3a.3 for ; Fri, 24 Oct 2025 14:55:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1761342906; x=1761947706; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=bzX2+4zwc/W4SYw5qrvZgh1SeceNBqkHGO3r7por6/E=; b=Gtj6mQxn0+7uB3G9G9O+wE60R+XjNrjEytUFlSiPU+BgwJPrzD5+UcpvQ+NVze2iOT YS3cLN6x4IAtzDKMMxuhyp9ogIuGXrCXT4WAZiOz0CyCO/SoD1VIbcSpppCPIhaeApMe BLyrvV20FYDhbTRyjOOQq6KisyDkT0fQVEW6YdN392w7b3bUx5pKG24dIyJeUdI0dGfN 1vE3kzevVxjFQiq++5EOg1tW+g5SU/aJfGf4cqvpWfTo2QyoI0ISgXXjPXiHdkkLiUZU NVeQBMv+SOXCa22kqlJZMVMfJ4bsOIRqWpsNTcgBHGIRpPRneLwsjdiW/yNoysIWZKke Rpew== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1761342906; x=1761947706; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bzX2+4zwc/W4SYw5qrvZgh1SeceNBqkHGO3r7por6/E=; b=nwlTtKekNI6uMmZ0DaVyvXu/PluZy5z+LDMUEz4CONZzaR0WVrU/KSbN+CtPanZruB ++8IQsp6LcuO6eb7OiALvUUYeMy5B+CHdOqaioz9dFUv66qPsb/5+JzBfun00+o+gvin kAlkUgF2kK/pBScE/n5T/F7X495TtQElb0F0Y9k70pTpyRQHQnXSm9IJVj1bMX/KVtme 8T2CvdirYRtzfjGZhxOMCDrNhHdPBnPTAuFvlXgkFZbEzxrLFRXRKbQhRuGbgys3HEVY heke0Y6XrLie37iIwuWMHea5uYoWG1VwPZT/Lhi9/lmY7L4/Ro9aQ7EiSkY6d7XdR4n9 LKYQ== X-Gm-Message-State: AOJu0YwhZEQmobRoTLkdUQkgtZr38SqECiZuQ4gKGPPqI2OtNQqrMQcY 7jRFeYNqQlZ9GZsPAlwoRy33Tg4jbyMuqd1auLo/TsXbBB4Anl+fnMh6JVXCYogulMUzqwOtZL0 R1uAI X-Gm-Gg: ASbGncveF4DRFgvIgaY/7RYn7gBSXGryxwqrz/mQmniGjB1UBSGQeYeknoTmwUXxARa QLQ5/vqf7/DqCoQazFXuM/Z8dKbpioNQ/rw93PBmEtuY8f8RACWD4/BxHOEmuZbZ5H8OwkhIePW J0Oar2w7r+EjfgcairUQm3EBhiER+rVd/TvlKgJfrw1x9cDMIRVFAa02z+ZeHac0dYdZ3YKQ0FR jFi6pLsZbp8eLLXiPrAf/7CFjw3c+s2Zj6eQTbWpwmCVn08NuMnCLODWIptMTtM0qrAo4E+pJ3c felmad1bIkBnMgnf6S6dAYHrjPVUWbyufXYBQ0k1kipLTVeeibktCTNVQuUDYjvAWxu7isJNhzM Biern//QeRwKDAimt3hDCj9rQ1ETE4J/qwsf0T4cbrlPa+VajZ2cD/8pi9NidKJ2IP/+zw1gBrT iD6LhL9Rjey89FCqcvx34nGawvWrz8RE9pkXnYJy0= X-Google-Smtp-Source: AGHT+IEoJBTSzR7lfuw/p2DHB7lRfA/X7mSfjpWy/+D+CV9QW577IAnWzjmtW13UghDb/qL0rOwgGg== X-Received: by 2002:a05:6a20:914b:b0:334:a462:d299 with SMTP id adf61e73a8af0-334a8528703mr43517431637.3.1761342906421; Fri, 24 Oct 2025 14:55:06 -0700 (PDT) Received: from phoenix.lan (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7a414012de3sm252530b3a.2.2025.10.24.14.55.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Oct 2025 14:55:05 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger , Bruce Richardson , Khadem Ullah <14pwcse1224@uetpeshawar.edu.pk>, Reshma Pattan Subject: [PATCH v5 8/8] doc: update documentation on pdump library Date: Fri, 24 Oct 2025 14:54:03 -0700 Message-ID: <20251024215456.282171-9-stephen@networkplumber.org> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20251024215456.282171-1-stephen@networkplumber.org> References: <250811213632.16023-1-stephen@networkplumber.org> <20251024215456.282171-1-stephen@networkplumber.org> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org The documentation was missing some of the API, and had some awkward wording. With the help of ChatGPT, update it and make it more concise. Add a release note Signed-off-by: Stephen Hemminger Acked-by: Bruce Richardson Acked-by: Khadem Ullah <14pwcse1224@uetpeshawar.edu.pk> --- doc/guides/prog_guide/img/pdump_overview.svg | 135 ++++++++++++++ doc/guides/prog_guide/pdump_lib.rst | 183 ++++++++++++------- doc/guides/rel_notes/release_25_11.rst | 5 + 3 files changed, 255 insertions(+), 68 deletions(-) create mode 100644 doc/guides/prog_guide/img/pdump_overview.svg diff --git a/doc/guides/prog_guide/img/pdump_overview.svg b/doc/guides/prog_guide/img/pdump_overview.svg new file mode 100644 index 0000000000..537de49669 --- /dev/null +++ b/doc/guides/prog_guide/img/pdump_overview.svg @@ -0,0 +1,135 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Capture Process + + Primary Process + + Secondary Processes + + + + + + + + + + rte_eal_init() + + rte_pdump_init() + + + + rte_eal_init() + + rte_pdump_init() + + + + rte_eal_init() + + rte_pdump_init() + + + + + rte_pdump_enable() + + uses rte_mp_request() to message primary + + + + pdump_server() + • enable RX/TX callbacks + • send ACK to capture + • forward request to all secondaries + + + ACK + + forward enable request + + + + pdump_server() + • register RX/TX callbacks + • send response + + + response + + + + collect responses + from secondary processes + + + + + + Packet capture in progress... + + + + + rte_pdump_disable() + + + + pdump_server() + • remove RX/TX callbacks + • forward disable to secondaries + + + + forward disable request + + + + pdump_server() + • remove RX/TX callbacks + + + + response + + + + collect disable responses + + diff --git a/doc/guides/prog_guide/pdump_lib.rst b/doc/guides/prog_guide/pdump_lib.rst index 07b9f39d09..5183756d9e 100644 --- a/doc/guides/prog_guide/pdump_lib.rst +++ b/doc/guides/prog_guide/pdump_lib.rst @@ -4,90 +4,137 @@ Packet Capture Library ====================== -The DPDK ``pdump`` library provides a framework for packet capturing in DPDK. -The library does the complete copy of the Rx and Tx mbufs to a new mempool and -hence it slows down the performance of the applications, so it is recommended -to use this library for debugging purposes. +The DPDK ``pdump`` library provides a framework for capturing packets within DPDK applications. +It enables a **secondary process** to monitor packets being processed by both +**primary** or **secondary** processes. -The library uses a generic multi process channel to facilitate communication -between primary and secondary process for enabling/disabling packet capture on -ports. +Overview +-------- -The library provides the following APIs to initialize the packet capture framework, to enable -or disable the packet capture, and to uninitialize it. +The library uses a multi-process channel to facilitate communication +between the primary and secondary processes. This mechanism allows enabling +or disabling packet capture on specific ports or queues. -* ``rte_pdump_init()``: - This API initializes the packet capture framework. +.. _figure_pdump_overview: -* ``rte_pdump_enable()``: - This API enables the packet capture on a given port and queue. +.. figure:: img/pdump_overview.* -* ``rte_pdump_enable_bpf()`` - This API enables the packet capture on a given port and queue. - It also allows setting an optional filter using DPDK BPF interpreter - and setting the captured packet length. + Packet Capture enable and disable sequence -* ``rte_pdump_enable_by_deviceid()``: - This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. +API Reference +------------- -* ``rte_pdump_enable_bpf_by_deviceid()`` - This API enables the packet capture on a given device id (``vdev name or pci address``) and queue. - It also allows setting an optional filter using DPDK BPF interpreter - and setting the captured packet length. +The library exposes APIs for: -* ``rte_pdump_disable()``: - This API disables the packet capture on a given port and queue. +* Initializing and uninitializing the packet capture framework. +* Enabling and disabling packet capture. +* Applying optional filters and limiting captured packet length. -* ``rte_pdump_disable_by_deviceid()``: - This API disables the packet capture on a given device id (``vdev name or pci address``) and queue. -* ``rte_pdump_uninit()``: - This API uninitializes the packet capture framework. +.. function:: int rte_pdump_init(void) + Initialize the packet capture framework. + +.. function:: int rte_pdump_enable(uint16_t port_id, uint16_t queue, uint32_t flags) + + Enable packet capture on the specified port and queue. + +.. function:: int rte_pdump_enable_bpf(uint16_t port_id, uint16_t queue, const struct rte_bpf_program *bpf, uint32_t snaplen) + + Enable packet capture on the specified port and queue with an optional + BPF packet filter and a limit on the captured packet length. + +.. function:: int rte_pdump_enable_by_deviceid(const char *device_id, uint16_t queue, uint32_t flags) + + Enable packet capture on the specified device ID (``vdev`` name or PCI address) + and queue. + +.. function:: int rte_pdump_enable_bpf_by_deviceid(const char *device_id, uint16_t queue, const struct rte_bpf_program *bpf, uint32_t snaplen) + + Enable packet capture on the specified device ID (``vdev`` name or PCI address) + and queue, with optional filtering and captured packet length limit. + +.. function:: int rte_pdump_disable(uint16_t port_id, uint16_t queue) + + Disable packet capture on the specified port and queue. + This applies to the current process and all other processes. + +.. function:: int rte_pdump_disable_by_deviceid(const char *device_id, uint16_t queue) + + Disable packet capture on the specified device ID (``vdev`` name or PCI address) + and queue. + +.. function:: int rte_pdump_uninit(void) + + Uninitialize the packet capture framework for this process. + +.. function:: int rte_pdump_stats(uint16_t port_id, struct rte_dump_stats *stats) + + Reports the number of packets captured, filtered, and missed. + Packets maybe missed due to mbuf pool being exhausted or the ring being full. Operation --------- -The primary process using ``librte_pdump`` is responsible for initializing the packet -capture framework. The packet capture framework, as part of its initialization, creates the -multi process channel to facilitate communication with secondary process, so the -secondary process ``app/pdump`` tool is responsible for enabling and disabling the packet capture on ports. +All processes using ``librte_pdump`` must initialize the packet capture framework +before use. This initialization is required in both the primary and secondary processes. + +DPDK provides the following utilities that use this library: + +* ``app/dpdk-dumpcap`` +* ``app/pdump`` Implementation Details ---------------------- -The library API ``rte_pdump_init()``, initializes the packet capture framework by creating the multi process -channel using ``rte_mp_action_register()`` API. The primary process will listen to secondary process requests -to enable or disable the packet capture over the multi process channel. - -The library APIs ``rte_pdump_enable()`` and ``rte_pdump_enable_by_deviceid()`` enables the packet capture. -For the calls to these APIs from secondary process, the library creates the "pdump enable" request and sends -the request to the primary process over the multi process channel. The primary process takes this request -and enables the packet capture by registering the Ethernet RX and TX callbacks for the given port or device_id -and queue combinations. Then the primary process will mirror the packets to the new mempool and enqueue them to -the rte_ring that secondary process have passed to these APIs. - -The packet ring supports one of two formats. -The default format enqueues copies of the original packets into the rte_ring. -If the ``RTE_PDUMP_FLAG_PCAPNG`` is set, the mbuf data is extended -with header and trailer to match the format of Pcapng enhanced packet block. -The enhanced packet block has meta-data such as the timestamp, port and queue -the packet was captured on. -It is up to the application consuming the packets from the ring -to select the format desired. - -The library APIs ``rte_pdump_disable()`` and ``rte_pdump_disable_by_deviceid()`` disables the packet capture. -For the calls to these APIs from secondary process, the library creates the "pdump disable" request and sends -the request to the primary process over the multi process channel. The primary process takes this request and -disables the packet capture by removing the Ethernet RX and TX callbacks for the given port or device_id and -queue combinations. - -The library API ``rte_pdump_uninit()``, uninitializes the packet capture framework by calling ``rte_mp_action_unregister()`` -function. - - -Use Case: Packet Capturing --------------------------- - -The DPDK ``app/dpdk-dumpcap`` utility uses this library -to capture packets in DPDK. +``rte_pdump_init()`` creates the multi-process channel by calling +``rte_mp_action_register()``. + +The primary process listens for requests from secondary processes to +enable or disable packet capture over the multi-process channel. + +When a secondary process calls ``rte_pdump_enable()`` or +``rte_pdump_enable_by_deviceid()``, the library sends a "pdump enable" request +to the primary process. The primary process then: + +1. Receives the request over the multi-process channel. +2. Registers Ethernet Rx and Tx callbacks for the specified port. +3. Forwards the request to other secondary processes (if any) + + +FAQ +--- + +* What is the performance impact of pdump? + +Setting up pdump with ``rte_pdump_init`` has no impact, +there are no changes in the fast path. +When pdump is enabled, the Tx and Rx fast path functions +callbacks make a copy of the mbufs and enqueue them. This will impact +performance. The effect can be reduced by filtering to only +see the packets of interest and using the snaplen parameter +to only copy the needed headers. + +* What happens if process does not call pdump init? + +If application does not call ``rte_pdump_init`` then the request +to enable (in the capture command) will timeout and an error is returned. + +* Where do packets go? + +Packets captured are placed in the ring passed in ``rte_pdump_enable``. +The capture application must dequeue these mbuf's and free them. + +* Why is copy required? + +A copy is used instead of incrementing the reference count because +on transmit the device maybe using fast free which does not use refcounts; +and on receive the application may modify the incoming packet. + +* What about offloads? + +The offload flags of the original mbuf are copied to the ring. +It is up to the capture application to handle flags like VLAN stripping +as necessary. Packets are captured before passing to driver and hardware +so the actual packet on the wire maybe segmented or encapsulated based +on the offload flags. diff --git a/doc/guides/rel_notes/release_25_11.rst b/doc/guides/rel_notes/release_25_11.rst index c5ba335cfc..5dfdb5ff1e 100644 --- a/doc/guides/rel_notes/release_25_11.rst +++ b/doc/guides/rel_notes/release_25_11.rst @@ -167,6 +167,11 @@ New Features The built-in help text function is available as a public function which can be reused by custom functions, if so desired. +* **Added packet capture (pdump) for secondary process.** + + Added multi-process support to allow packets sent and received by secondary + process to be visible in packet capture. + Removed Items ------------- -- 2.51.0