examples/udpfwd/README

   1 Introduction
   2 ============
   3
   4 udpfwd is a sample application to demonstrate and test libtle_udp.
   5 Depending on configuration it can do simple send/recv or both over
   6 opened udp streams. Also it implements ability to do UDP datagram
   7 forwarding between different streams, so it is possible to use that
   8 application as some sort of 'UDP proxy'.
   9 The application can reassemble input fragmented IP packets,
  10 and fragment outgoing IP packets (if destination MTU is less then packet size).
  11 To build and run the application DPDK and TLDK libraries are required.
  12
  13 Logically the application is divided into two parts:
  14
  15 - Back End (BE)
  16 BE is responsible for:
  17         - RX over DPDK ports and feed them into UDP TLDK context(s)
  18         (via tle_udp_rx_bulk).
  19         - retrieve packets ready to be send out from UDP TLDK context(s)
  20         and TX them over destined DPDK port.
  21 Multiple RX/TX queues per port are supported by RSS. Right now the number of
  22 TX is same as the number of RX queue.
  23 Each BE lcore can serve multiple DPDK ports, TLDK UDP contexts.
  24
  25 - Front End (FE)
  26 FE responsibility is to open configured UDP streams and perform
  27 send/recv over them. These streams can belong to different UDP contexts.
  28
  29 Right now each lcore can act as BE and/or FE.
  30
  31 Usage
  32 =====
  33
  34 udpfwd <EAL parameters> -- \
  35         -P | --promisc          /* promiscuous mode enabled. */    \
  36         -R | --rbufs <num>      /* max recv buffers per stream. */ \
  37         -S | --sbufs <num>      /* max send buffers per stream. */ \
  38         -s | --streams <num>    /* streams to open per context. */ \
  39         -b | --becfg <filename> /* backend configuration file. */  \
  40         -f | --fecfg <filename> /* frontend configuration file. */ \
  41         <port0_params> <port1_params> ... <portN_params>
  42
  43 port_params: port=<uint>,lcore=<uint>[-<uint>],\
  44 [rx_offload=<uint>,tx_offload=<uint>,mtu=<uint>,ipv4=<ipv4>,ipv6=<ipv6>]
  45
  46 port_params are used to configure the particular DPDK device (rte_ethdev port),
  47 and specify BE lcore that will do RX/TX from/to the device and manage
  48 BE part of corresponding UDP context. Multiple BE lcore can be specified.
  49
  50 port -          DPDK port id (multiple queues are supported when multiple lcore
  51                 is specified for a port).
  52 lcore -         EAL lcore id to do IO over that port (rx_burst/tx_burst).
  53                 several ports can be managed by the same lcore, and same port can
  54                 belong to more than one lcore.
  55 rx_offload -    RX HW offload capabilities to enable/use on this port.
  56                 (bitmask of DEV_RX_OFFLOAD_* values).
  57 tx_offload -    TX HW offload capabilities to enable/use on this port.
  58                 (bitmask of DEV_TX_OFFLOAD_* values).
  59 mtu -           MTU to be used on that port
  60                 ( = UDP data size + L2/L3/L4 headers sizes, default=1514).
  61 ipv4 -          ipv4 address to assign to that port.
  62 ipv6 -          ipv6 address to assign to that port.
  63
  64 At least one of ipv4/ipv6 values have to be specified for each port.
  65
  66 As an example:
  67 udpfwd --lcores='3,6,8' -w 01:00.0 -- \
  68 --promisc --rbufs 0x1000 --sbufs 0x1000 --streams 0x100 \
  69 --fecfg ./fe.cfg --becfg ./be.cfg \
  70 port=0,lcore=6,lcore=8,rx_offload=0xf,tx_offload=0,\
  71 ipv4=192.168.1.233,ipv6=2001:4860:b002::28
  72
  73 Will create TLDK UDP context on lcore=6 and lcore=8 (BE lcore) to manage
  74 DPDK port 0. Will assign IPv4 address 192.168.1.233 and IPv6 address
  75 2001:4860:b002::28 to that port.
  76 The following supported by DPDK RX HW offloads:
  77         DEV_RX_OFFLOAD_VLAN_STRIP,
  78         DEV_RX_OFFLOAD_IPV4_CKSUM,
  79         DEV_RX_OFFLOAD_UDP_CKSUM,
  80         DEV_RX_OFFLOAD_TCP_CKSUM
  81 will be enabled on that port.
  82 No HW TX offloads will be enabled.
  83
  84 If multiple lcore is specified per DPDK port, the following RSS hash will
  85 be enabled on that port:
  86         ETH_RSS_UDP
  87
  88
  89 Fornt-End (FE) and Back-End (BE) configuration files format:
  90 ------------------------------------------------------------
  91         - each record on a separate line.
  92         - lines started with '#' are treated as comments.
  93         - empty lines (containing whitespace chars only) are ignored.
  94         - kvargs style format for each record.
  95         - each FE record correspond to at least one stream to be opened
  96           (could be multiple streams in case of op="fwd").
  97         - each BE record define a ipv4/ipv6 destination.
  98
  99 FE config record format:
 100 ------------------------
 101
 102 lcore=<uint>,op=<"rx|tx|echo|fwd">,\
 103 laddr=<ip>,lport=<uint16>,raddr=<ip>,rport=<uint16>,\
 104 [txlen=<uint>,fwladdr=<ip>,fwlport=<uint16>,fwraddr=<ip>,fwrport=<uint16>,\
 105 belcore=<uint>]
 106
 107 lcore -         EAL lcore to manage that stream(s) in the FE.
 108 op -            operation to perform on that stream:
 109                 "rx" - do receive only on that stream.
 110                 "tx" - do send only on that stream.
 111                 "echo" - mimic recvfrom(..., &addr);sendto(..., &addr);
 112                 on that stream.
 113                 "fwd" - forward packets between streams.
 114 laddr -         local address for the stream to open.
 115 lport -         local port for the stream to open.
 116 raddr -         remote address for the stream to open.
 117 rport -         remote port for the stream to open.
 118 txlen -         data length to send with each packet ("tx" mode only).
 119 fwladdr -       local address for the forwarding stream(s) to open
 120                 ("fwd mode only).
 121 fwlport -       local port for the forwarding stream(s) to open
 122                 ("fwd mode only).
 123 fwraddr -       remote address for the forwarding stream(s) to open
 124                 ("fwd mode only).
 125 fwrport -       remote port for the forwarding stream(s) to open
 126                 ("fwd mode only).
 127 belcore -               EAL lcore to manage that stream(s) in the BE.
 128
 129 Refer to fe.cfg for an example.
 130
 131 BE config record format:
 132 ------------------------
 133
 134 port=<uint>,addr=<ipv4/ipv6>,masklen=<uint>,mac=<ether>
 135
 136 port -          port number to be used to send packets to the destination.
 137 addr -          destionation network address.
 138 masklen -       desitantion network prefix length.
 139 mac -           destination ethernet address.
 140
 141 Refer to fe.cfg for an example.