From c46c99f566ee6da3ef9918a1e498213f903f0b77 Mon Sep 17 00:00:00 2001 From: seladb Date: Thu, 14 Dec 2023 00:17:40 -0800 Subject: [PATCH] DPDK/PF_RING examples README fixes (#1264) --- Examples/DpdkBridge/README.md | 7 ++++--- Examples/DpdkExample-FilterTraffic/README.md | 15 ++++++++------- Examples/PfRingExample-FilterTraffic/README.md | 9 +++++---- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/Examples/DpdkBridge/README.md b/Examples/DpdkBridge/README.md index 16f63039c8..483e516d54 100644 --- a/Examples/DpdkBridge/README.md +++ b/Examples/DpdkBridge/README.md @@ -2,7 +2,7 @@ DPDK Bridge example application =============================== This application demonstrates how to create a bridge between two network devices using PcapPlusPlus DPDK APIs. -It listens to two DPDK ports (a.k.a DPDK devices), and forwards all the traffic received on one port to the other, acting like a L2 bridge. +It listens to two DPDK ports (a.k.a. DPDK devices), and forwards all the traffic received on one port to the other, acting like a L2 bridge. The application is very similar to [DPDK's L2 forwarding example](https://doc.dpdk.org/guides/sample_app_ug/l2_forward_real_virtual.html) and demonstrates how to achieve the same functionality with PcapPlusPlus using less and easier to understand C++ code. @@ -12,9 +12,10 @@ one for receiving packets on NIC#1 and sending them to NIC#2, and another for re Important: ---------- -- This application runs only on Linux (DPDK is not supported on Windows and Mac OS X) +- This application runs only on Linux (DPDK is not supported on non-Linux platforms) +- In order to build this application follow the instructions on how to build PcapPlusPlus with DPDK - This application (like all applications using DPDK) should be run as 'sudo' -- In order to test this application you need an envorinment where the bridge is connected directly (back-to-back) to the two machines the +- In order to test this application you need an environment where the bridge is connected directly (back-to-back) to the two machines the bridge wants to connect diff --git a/Examples/DpdkExample-FilterTraffic/README.md b/Examples/DpdkExample-FilterTraffic/README.md index bbcf8a0aa2..283d6dad99 100644 --- a/Examples/DpdkExample-FilterTraffic/README.md +++ b/Examples/DpdkExample-FilterTraffic/README.md @@ -3,13 +3,12 @@ Filter Traffic DPDK example application This application demonstrates PcapPlusPlus DPDK APIs. -It listens to one or more DPDK ports (a.k.a DPDK devices), captures all traffic and matches packets by user-defined matching criteria such as source/dest IP, source/dest TCP/UDP port and more. -Matched packets can be send to another DPDK port and/or be saved to a pcap file. +It listens to one or more DPDK ports (a.k.a. DPDK devices), captures all traffic and matches packets by user-defined matching criteria such as source/dest IP, source/dest TCP/UDP port and more. +Matched packets can be sent to another DPDK port and/or be saved to a pcap file. -In addition the application collects statistics on received and matched packets (such as number of packets per protocol, number of matched flows and number of matched packets). +In addition, the application collects statistics on received and matched packets (such as number of packets per protocol, number of matched flows and number of matched packets). Matching is done per flow, meaning the first packet received on a flow is matched against the matching criteria and if it's matched then all packets of the same flow will be matched too. - The application uses the concept of worker threads. Number of cores can be set by the user or set to default (default is all machine cores minus one management core). Each core is assigned with one worker thread. The application divides the DPDK ports and RX queues equally between worker threads. For example: if there are 2 DPDK ports to listen to, each one with 6 RX queues and there are 3 worker threads, then worker #1 will get RX queues 1-4 of port 1, worker #2 will get RX queues 5-6 of port 1 @@ -19,14 +18,16 @@ Each worker thread does exactly the same work: receiving packets, collecting pac Important: ---------- -- This application runs only on Linux (DPDK is not supported on Windows and Mac OS X) +- This application runs only on Linux (DPDK is not supported on non-Linux platforms) +- In order to build this application follow the instructions on how to build PcapPlusPlus with DPDK - This application (like all applications using DPDK) should be run as 'sudo' Using the utility ----------------- - DpdkTrafficFilter [-hvl] [-s PORT] [-f FILENAME] [-i IPV4_ADDR] [-I IPV4_ADDR] [-p PORT] [-P PORT] [-r PROTOCOL] - [-c CORE_MASK] [-m POOL_SIZE] [-r NUM_QUEUES] [-t NUM_QUEUES] -d PORT_1,PORT_3,...,PORT_N + Basic usage: + DpdkTrafficFilter [-hvl] [-s PORT] [-f FILENAME] [-i IPV4_ADDR] [-I IPV4_ADDR] [-p PORT] [-P PORT] [-r PROTOCOL] + [-c CORE_MASK] [-m POOL_SIZE] [-r NUM_QUEUES] [-t NUM_QUEUES] -d PORT_1,PORT_3,...,PORT_N Options: -h|--help : Displays this help message and exits diff --git a/Examples/PfRingExample-FilterTraffic/README.md b/Examples/PfRingExample-FilterTraffic/README.md index 07ab33c937..60e18e0f43 100644 --- a/Examples/PfRingExample-FilterTraffic/README.md +++ b/Examples/PfRingExample-FilterTraffic/README.md @@ -3,10 +3,11 @@ Filter Traffic PF_RING example application This application demonstrates PcapPlusPlus PF_RING APIs. It listens to a PF_RING interface, captures all traffic and matches packets by user-defined matching criteria such as source/dest IP, source/dest TCP/UDP port and more. -Matched packets can be send to another PF_RING interface and/or be save to a pcap file. In addition the application collects statistics on received and matched packets. -In addition the application collect statistics on received and matched packets: number of packets per protocol, number of matched flows and number of matched packets. +Matched packets can be sent to another PF_RING interface and/or be saved to a pcap file. -The application uses PfRingDevice's multi-threaded capturing. Number of capture threads can be set by the user (to the maximum of machine's core number minus 1) or set to default +In addition, the application collect statistics on received and matched packets: number of packets per protocol, number of matched flows and number of matched packets. + +The application uses PfRingDevice's multithreading capturing. Number of capture threads can be set by the user (to the maximum of machine's core number minus 1) or set to default (default is all machine cores minus one management core the application runs on). Each core is assigned with one capture thread. PfRingDevice tries to assign one RX channel for each capturing thread (to improve performance), but if NIC doesn't enough RX channels to provide one for each thread, it will assign several thread with the same RX channel For example: if NIC supports 4 RX channels but the user asks for 6 capturing threads than 4 cores will share 2 RX channels and the 2 remaining cores will use RX channels of their own. @@ -17,7 +18,7 @@ Another thing this application demonstrates is getting interface details such as Important: ---------- - This application runs only on Linux (PF_RING is not supported on Windows and Mac OS X) -- Before compiling this application make sure you set Compile PcapPlusPlus with PF_RING to y in configure-linux.sh. Otherwise the application won't compile +- In order to build this application follow the instructions on how to build PcapPlusPlus with PF_RING - Before running the application make sure you load the PF_RING kernel module: sudo insmod /kernel/pf_ring.ko , otherwise the application will exit with an error log that instructs you to load the kernel module - This application (like all applications using PF_RING) should be run as 'sudo'