@@ -91,6 +91,7 @@ Contents:
operstates
packet_mmap
phonet
+ pktgen
.. only:: subproject and html
similarity index 62%
rename from Documentation/networking/pktgen.txt
rename to Documentation/networking/pktgen.rst
@@ -1,7 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
-
- HOWTO for the linux packet generator
- ------------------------------------
+====================================
+HOWTO for the linux packet generator
+====================================
Enable CONFIG_NET_PKTGEN to compile and build pktgen either in-kernel
or as a module. A module is preferred; modprobe pktgen if needed. Once
@@ -9,17 +10,18 @@ running, pktgen creates a thread for each CPU with affinity to that CPU.
Monitoring and controlling is done via /proc. It is easiest to select a
suitable sample script and configure that.
-On a dual CPU:
+On a dual CPU::
-ps aux | grep pkt
-root 129 0.3 0.0 0 0 ? SW 2003 523:20 [kpktgend_0]
-root 130 0.3 0.0 0 0 ? SW 2003 509:50 [kpktgend_1]
+ ps aux | grep pkt
+ root 129 0.3 0.0 0 0 ? SW 2003 523:20 [kpktgend_0]
+ root 130 0.3 0.0 0 0 ? SW 2003 509:50 [kpktgend_1]
-For monitoring and control pktgen creates:
+For monitoring and control pktgen creates::
+
/proc/net/pktgen/pgctrl
/proc/net/pktgen/kpktgend_X
- /proc/net/pktgen/ethX
+ /proc/net/pktgen/ethX
Tuning NIC for max performance
@@ -28,7 +30,8 @@ Tuning NIC for max performance
The default NIC settings are (likely) not tuned for pktgen's artificial
overload type of benchmarking, as this could hurt the normal use-case.
-Specifically increasing the TX ring buffer in the NIC:
+Specifically increasing the TX ring buffer in the NIC::
+
# ethtool -G ethX tx 1024
A larger TX ring can improve pktgen's performance, while it can hurt
@@ -46,7 +49,8 @@ This cleanup issue is specifically the case for the driver ixgbe
and the cleanup interval is affected by the ethtool --coalesce setting
of parameter "rx-usecs".
-For ixgbe use e.g. "30" resulting in approx 33K interrupts/sec (1/30*10^6):
+For ixgbe use e.g. "30" resulting in approx 33K interrupts/sec (1/30*10^6)::
+
# ethtool -C ethX rx-usecs 30
@@ -55,7 +59,7 @@ Kernel threads
Pktgen creates a thread for each CPU with affinity to that CPU.
Which is controlled through procfile /proc/net/pktgen/kpktgend_X.
-Example: /proc/net/pktgen/kpktgend_0
+Example: /proc/net/pktgen/kpktgend_0::
Running:
Stopped: eth4@0
@@ -64,6 +68,7 @@ Example: /proc/net/pktgen/kpktgend_0
Most important are the devices assigned to the thread.
The two basic thread commands are:
+
* add_device DEVICE@NAME -- adds a single device
* rem_device_all -- remove all associated devices
@@ -73,7 +78,7 @@ be unique.
To support adding the same device to multiple threads, which is useful
with multi queue NICs, the device naming scheme is extended with "@":
- device@something
+device@something
The part after "@" can be anything, but it is custom to use the thread
number.
@@ -83,30 +88,30 @@ Viewing devices
The Params section holds configured information. The Current section
holds running statistics. The Result is printed after a run or after
-interruption. Example:
+interruption. Example::
-/proc/net/pktgen/eth4@0
+ /proc/net/pktgen/eth4@0
- Params: count 100000 min_pkt_size: 60 max_pkt_size: 60
- frags: 0 delay: 0 clone_skb: 64 ifname: eth4@0
- flows: 0 flowlen: 0
- queue_map_min: 0 queue_map_max: 0
- dst_min: 192.168.81.2 dst_max:
- src_min: src_max:
- src_mac: 90:e2:ba:0a:56:b4 dst_mac: 00:1b:21:3c:9d:f8
- udp_src_min: 9 udp_src_max: 109 udp_dst_min: 9 udp_dst_max: 9
- src_mac_count: 0 dst_mac_count: 0
- Flags: UDPSRC_RND NO_TIMESTAMP QUEUE_MAP_CPU
- Current:
- pkts-sofar: 100000 errors: 0
- started: 623913381008us stopped: 623913396439us idle: 25us
- seq_num: 100001 cur_dst_mac_offset: 0 cur_src_mac_offset: 0
- cur_saddr: 192.168.8.3 cur_daddr: 192.168.81.2
- cur_udp_dst: 9 cur_udp_src: 42
- cur_queue_map: 0
- flows: 0
- Result: OK: 15430(c15405+d25) usec, 100000 (60byte,0frags)
- 6480562pps 3110Mb/sec (3110669760bps) errors: 0
+ Params: count 100000 min_pkt_size: 60 max_pkt_size: 60
+ frags: 0 delay: 0 clone_skb: 64 ifname: eth4@0
+ flows: 0 flowlen: 0
+ queue_map_min: 0 queue_map_max: 0
+ dst_min: 192.168.81.2 dst_max:
+ src_min: src_max:
+ src_mac: 90:e2:ba:0a:56:b4 dst_mac: 00:1b:21:3c:9d:f8
+ udp_src_min: 9 udp_src_max: 109 udp_dst_min: 9 udp_dst_max: 9
+ src_mac_count: 0 dst_mac_count: 0
+ Flags: UDPSRC_RND NO_TIMESTAMP QUEUE_MAP_CPU
+ Current:
+ pkts-sofar: 100000 errors: 0
+ started: 623913381008us stopped: 623913396439us idle: 25us
+ seq_num: 100001 cur_dst_mac_offset: 0 cur_src_mac_offset: 0
+ cur_saddr: 192.168.8.3 cur_daddr: 192.168.81.2
+ cur_udp_dst: 9 cur_udp_src: 42
+ cur_queue_map: 0
+ flows: 0
+ Result: OK: 15430(c15405+d25) usec, 100000 (60byte,0frags)
+ 6480562pps 3110Mb/sec (3110669760bps) errors: 0
Configuring devices
@@ -114,11 +119,12 @@ Configuring devices
This is done via the /proc interface, and most easily done via pgset
as defined in the sample scripts.
You need to specify PGDEV environment variable to use functions from sample
-scripts, i.e.:
-export PGDEV=/proc/net/pktgen/eth4@0
-source samples/pktgen/functions.sh
+scripts, i.e.::
-Examples:
+ export PGDEV=/proc/net/pktgen/eth4@0
+ source samples/pktgen/functions.sh
+
+Examples::
pg_ctrl start starts injection.
pg_ctrl stop aborts injection. Also, ^C aborts generator.
@@ -126,17 +132,17 @@ Examples:
pgset "clone_skb 1" sets the number of copies of the same packet
pgset "clone_skb 0" use single SKB for all transmits
pgset "burst 8" uses xmit_more API to queue 8 copies of the same
- packet and update HW tx queue tail pointer once.
- "burst 1" is the default
+ packet and update HW tx queue tail pointer once.
+ "burst 1" is the default
pgset "pkt_size 9014" sets packet size to 9014
pgset "frags 5" packet will consist of 5 fragments
pgset "count 200000" sets number of packets to send, set to zero
- for continuous sends until explicitly stopped.
+ for continuous sends until explicitly stopped.
pgset "delay 5000" adds delay to hard_start_xmit(). nanoseconds
pgset "dst 10.0.0.1" sets IP destination address
- (BEWARE! This generator is very aggressive!)
+ (BEWARE! This generator is very aggressive!)
pgset "dst_min 10.0.0.1" Same as dst
pgset "dst_max 10.0.0.254" Set the maximum destination IP.
@@ -149,46 +155,46 @@ Examples:
pgset "queue_map_min 0" Sets the min value of tx queue interval
pgset "queue_map_max 7" Sets the max value of tx queue interval, for multiqueue devices
- To select queue 1 of a given device,
- use queue_map_min=1 and queue_map_max=1
+ To select queue 1 of a given device,
+ use queue_map_min=1 and queue_map_max=1
pgset "src_mac_count 1" Sets the number of MACs we'll range through.
- The 'minimum' MAC is what you set with srcmac.
+ The 'minimum' MAC is what you set with srcmac.
pgset "dst_mac_count 1" Sets the number of MACs we'll range through.
- The 'minimum' MAC is what you set with dstmac.
+ The 'minimum' MAC is what you set with dstmac.
pgset "flag [name]" Set a flag to determine behaviour. Current flags
- are: IPSRC_RND # IP source is random (between min/max)
- IPDST_RND # IP destination is random
- UDPSRC_RND, UDPDST_RND,
- MACSRC_RND, MACDST_RND
- TXSIZE_RND, IPV6,
- MPLS_RND, VID_RND, SVID_RND
- FLOW_SEQ,
- QUEUE_MAP_RND # queue map random
- QUEUE_MAP_CPU # queue map mirrors smp_processor_id()
- UDPCSUM,
- IPSEC # IPsec encapsulation (needs CONFIG_XFRM)
- NODE_ALLOC # node specific memory allocation
- NO_TIMESTAMP # disable timestamping
+ are: IPSRC_RND # IP source is random (between min/max)
+ IPDST_RND # IP destination is random
+ UDPSRC_RND, UDPDST_RND,
+ MACSRC_RND, MACDST_RND
+ TXSIZE_RND, IPV6,
+ MPLS_RND, VID_RND, SVID_RND
+ FLOW_SEQ,
+ QUEUE_MAP_RND # queue map random
+ QUEUE_MAP_CPU # queue map mirrors smp_processor_id()
+ UDPCSUM,
+ IPSEC # IPsec encapsulation (needs CONFIG_XFRM)
+ NODE_ALLOC # node specific memory allocation
+ NO_TIMESTAMP # disable timestamping
pgset 'flag ![name]' Clear a flag to determine behaviour.
- Note that you might need to use single quote in
- interactive mode, so that your shell wouldn't expand
- the specified flag as a history command.
+ Note that you might need to use single quote in
+ interactive mode, so that your shell wouldn't expand
+ the specified flag as a history command.
pgset "spi [SPI_VALUE]" Set specific SA used to transform packet.
pgset "udp_src_min 9" set UDP source port min, If < udp_src_max, then
- cycle through the port range.
+ cycle through the port range.
pgset "udp_src_max 9" set UDP source port max.
pgset "udp_dst_min 9" set UDP destination port min, If < udp_dst_max, then
- cycle through the port range.
+ cycle through the port range.
pgset "udp_dst_max 9" set UDP destination port max.
pgset "mpls 0001000a,0002000a,0000000a" set MPLS labels (in this example
- outer label=16,middle label=32,
+ outer label=16,middle label=32,
inner label=0 (IPv4 NULL)) Note that
there must be no spaces between the
arguments. Leading zeros are required.
@@ -232,10 +238,14 @@ A collection of tutorial scripts and helpers for pktgen is in the
samples/pktgen directory. The helper parameters.sh file support easy
and consistent parameter parsing across the sample scripts.
-Usage example and help:
+Usage example and help::
+
./pktgen_sample01_simple.sh -i eth4 -m 00:1B:21:3C:9D:F8 -d 192.168.8.2
-Usage: ./pktgen_sample01_simple.sh [-vx] -i ethX
+Usage:::
+
+ ./pktgen_sample01_simple.sh [-vx] -i ethX
+
-i : ($DEV) output interface/device (required)
-s : ($PKT_SIZE) packet size
-d : ($DEST_IP) destination IP
@@ -250,13 +260,13 @@ The global variables being set are also listed. E.g. the required
interface/device parameter "-i" sets variable $DEV. Copy the
pktgen_sampleXX scripts and modify them to fit your own needs.
-The old scripts:
+The old scripts::
-pktgen.conf-1-2 # 1 CPU 2 dev
-pktgen.conf-1-1-rdos # 1 CPU 1 dev w. route DoS
-pktgen.conf-1-1-ip6 # 1 CPU 1 dev ipv6
-pktgen.conf-1-1-ip6-rdos # 1 CPU 1 dev ipv6 w. route DoS
-pktgen.conf-1-1-flows # 1 CPU 1 dev multiple flows.
+ pktgen.conf-1-2 # 1 CPU 2 dev
+ pktgen.conf-1-1-rdos # 1 CPU 1 dev w. route DoS
+ pktgen.conf-1-1-ip6 # 1 CPU 1 dev ipv6
+ pktgen.conf-1-1-ip6-rdos # 1 CPU 1 dev ipv6 w. route DoS
+ pktgen.conf-1-1-flows # 1 CPU 1 dev multiple flows.
Interrupt affinity
@@ -271,10 +281,10 @@ to the running threads CPU (directly from smp_processor_id()).
Enable IPsec
============
Default IPsec transformation with ESP encapsulation plus transport mode
-can be enabled by simply setting:
+can be enabled by simply setting::
-pgset "flag IPSEC"
-pgset "flows 1"
+ pgset "flag IPSEC"
+ pgset "flows 1"
To avoid breaking existing testbed scripts for using AH type and tunnel mode,
you can use "pgset spi SPI_VALUE" to specify which transformation mode
@@ -284,115 +294,117 @@ to employ.
Current commands and configuration options
==========================================
-** Pgcontrol commands:
+**Pgcontrol commands**::
-start
-stop
-reset
+ start
+ stop
+ reset
-** Thread commands:
+**Thread commands**::
-add_device
-rem_device_all
+ add_device
+ rem_device_all
-** Device commands:
+**Device commands**::
-count
-clone_skb
-burst
-debug
+ count
+ clone_skb
+ burst
+ debug
-frags
-delay
+ frags
+ delay
-src_mac_count
-dst_mac_count
+ src_mac_count
+ dst_mac_count
-pkt_size
-min_pkt_size
-max_pkt_size
+ pkt_size
+ min_pkt_size
+ max_pkt_size
-queue_map_min
-queue_map_max
-skb_priority
+ queue_map_min
+ queue_map_max
+ skb_priority
-tos (ipv4)
-traffic_class (ipv6)
+ tos (ipv4)
+ traffic_class (ipv6)
-mpls
+ mpls
-udp_src_min
-udp_src_max
+ udp_src_min
+ udp_src_max
-udp_dst_min
-udp_dst_max
+ udp_dst_min
+ udp_dst_max
-node
+ node
-flag
- IPSRC_RND
- IPDST_RND
- UDPSRC_RND
- UDPDST_RND
- MACSRC_RND
- MACDST_RND
- TXSIZE_RND
- IPV6
- MPLS_RND
- VID_RND
- SVID_RND
- FLOW_SEQ
- QUEUE_MAP_RND
- QUEUE_MAP_CPU
- UDPCSUM
- IPSEC
- NODE_ALLOC
- NO_TIMESTAMP
+ flag
+ IPSRC_RND
+ IPDST_RND
+ UDPSRC_RND
+ UDPDST_RND
+ MACSRC_RND
+ MACDST_RND
+ TXSIZE_RND
+ IPV6
+ MPLS_RND
+ VID_RND
+ SVID_RND
+ FLOW_SEQ
+ QUEUE_MAP_RND
+ QUEUE_MAP_CPU
+ UDPCSUM
+ IPSEC
+ NODE_ALLOC
+ NO_TIMESTAMP
-spi (ipsec)
+ spi (ipsec)
-dst_min
-dst_max
+ dst_min
+ dst_max
-src_min
-src_max
+ src_min
+ src_max
-dst_mac
-src_mac
+ dst_mac
+ src_mac
-clear_counters
+ clear_counters
-src6
-dst6
-dst6_max
-dst6_min
+ src6
+ dst6
+ dst6_max
+ dst6_min
-flows
-flowlen
+ flows
+ flowlen
-rate
-ratep
+ rate
+ ratep
-xmit_mode <start_xmit|netif_receive>
+ xmit_mode <start_xmit|netif_receive>
-vlan_cfi
-vlan_id
-vlan_p
+ vlan_cfi
+ vlan_id
+ vlan_p
-svlan_cfi
-svlan_id
-svlan_p
+ svlan_cfi
+ svlan_id
+ svlan_p
References:
-ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/
-ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/
+
+- ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/
+- tp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/
Paper from Linux-Kongress in Erlangen 2004.
-ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/pktgen_paper.pdf
+- ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/pktgen_paper.pdf
Thanks to:
+
Grant Grundler for testing on IA-64 and parisc, Harald Welte, Lennert Buytenhek
Stephen Hemminger, Andi Kleen, Dave Miller and many others.
@@ -344,7 +344,7 @@ config NET_PKTGEN
what was just said, you don't need it: say N.
Documentation on how to use the packet generator can be found
- at <file:Documentation/networking/pktgen.txt>.
+ at <file:Documentation/networking/pktgen.rst>.
To compile this code as a module, choose M here: the
module will be called pktgen.
@@ -56,7 +56,7 @@
* Integrated to 2.5.x 021029 --Lucio Maciel (luciomaciel@zipmail.com.br)
*
* 021124 Finished major redesign and rewrite for new functionality.
- * See Documentation/networking/pktgen.txt for how to use this.
+ * See Documentation/networking/pktgen.rst for how to use this.
*
* The new operation:
* For each CPU one thread/process is created at start. This process checks
@@ -3,7 +3,7 @@ Sample and benchmark scripts for pktgen (packet generator)
This directory contains some pktgen sample and benchmark scripts, that
can easily be copied and adjusted for your own use-case.
-General doc is located in kernel: Documentation/networking/pktgen.txt
+General doc is located in kernel: Documentation/networking/pktgen.rst
Helper include files
====================
- add SPDX header; - adjust title markup; - use bold markups on a few places; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines where needed; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/networking/index.rst | 1 + .../networking/{pktgen.txt => pktgen.rst} | 316 +++++++++--------- net/Kconfig | 2 +- net/core/pktgen.c | 2 +- samples/pktgen/README.rst | 2 +- 5 files changed, 168 insertions(+), 155 deletions(-) rename Documentation/networking/{pktgen.txt => pktgen.rst} (62%)