diff options
Diffstat (limited to 'xdp-bench/xdp-bench.8')
| -rw-r--r-- | xdp-bench/xdp-bench.8 | 696 |
1 files changed, 696 insertions, 0 deletions
diff --git a/xdp-bench/xdp-bench.8 b/xdp-bench/xdp-bench.8 new file mode 100644 index 0000000..c89dd1b --- /dev/null +++ b/xdp-bench/xdp-bench.8 @@ -0,0 +1,696 @@ +.TH "xdp-bench" "8" "FEBRUARY 4, 2023" "V1.3.1" "A simple XDP benchmarking tool" + +.SH "NAME" +XDP-bench \- a simple XDP benchmarking tool +.SH "SYNOPSIS" +.PP +XDP-bench is a benchmarking utility for exercising the different operation modes +of XDP. It is intended to be a simple program demonstrating the various +operating modes; these include dropping packets, hairpin forwarding (using the +\fIXDP_TX\fP return code), and redirection using the various in-kernel packet +redirection facilities. + +.PP +The drop and TX modes support various options to control whether packet data is +touched (read or written) before being dropped or transmitted. The redirection +modes support using the simple ifindex-based \fIbpf_redirect\fP helper, the +\fIbpf_redirect_map\fP helper using a cpumap as its target, \fIbpf_redirect_map\fP using +a devmap as its target, and the devmap's broadcast mode which allows redirecting +to multiple devices. + +.PP +There is more information on the meaning of the output in both default (terse) +and extended output mode, in the \fBOutput Format Description\fP section below. + +.SS "Running xdp-bench" +.PP +The syntax for running xdp-bench is: + +.RS +.nf +\fCUsage: xdp-bench COMMAND [options] + +COMMAND can be one of: + drop - Drop all packets on an interface + tx - Transmit packets back out on an interface (hairpin forwarding) + redirect - XDP redirect using the bpf_redirect() helper + redirect-cpu - XDP CPU redirect using BPF_MAP_TYPE_CPUMAP + redirect-map - XDP redirect using BPF_MAP_TYPE_DEVMAP + redirect-multi - XDP multi-redirect using BPF_MAP_TYPE_DEVMAP and the BPF_F_BROADCAST flag +\fP +.fi +.RE + +.PP +Each command, and its options are explained below. Or use \fIxdp\-bench COMMAND +\-\-help\fP to see the options for each command. + +.SH "The DROP command" +.PP +In this mode, \fIxdp\-bench\fP installs an XDP program on an interface that simply +drops all packets. There are options to control what to do with the packet +before dropping it (touch the packet data or not), as well as which statistics +to gather. This is a basic benchmark for the baseline (best-case) performance of +XDP on an interface. + +.PP +The syntax for the \fIdrop\fP command is: + +.PP +\fIxdp\-bench drop [options] <ifname>\fP + +.PP +Where \fI<ifname>\fP is the name of the interface the XDP program should be +installed on. + +.PP +The supported options are: + +.SS "-p, --packet-operation <ACTION>" +.PP +Specify which operation should be taken on the packet before dropping it. The +following actions are available: + +.RS +.nf +\fCno-touch - Drop the packet without touching the packet data +touch - Read a field in the packet header before dropping +swap-macs - Swap the source and destination MAC addresses before dropping +\fP +.fi +.RE + +.PP +Whether to touch the packet before dropping it can have a significant +performance impact as this requires bringing packet data into the CPU cache (and +flushing it back out if writing). + +.PP +The default for this option is \fIno\-touch\fP. + +.SS "-r, --rxq-stats" +.PP +If set, the XDP program will also gather statistics on which receive queue index +each packet was received on. This is displayed in the extended output mode along +with per-CPU data (which, depending on the hardware configuration may or may not +be equivalent). + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + +.SH "The PASS command" +.PP +In this mode, \fIxdp\-bench\fP installs an XDP program on an interface that passes +all packets to the network stack after processing them (returning \fIXDP_PASS\fP). +There are options to control what to do with the packet before passing it +(touch the packet data or not), as well as which statistics to gather. This is a +basic benchmark for the overhead of installing an XDP program on an interface +while still running the regular network stack. + +.PP +The syntax for the \fIpass\fP command is: + +.PP +\fIxdp\-bench pass [options] <ifname>\fP + +.PP +Where \fI<ifname>\fP is the name of the interface the XDP program should be +installed on. + +.PP +The supported options are: + +.SS "-p, --packet-operation <ACTION>" +.PP +Specify which operation should be taken on the packet before passing it. The +following actions are available: + +.RS +.nf +\fCno-touch - Pass the packet without touching the packet data +touch - Read a field in the packet header before passing +swap-macs - Swap the source and destination MAC addresses before passing +\fP +.fi +.RE + +.PP +The default for this option is \fIno\-touch\fP. + +.SS "-r, --rxq-stats" +.PP +If set, the XDP program will also gather statistics on which receive queue index +each packet was received on. This is displayed in the extended output mode along +with per-CPU data (which, depending on the hardware configuration may or may not +be equivalent). + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + +.SH "The TX command" +.PP +In this mode, \fIxdp\-bench\fP installs an XDP program on an interface that performs +so-called "hairpin forwarding", which means each packet is transmitted back out +the same interface (using the \fIXDP_TX\fP return code).. There are options to +control what to do with the packet before transmitting it (touch the packet data +or not), as well as which statistics to gather. + +.PP +The syntax for the \fItx\fP command is: + +.PP +\fIxdp\-bench tx [options] <ifname>\fP + +.PP +Where \fI<ifname>\fP is the name of the interface the XDP program should be +installed on. + +.PP +The supported options are: + +.SS "-p, --packet-operation <ACTION>" +.PP +Specify which operation should be taken on the packet before transmitting it. The +following actions are available: + +.RS +.nf +\fCno-touch - Transmit the packet without touching the packet data +touch - Read a field in the packet header before transmitting +swap-macs - Swap the source and destination MAC addresses before transmitting +\fP +.fi +.RE + +.PP +To allow the packet to be successfully transmitted back to the sender, the MAC +addresses have to be swapped, so that the source MAC matches the network device. +However, there is a performance overhead in doing swapping, so this option +allows this function to be turned off. + +.PP +The default for this option is \fIswap\-macs\fP. + +.SS "-r, --rxq-stats" +.PP +If set, the XDP program will also gather statistics on which receive queue index +each packet was received on. This is displayed in the extended output mode along +with per-CPU data (which, depending on the hardware configuration may or may not +be equivalent). + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + +.SH "The REDIRECT command" +.PP +In this mode, \fIxdp\-bench\fP sets up packet redirection between the two +interfaces supplied on the command line using the \fIbpf_redirect\fP BPF helper +triggered on packet reception on the ingress interface. + +.PP +The syntax for the \fIredirect\fP command is: + +.PP +\fIxdp\-bench redirect [options] <ifname_in> <ifname_out>\fP + +.PP +Where \fI<ifname_in>\fP is the name of the input interface from where packets will +be redirect to the output interface \fI<ifname_out>\fP. + +.PP +The supported options are: + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-s, --stats" +.PP +Enable statistics for successful redirection. This option comes with a per +packet tracing overhead, for recording all successful redirections. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + +.SH "The REDIRECT-CPU command" +.PP +In this mode, \fIxdp\-bench\fP sets up packet redirection using the +\fIbpf_redirect_map\fP BPF helper triggered on packet reception on the ingress +interface, using a cpumap as its target. Hence, this tool can be used to +redirect packets on an interface from one CPU to another. In addition to this, +the tool then supports redirecting the packet to another output device when it +is processed on the target CPU. + +.PP +The syntax for the \fIredirect\-cpu\fP command is: + +.PP +\fIxdp\-bench redirect\-cpu [options] <ifname> \-c 0 ... \-c N\fP + +.PP +Where \fI<ifname>\fP is the name of the input interface from where packets will be +redirect to the target CPU list specified using \fI\-c\fP. + +.PP +The supported options are: + +.SS "-c, --cpu <CPU>" +.PP +Specify a possible target CPU index. This option must be passed at least once, +and can be passed multiple times to specify a list of CPUs. Which CPU is chosen +for a given packet depends on the value of the \fI\-\-program\-mode\fP option, +described below. + +.SS "-p, --program-mode <MODE>" +.PP +Specify a program that embeds a predefined policy deciding how packets are +redirected to different CPUs. The following options are available: + +.RS +.nf +\fCno-touch - Redirect without touching packet data +touch - Read packet data before redirecting +round-robin - Cycle between target CPUs in a round-robin fashion (for each packet) +l4-proto - Choose the target CPU based on the layer-4 protocol of packet +l4-filter - Like l4-proto, but drop UDP packets with destination port 9 (used by pktgen) +l4-hash - Use source and destination IP hashing to pick target CPU +\fP +.fi +.RE + +.PP +The \fIno\-touch\fP and \fItouch\fP modes always redirect packets to the same CPU (the +first value supplied to \fI\-\-cpu\fP). The \fIround\-robin\fP and \fIl4\-hash\fP modes +distribute packets between all the CPUs supplied as \fI\-\-cpu\fP arguments, while +\fIl4\-proto\fP and \fIl4\-filter\fP send TCP and unrecognised packets to CPU index 0, UDP +packets to CPU index 1 and ICMP packets to CPU index 2 (where the index refers +to the order the actual CPUs are given on the command line). + +.PP +The default for this option is \fIl4\-hash\fP. + +.SS "-r --remote-action <ACTION>" +.PP +If this option is set, a separate program is installed into the cpumap, which +will be invoked on the remote CPU after the packet is processed there. The +action can be either \fIdrop\fP or \fIpass\fP which will drop the packet or pass it to +the regular networking stack, respectively. Or it can be \fIredirect\fP, which will +cause the packet to be redirected to another interface and transmitted out that +interface on the remote CPU. If this option is set to \fIredirect\fP the target +device must be specified using \fI\-\-redirect\-device\fP. + +.PP +The default for this option is \fIdisabled\fP. + +.SS "-r, --redirect-device <IFNAME>" +.PP +Specify the device to redirect the packet to when it is received on the target CPU. +Note that this option can only be specified with \fI\-\-remote\-action redirect\fP. + +.SS "-q, --qsize <PACKETS>" +.PP +Set the queue size for the per-CPU cpumap ring buffer used for redirecting +packets from multiple CPUs to one CPU. The default value is 2048 packets. + +.SS "-x, --stress-mode" +.PP +Stress the cpumap implementation by deallocating and reallocating the cpumap +ring buffer on each polling interval. + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-s, --stats" +.PP +Enable statistics for successful redirection. This option comes with a per +packet tracing overhead, for recording all successful redirections. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + +.SH "The REDIRECT-MAP command" +.PP +In this mode, \fIxdp\-bench\fP sets up packet redirection between two interfaces +supplied on the command line using the \fIbpf_redirect_map()\fP BPF helper triggered +on packet reception on the ingress interface, using a devmap as its target. + +.PP +The syntax for the \fIredirect\-map\fP command is: + +.PP +\fIxdp\-bench redirect\-map [options] <ifname_in> <ifname_out>\fP + +.PP +Where \fI<ifname_in>\fP is the name of the input interface from where packets will +be redirect to the output interface \fI<ifname_out>\fP. + +.PP +The supported options are: + +.SS "-X, --load-egress" +.PP +Load a program in the devmap entry used for redirection, so that it is invoked +after the packet is redirected to the target device, before it is transmitted +out of the output interface. The remote program will update the packet data so +its source MAC address matches the one of the destination interface. + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-s, --stats" +.PP +Enable statistics for successful redirection. This option comes with a per +packet tracing overhead, for recording all successful redirections. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + +.SH "The REDIRECT-MULTI command" +.PP +In this mode, \fIxdp\-bench\fP sets up one-to-many packet redirection between +interfaces supplied on the command line, using the \fIbpf_redirect_map\fP BPF helper +triggered on packet reception on the ingress interface, using a devmap as its +target. The packet is broadcast to all output interfaces specified on the +command line, using devmap's packet broadcast feature. + +.PP +The syntax for the \fIredirect\-multi\fP command is: + +.PP +\fIxdp\-bench redirect\-multi [options] <ifname_in> <ifname_out1> ... <ifname_outN>\fP + +.PP +Where \fI<ifname_in>\fP is the name of the input interface from where packets will +be redirect to one or many output interface(s). + +.PP +The supported options are: + +.SS "-X, --load-egress" +.PP +Load a program in the devmap entry used for redirection, so that it is invoked +after the packet is redirected to the target device, before it is transmitted +out of the output interface. The remote program will update the packet data so +its source MAC address matches the one of the destination interface. + +.SS "-i, --interval <SECONDS>" +.PP +Set the polling interval for collecting all statistics and displaying them to +the output. The unit of interval is in seconds. + +.SS "-s, --stats" +.PP +Enable statistics for successful redirection. This option comes with a per +packet tracing overhead, for recording all successful redirections. + +.SS "-e, --extended" +.PP +Start xdp-bench in "extended" output mode. If not set, xdp-bench will start in +"terse" mode. The output mode can be switched by hitting C-$\ while the program +is running. See also the \fBOutput Format Description\fP section below. + +.SS "-m, --mode" +.PP +Selects the XDP program mode (native or skb). Note that native XDP mode is the +default, and loading the redirect program in skb manner is neither performant, +nor recommended. However, this option is useful if the interface driver lacks +native XDP support, or when simply testing the tool. + +.SS "-v, --verbose" +.PP +Enable verbose logging. Supply twice to enable verbose logging from the +underlying \fIlibxdp\fP and \fIlibbpf\fP libraries. + +.SS "--version" +.PP +Show the application version and exit. + +.SS "-h, --help" +.PP +Display a summary of the available options + + +.SH "Output Format Description" +.PP +By default, redirect success statistics are disabled, use \fI\-\-stats\fP to enable. +The terse output mode is default, extended output mode can be activated using +the \fI\-\-extended\fP command line option. + +.PP +SIGQUIT (Ctrl + \\) can be used to switch the mode dynamically at runtime. + +.PP +Terse mode displays at most the following fields: +.RS +.nf +\fCrx/s Number of packets received per second +redir/s Number of packets successfully redirected per second +err,drop/s Aggregated count of errors per second (including dropped packets when not using the drop command) +xmit/s Number of packets transmitted on the output device per second +\fP +.fi +.RE + +.PP +Extended output mode displays at most the following fields: +.RS +.nf +\fCFIELD DESCRIPTION +receive Displays the number of packets received and errors encountered + + Whenever an error or packet drop occurs, details of per CPU error + and drop statistics will be expanded inline in terse mode. + pkt/s - Packets received per second + drop/s - Packets dropped per second + error/s - Errors encountered per second + redirect - Displays the number of packets successfully redirected + Errors encountered are expanded under redirect_err field + Note that passing -s to enable it has a per packet overhead + redir/s - Packets redirected successfully per second + + +redirect_err Displays the number of packets that failed redirection + + The errno is expanded under this field with per CPU count + The recognized errors are: + EINVAL: Invalid redirection + ENETDOWN: Device being redirected to is down + EMSGSIZE: Packet length too large for device + EOPNOTSUPP: Operation not supported + ENOSPC: No space in ptr_ring of cpumap kthread + + error/s - Packets that failed redirection per second + + +enqueue to cpu N Displays the number of packets enqueued to bulk queue of CPU N + Expands to cpu:FROM->N to display enqueue stats for each CPU enqueuing to CPU N + Received packets can be associated with the CPU redirect program is enqueuing + packets to. + pkt/s - Packets enqueued per second from other CPU to CPU N + drop/s - Packets dropped when trying to enqueue to CPU N + bulk-avg - Average number of packets processed for each event + + +kthread Displays the number of packets processed in CPUMAP kthread for each CPU + Packets consumed from ptr_ring in kthread, and its xdp_stats (after calling + CPUMAP bpf prog) are expanded below this. xdp_stats are expanded as a total and + then per-CPU to associate it to each CPU's pinned CPUMAP kthread. + pkt/s - Packets consumed per second from ptr_ring + drop/s - Packets dropped per second in kthread + sched - Number of times kthread called schedule() + + xdp_stats (also expands to per-CPU counts) + pass/s - XDP_PASS count for CPUMAP program execution + drop/s - XDP_DROP count for CPUMAP program execution + redir/s - XDP_REDIRECT count for CPUMAP program execution + + +xdp_exception Displays xdp_exception tracepoint events + + This can occur due to internal driver errors, unrecognized + XDP actions and due to explicit user trigger by use of XDP_ABORTED + Each action is expanded below this field with its count + hit/s - Number of times the tracepoint was hit per second + + +devmap_xmit Displays devmap_xmit tracepoint events + + This tracepoint is invoked for successful transmissions on output + device but these statistics are not available for generic XDP mode, + hence they will be omitted from the output when using SKB mode + xmit/s - Number of packets that were transmitted per second + drop/s - Number of packets that failed transmissions per second + drv_err/s - Number of internal driver errors per second + bulk-avg - Average number of packets processed for each event +\fP +.fi +.RE + +.SH "BUGS" +.PP +Please report any bugs on Github: \fIhttps://github.com/xdp-project/xdp-tools/issues\fP + +.SH "AUTHOR" +.PP +Earlier xdp-redirect tools were written by Jesper Dangaard Brouer and John +Fastabend. They were then rewritten to support more features by Kumar Kartikeya +Dwivedi, who also ported them to xdp-tools together with Toke Høiland-Jørgensen. +This man page was written by Kumar Kartikeya Dwivedi and Toke Høiland-Jørgensen. |