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 BE3294897F; Sun, 19 Oct 2025 18:58:18 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 93F1C42E46; Sun, 19 Oct 2025 18:57:43 +0200 (CEST) Received: from mail-pl1-f173.google.com (mail-pl1-f173.google.com [209.85.214.173]) by mails.dpdk.org (Postfix) with ESMTP id 4986342DDE for ; Sun, 19 Oct 2025 18:57:39 +0200 (CEST) Received: by mail-pl1-f173.google.com with SMTP id d9443c01a7336-290dc63fabbso22287395ad.0 for ; Sun, 19 Oct 2025 09:57:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1760893058; x=1761497858; 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=TLQVPjprVJZBMp1YSBB8l2fBZ//N4IBcB6boO58uflc=; b=21+fOG/GDYy+xdWl7bxtQNHgBcrPkI+yRbmJdFU/dnzgWB1eN+FWvtmWPbZg6XhDun AmAqgG1X5KHfMqL/PRNp3nus1Jz+GAnu9N/VHECf27Pnw4kdKPZd0j6CqQKtNdRJs1yb 2homVgrBKKMU4BSCt5ECtLUFm87p2t+CYRnDyaV1wJTyzlc0yH2u3788vA5DlST3eq1r Uljf0/hovZPptCcA3j3LG7xmbarnvJfHIrw1mrZMe66kfhGX0PwT3Sx3TKmCJWIcAqUo U2oIrHJoa6rG52mbFLwsP6OZplCEUClE/U/kzqHUv1ZPluf9puib+HPoDH53sf2mwJXa kMyQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1760893058; x=1761497858; 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=TLQVPjprVJZBMp1YSBB8l2fBZ//N4IBcB6boO58uflc=; b=euarLmmfJlfA8G6vgV9o9AImWBnaVcNCu9ObChky2/JhnL8KHz4sCC4LLrMkibQu3O kASkcD5y6EMxno2xiplqgwhxn/CRDZFpCcv8/7DC7Y6exc62C95xMfJb9j8MJ0wpOF6G QwnwuPx275ogEnkec/yDFsbSnd4n+IGosgOfnBDx8GEDV0HwzR0y+GBEjVmsB/8pNq9E DDDJ1vnnlijT9QbJUtYY+8kMLcNliunGeMaYDXATr7znqITx7gx6IEHKRALAHm1ujLEx esTjqhM53yU6xiaDS2qxZm2ce/GMunF/FgEQ8b185By5szRiBwjHy908kssPl+2UD4Zf lX3g== X-Gm-Message-State: AOJu0YwikbCEd98v5mZ7vouaI1SR4oQTLsg2hgFnpcWrJyoKtkBxq50A qz9E6Af7nUeuoT7GlWEFbdEvXaExkKn7Cyn2tAi9QXKu6iClpLgg7OzQxUXHOMzDm6OTFAz85Qa KsJ8Tst4= X-Gm-Gg: ASbGncuJMBaWYs9AczgK64ZZhpTIDTQERuCEOimnAdmnkBOhTTlUmMxU9NyafAw7i8R iqsBPXBPHSp0sPY0pLRyNpUPmGhwDX6E0R0L4yv+ZLAs4QWqPm1QgTV/Xq+hBsFKrzGzZriW91E KigDNVwV6/YvG6hJU5ZJWM30BNsRAFwfbPkmlDUszJPPemmSWHBnMAtvx8W01Xg6cDje31W+1yk 6WzeEEYrtpCCStyDYGmuIYaLpOiY6LFGokpUwAQSFSCYwqKspJuGLmLXR62nSGLNnaQN/oqE/FG JTh2bRxQz04nJgncEr6ftfwqTLJCvSSweZw2OSxT8P0RMHZotK9QIzxyI22chpnjS7T3B72DgC8 ClLmLmydX8dwFja1gilkyCOai1ygBFLv/YBia3npzH7ILwQQXp5o+P4fr06MHnbf0iaUYr4W3g0 gUlKgmfZLDZBzkVydprc03Aeef6p2ak/gsCzLdHwUMDQpvRzDilw== X-Google-Smtp-Source: AGHT+IF3b/n9Ytd/wmxE8ilQTVTyThaELdKkC7huhByJ+CPU1yvvr84iOzGsx0GzksVM45PVYcuSTA== X-Received: by 2002:a17:902:d2c9:b0:286:74e3:3889 with SMTP id d9443c01a7336-290cba42e4fmr151016275ad.55.1760893058323; Sun, 19 Oct 2025 09:57:38 -0700 (PDT) Received: from phoenix.lan (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-2924721b6fdsm56940455ad.118.2025.10.19.09.57.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 19 Oct 2025 09:57:37 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger , Reshma Pattan Subject: [PATCH v3 8/8] doc: update documentation on pdump library Date: Sun, 19 Oct 2025 09:56:15 -0700 Message-ID: <20251019165728.164929-9-stephen@networkplumber.org> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20251019165728.164929-1-stephen@networkplumber.org> References: <250811213632.16023-1-stephen@networkplumber.org> <20251019165728.164929-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 --- 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 17d2deaa07..a47c9ad89d 100644 --- a/doc/guides/rel_notes/release_25_11.rst +++ b/doc/guides/rel_notes/release_25_11.rst @@ -107,6 +107,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