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 2936B48AB2; Tue, 4 Nov 2025 19:10:24 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D61ED40A72; Tue, 4 Nov 2025 19:09:42 +0100 (CET) Received: from mail-pl1-f181.google.com (mail-pl1-f181.google.com [209.85.214.181]) by mails.dpdk.org (Postfix) with ESMTP id 21C0F40A6F for ; Tue, 4 Nov 2025 19:09:41 +0100 (CET) Received: by mail-pl1-f181.google.com with SMTP id d9443c01a7336-2955805b7acso693335ad.1 for ; Tue, 04 Nov 2025 10:09:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1762279780; x=1762884580; 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=HfN2QoO31EyRfAaH14myM8v3sZSA/gouGfmjUplyZQgrxcaLnJ2rrawiVARH83pvJb r6iVu07WWokOyR+Jhv4LZvaJWzi3xoniS5kjG66YM0xg/mQ0p0u6mRqaRl53k2c9KlXl axnsZT0yhZPJPW6+7jPIRH265J8JvHPrd1AonrEgfwGmbRi+1WcToc6IKyXySMw4EHDJ bXq5Am1P6gutSYQBwdh/CS7d6PC4Ef+zMpD5Afd8x3yjHIx2sPVK2L8IPsvTnxXQZQnH /h7Lamq8o8jSy8gVBNT2apXH9R/qW4w6f5Yg1TNle9Q1EV9Oue3wHPpMZv+O2z3G8qTu 1k9g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1762279780; x=1762884580; 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=wwMAkSpyyIuIEF+234QGshltr9AlPon1M9fw8sLwEOmXr2TL9KOZSRCIcckv9fKgSo ZPhVkB/qWqtdpR/wy7x4Td4HQcrY6eQ1p0hVa9DLkpl87sWbD8HyZtmdpw00i/0jRcnX 02+q2pWaj5NdIujuHx5QfzYpkVDjhGMW6AoEew9PkHdb+m45DQXDuB50nNdXD94mdgGW f4Y3Qm2DGeh7H5N/G6nYCGrTj5YiSzkvjozy8f8T1OjQDPqLZ/EEL6ut8/FcJerTeBDe HmYS6kRdELvygNDP3ZrR7wVXFD1hhGZ0M+22dTAlchQAUE54OdShUvp87gD/AabKd6Q6 55oA== X-Gm-Message-State: AOJu0YzCk0fRm73KU5hM1TvxERhCJXHk44pCy/SP26J7y5LDd1ttDyEr TJEFuVQRCGGP4AeUJHdVVRsK4cvUi9YfXuGhCiE55KxedTejr1w0vqOywQURqmHL7wkQz1we0DG of+uf X-Gm-Gg: ASbGncvFm396xoFCrTx0dZHNWGwTUHEjaiAwSB0OryDhy7WSYqPVL+3vn5RFaNH0lX3 WeZ/ZyykbDULy9YcWcbNu8dARODn71xNI/9PxvoVvZ394hxBFHo/2f9SybUZfucYFv3ZDTR6Pws wb8So6Dw2RGNugCufERaXEaY7YekRHXv5VqdJuYdRGC2p9JWI81pR2rSFTu8OMrsKVbCKH3eHZC FiweIe1gXG9Wuxrpp6JE2VNTzv+0j87aGQrm1u49zpJYb/Cz9vx6XIHSvddqeacY/frNKoiWZ+b b6v8jelamDxYx//0AQJYr0+UzvNPpO386iW1g5he9Nsn3VLC9gHpl0Z5bn0L+w9vCUP6GmR/Jik tv56PW8Fv/+N14KgqHl0tQU7y1kAymml7Dpn1r0HzTvyOuoxKfrQSS7w2/RqS0TMGi6d4FNerkx ZNJNl3mC33XyvnXYbqxrG+F/FxJ9J92Jfq1ywlHLU= X-Google-Smtp-Source: AGHT+IFs7JnwCZF3NlkjAe5AZMOsJEqpWtZWi4do689DUW1CWT4x6RCJVCXfNTgLWCAIqTz1hys/pg== X-Received: by 2002:a17:903:2c04:b0:295:50f5:c0e3 with SMTP id d9443c01a7336-2962ada2f5emr7023675ad.14.1762279780173; Tue, 04 Nov 2025 10:09:40 -0800 (PST) Received: from phoenix.lan (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id 41be03b00d2f7-ba1f86b0688sm3035988a12.28.2025.11.04.10.09.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 04 Nov 2025 10:09:39 -0800 (PST) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger , Bruce Richardson , Khadem Ullah <14pwcse1224@uetpeshawar.edu.pk>, Reshma Pattan Subject: [PATCH v6 8/8] doc: update documentation on pdump library Date: Tue, 4 Nov 2025 10:07:12 -0800 Message-ID: <20251104180927.403355-9-stephen@networkplumber.org> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20251104180927.403355-1-stephen@networkplumber.org> References: <20250811213632.16023-1-stephen@networkplumber.org> <20251104180927.403355-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