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 2913C46D29; Thu, 14 Aug 2025 18:54:05 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 53EA0427C5; Thu, 14 Aug 2025 18:53:31 +0200 (CEST) Received: from mail-wr1-f44.google.com (mail-wr1-f44.google.com [209.85.221.44]) by mails.dpdk.org (Postfix) with ESMTP id 03045427D4 for ; Thu, 14 Aug 2025 18:53:29 +0200 (CEST) Received: by mail-wr1-f44.google.com with SMTP id ffacd0b85a97d-3b9e414252dso601219f8f.3 for ; Thu, 14 Aug 2025 09:53:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1755190408; x=1755795208; 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=J/ybt7TAO1JX/an/keMZ498FM8FVQEaW1+9X3iYLoX4=; b=up0D06B18fXT8Df+DbkPWSkKd5cNzNMfzL5+nLf7lGgSc4Pg/BLGvh0DTdYq25d9D4 FTioxdk4NZDpNzWYSdmnssapkwbwJ7nFvX1L2zWQtgNToUeL7+bFpmMiX1iCVkcumtoe /FST7QiNZUxn1099dgHfRRbYUr5esbIquVzkzUUsjj66iIqb3LM8fDcLDlHBHaXA97qE ey69+qaTNdj8yMGV+1r4YzpBEU8I2ziKheoqaYQBarPZXbndsKtPvOBdbSLIMhwsvdkQ DAC59uZLtdDrwcVxUzbbP0lTD1gbWEVOQl76//Px/DynoDcewi+045L70q7cEar8SqyI mrrw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1755190408; x=1755795208; 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=J/ybt7TAO1JX/an/keMZ498FM8FVQEaW1+9X3iYLoX4=; b=Jkj0jJ5eMLugoO+LNSApb/VwWB58EtKIIImqDohQ41V+7gcUHUbvszUXBDuJZ5FgU+ IHyuKzn8Y0HiOef/aOe5iG6yRzHj4x5rJ5I29qWgJb3fQyhUzhYPfjWmfSVCBH7VA/rA NkCEHvZeHT+8GCMEfFUqertlDVVlriyDQaHtkw+kYWYfl+5nTHAooL+/XAJlGRe9UVI/ /mmSyNYHHtr3Tvqdn2DYmYo9ePmeb72fZN/sjQFAgDPS/Q/sc3iAFyebmBSKSzdPlk94 9F4GSSAa3PnvpXD48kMIFzNd5VpwHQR5IUhzJjXM1Ov5/PveYKLCcojHBsHeF5zsyBY/ 0rkg== X-Gm-Message-State: AOJu0YxG7dvWYlyn/QAq68czt63qW7KxqFLMMLSl8lCCNDMPJ/rBxJo1 qQ0pLK5DAKTBi7VkvrGAqtefxAOdEwq3aC0kua4JjRDJX4Ag2shbxTOb7OptUw7oNNghgPA/19N s2XJ2 X-Gm-Gg: ASbGnctPm3Qzx0pSg7Hzo53pKt4hryYJPeG3RzZ6aj0Pn9EP5w1yVJQL3iRK4O6lqOr LEbBUQdQ3JfTgq9smnWmbW+rVSQYdQohP/Qy4d1Zi8B6kRENnErc/QautPZFBB8vctSv/G2pT7J G/ncB1D+OWASXwhIakQma5BOGTB3Er2WaL5JnOegD48wX7peK4ISzDfZBQgvO0+es4+SNcuUhNA IObDk6qFk0VN5HzFa1ppIIMfYwUWWmmk2znKxYMK6ZQuwB6aaXxIbz5L8S7bJPqmdRCFsnwYzQX tY7rQTeaAt5n2KyV9nu/shYG/BHp+PMwYGSSoXxOWF0YGAMuKfvSBgZvK7RMhNdUUZ0Ugj8e473 14Gl3h1tFJ1C4nA332Uhd+GDNwTh8L7rw8Gk42xTneWWl07Zf4dpjWopoWJYHN1gr+ydLXMU1 X-Google-Smtp-Source: AGHT+IE/Jrc68EeA8uL1WK/7sJLTyuKcObtkiTdcasbSdUtf1DcHO4rBZakW/t62fwtItX+Ynu/6Wg== X-Received: by 2002:a05:6000:2502:b0:3b9:1342:f8ac with SMTP id ffacd0b85a97d-3b9fc3595fbmr3218512f8f.31.1755190408425; Thu, 14 Aug 2025 09:53:28 -0700 (PDT) Received: from hermes.lan (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-3ba54f87e17sm1748197f8f.23.2025.08.14.09.53.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 14 Aug 2025 09:53:28 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger , Reshma Pattan Subject: [PATCH v2 8/8] doc: update documentation on pdump library Date: Thu, 14 Aug 2025 09:53:04 -0700 Message-ID: <20250814165307.12786-9-stephen@networkplumber.org> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250814165307.12786-1-stephen@networkplumber.org> References: <20250811213632.16023-1-stephen@networkplumber.org> <20250814165307.12786-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. Signed-off-by: Stephen Hemminger --- doc/guides/prog_guide/img/pdump_overview.svg | 135 ++++++++++++++ doc/guides/prog_guide/pdump_lib.rst | 183 ++++++++++++------- 2 files changed, 250 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. -- 2.47.2