Skip to content

Commit

Permalink
DPDK/PF_RING examples README fixes (#1264)
Browse files Browse the repository at this point in the history
  • Loading branch information
seladb authored Dec 14, 2023
1 parent 660843e commit c46c99f
Show file tree
Hide file tree
Showing 3 changed files with 17 additions and 14 deletions.
7 changes: 4 additions & 3 deletions Examples/DpdkBridge/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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


Expand Down
15 changes: 8 additions & 7 deletions Examples/DpdkExample-FilterTraffic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
9 changes: 5 additions & 4 deletions Examples/PfRingExample-FilterTraffic/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 <PF_RING_LOCATION>/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'

Expand Down

0 comments on commit c46c99f

Please sign in to comment.