1 files changed, 157 insertions, 0 deletions
diff --git a/xdp-trafficgen/README.org b/xdp-trafficgen/README.org
new file mode 100644
index 0000000..6d7c20f
--- /dev/null
+++ b/xdp-trafficgen/README.org
@@ -0,0 +1,157 @@
+#+EXPORT_FILE_NAME: xdp-trafficgen
+#+TITLE: xdp-trafficgen
+#+OPTIONS: ^:nil
+#+MAN_CLASS_OPTIONS: :section-id "8\" \"DATE\" \"VERSION\" \"An XDP-based traffic generator"
+# This file serves both as a README on github, and as the source for the man
+# page; the latter through the org-mode man page export support.
+# .
+# To export the man page, simply use the org-mode exporter; (require 'ox-man) if
+# it's not available. There's also a Makefile rule to export it.
+
+* XDP-trafficgen - an XDP-based traffic generator
+
+XDP-trafficgen is a packet generator utilising the XDP kernel subsystem to
+generate packets transmit them through a network interface. Packets are
+dynamically generated and transmitted in the kernel, allowing for high
+performance (millions of packets per second per core).
+
+XDP-trafficgen supports generating UDP traffic with fixed or dynamic destination
+ports, and also has basic support for generating dummy TCP traffic on a single
+flow.
+
+** Running xdp-traffigen
+The syntax for running xdp-bench is:
+
+#+begin_src sh
+Usage: xdp-trafficgen COMMAND [options]
+
+COMMAND can be one of:
+       udp         - run in UDP mode
+       tcp         - run in TCP mode
+#+end_src
+
+Each command, and its options are explained below. Or use =xdp-trafficgen COMMAND
+--help= to see the options for each command.
+
+* The UDP command
+The UDP command generates UDP traffic to a given destination IP and either a
+fixed destination port, or a range of port numbers. Only IPv6 traffic is
+supported, and the generated packets will have their IP hop limit set to 1, so
+they can't be routed.
+
+The syntax for the =udp= command is:
+
+=xdp-trafficgen udp [options] <ifname>=
+
+Where =<ifname>= is the name of the destination interface that packets will be
+transmitted on. Note that the network driver of this network interface must
+support being the target of XDP redirects (it must implement the =ndo_xdp_xmit=
+driver operation).
+
+The supported options are:
+
+** -m, --dst-mac <mac addr>
+Set the destination MAC address of generated packets. The default is to generate
+packets with an all-zero destination MAC.
+
+** -M, --src-mac <mac addr>
+Set the source MAC address of the generated packets. The default is to use the
+MAC address of the interface packets are transmitted on.
+
+** -a, --dst-addr <addr>
+Destination IP address of generated packets. The default is the link-local
+=fe80::2= address.
+
+** -A, --src-addr <addr>
+Source IP address of generated packets. The default is the link-local =fe80::1=
+address.
+
+** -p, --dst-port <port>
+Destination UDP port of generated packets, or the first port in the range if
+running with =--dyn-ports= set. Defaults to 1.
+
+** -P, --src-port <port>
+Source UDP port of generated packets. Defaults to 1.
+
+** -d, --dyn-ports <num ports>
+Enable dynamic port mode where the destination port is varied over a range of
+=<num ports>= starting from the =--dst-port=.
+
+** -n, --num-packets <port>
+Number of packets to send before exiting. If not supplied, =xdp-trafficgen= will
+keep sending packets until interrupted.
+
+** -t, --threads <threads>
+Number of simultaneous threads to transmit from. Each thread will be pinned to a
+separate CPU core if possible. Defaults to 1.
+
+** -I, --interval <s>
+Output transmission statistics with this interval (in seconds).
+
+** -v, --verbose
+Enable verbose logging (-vv: more verbose).
+
+** --version
+Display version information and exit.
+
+** -h, --help
+Display a summary of the available options
+
+
+* The TCP command
+The TCP command generates dummy TCP traffic in a single TCP flow. This relies on
+first installing an ingress XDP program on the interface used to transmit on.
+Then, a regular TCP socket connection is established from userspace, and once
+the handshake is completed, the XDP program will take over and start generating
+traffic on that flow tuple. The ingress XDP program will intercept ACK packets
+from the receiver, and keep track of the receive window.
+
+The traffic generator has no congestion control, and only very basic retransmit
+tracking: in essence, any duplicate ACKs from the receiver will cause the sender
+to reset its send sequence number to the last ACKed value and restart from
+there. The same thing happens if no progress on the window is made within two
+seconds. This means that the traffic generator can generate a large amount of
+dummy traffic, but if there's packet loss a lot of this can be retransmissions.
+
+The syntax for the =tcp= command is:
+
+=xdp-trafficgen tcp [options] -i <ifname> <hostname>=
+
+Where =<ifname>= is the name of the destination interface that packets will be
+transmitted on and =<hostname>= is the peer hostname or IP address to connect to
+(only IPv6 is supported). Note that the network driver of this network interface
+must support being the target of XDP redirects (it must implement the
+=ndo_xdp_xmit= driver operation).
+
+The supported options are:
+
+** -p, --dst-port <port>
+Connect to destination <port>. Default 10000.
+
+** -m, --mode <mode>
+Load ingress XDP program in <mode>; default native (valid values: native,skb,hw)
+
+** -n, --num-packets <port>
+Number of packets to send before exiting. If not supplied, =xdp-trafficgen= will
+keep sending packets until interrupted.
+
+** -I, --interval <s>
+Output transmission statistics with this interval (in seconds).
+
+** -v, --verbose
+Enable verbose logging (-vv: more verbose).
+
+** --version
+Display version information and exit.
+
+** -h, --help
+Display a summary of the available options
+
+
+* BUGS
+
+Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues
+
+* AUTHOR
+
+xdp-trafficgen and this man page were written by Toke Høiland-Jørgensen.