doc/guides/prog_guide/generic_receive_offload_lib.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 Generic Receive Offload Library
  32 ===============================
  33
  34 Generic Receive Offload (GRO) is a widely used SW-based offloading
  35 technique to reduce per-packet processing overhead. It gains performance
  36 by reassembling small packets into large ones. To enable more flexibility
  37 to applications, DPDK implements GRO as a standalone library. Applications
  38 explicitly use the GRO library to merge small packets into large ones.
  39
  40 The GRO library assumes all input packets have correct checksums. In
  41 addition, the GRO library doesn't re-calculate checksums for merged
  42 packets. If input packets are IP fragmented, the GRO library assumes
  43 they are complete packets (i.e. with L4 headers).
  44
  45 Currently, the GRO library implements TCP/IPv4 packet reassembly.
  46
  47 Reassembly Modes
  48 ----------------
  49
  50 The GRO library provides two reassembly modes: lightweight and
  51 heavyweight mode. If applications want to merge packets in a simple way,
  52 they can use the lightweight mode API. If applications want more
  53 fine-grained controls, they can choose the heavyweight mode API.
  54
  55 Lightweight Mode
  56 ~~~~~~~~~~~~~~~~
  57
  58 The ``rte_gro_reassemble_burst()`` function is used for reassembly in
  59 lightweight mode. It tries to merge N input packets at a time, where
  60 N should be less than or equal to ``RTE_GRO_MAX_BURST_ITEM_NUM``.
  61
  62 In each invocation, ``rte_gro_reassemble_burst()`` allocates temporary
  63 reassembly tables for the desired GRO types. Note that the reassembly
  64 table is a table structure used to reassemble packets and different GRO
  65 types (e.g. TCP/IPv4 GRO and TCP/IPv6 GRO) have different reassembly table
  66 structures. The ``rte_gro_reassemble_burst()`` function uses the reassembly
  67 tables to merge the N input packets.
  68
  69 For applications, performing GRO in lightweight mode is simple. They
  70 just need to invoke ``rte_gro_reassemble_burst()``. Applications can get
  71 GROed packets as soon as ``rte_gro_reassemble_burst()`` returns.
  72
  73 Heavyweight Mode
  74 ~~~~~~~~~~~~~~~~
  75
  76 The ``rte_gro_reassemble()`` function is used for reassembly in heavyweight
  77 mode. Compared with the lightweight mode, performing GRO in heavyweight mode
  78 is relatively complicated.
  79
  80 Before performing GRO, applications need to create a GRO context object
  81 by calling ``rte_gro_ctx_create()``. A GRO context object holds the
  82 reassembly tables of desired GRO types. Note that all update/lookup
  83 operations on the context object are not thread safe. So if different
  84 processes or threads want to access the same context object simultaneously,
  85 some external syncing mechanisms must be used.
  86
  87 Once the GRO context is created, applications can then use the
  88 ``rte_gro_reassemble()`` function to merge packets. In each invocation,
  89 ``rte_gro_reassemble()`` tries to merge input packets with the packets
  90 in the reassembly tables. If an input packet is an unsupported GRO type,
  91 or other errors happen (e.g. SYN bit is set), ``rte_gro_reassemble()``
  92 returns the packet to applications. Otherwise, the input packet is either
  93 merged or inserted into a reassembly table.
  94
  95 When applications want to get GRO processed packets, they need to use
  96 ``rte_gro_timeout_flush()`` to flush them from the tables manually.
  97
  98 TCP/IPv4 GRO
  99 ------------
 100
 101 TCP/IPv4 GRO supports merging small TCP/IPv4 packets into large ones,
 102 using a table structure called the TCP/IPv4 reassembly table.
 103
 104 TCP/IPv4 Reassembly Table
 105 ~~~~~~~~~~~~~~~~~~~~~~~~~
 106
 107 A TCP/IPv4 reassembly table includes a "key" array and an "item" array.
 108 The key array keeps the criteria to merge packets and the item array
 109 keeps the packet information.
 110
 111 Each key in the key array points to an item group, which consists of
 112 packets which have the same criteria values but can't be merged. A key
 113 in the key array includes two parts:
 114
 115 * ``criteria``: the criteria to merge packets. If two packets can be
 116   merged, they must have the same criteria values.
 117
 118 * ``start_index``: the item array index of the first packet in the item
 119   group.
 120
 121 Each element in the item array keeps the information of a packet. An item
 122 in the item array mainly includes three parts:
 123
 124 * ``firstseg``: the mbuf address of the first segment of the packet.
 125
 126 * ``lastseg``: the mbuf address of the last segment of the packet.
 127
 128 * ``next_pkt_index``: the item array index of the next packet in the same
 129   item group. TCP/IPv4 GRO uses ``next_pkt_index`` to chain the packets
 130   that have the same criteria value but can't be merged together.
 131
 132 Procedure to Reassemble a Packet
 133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 134
 135 To reassemble an incoming packet needs three steps:
 136
 137 #. Check if the packet should be processed. Packets with one of the
 138    following properties aren't processed and are returned immediately:
 139
 140    * FIN, SYN, RST, URG, PSH, ECE or CWR bit is set.
 141
 142    * L4 payload length is 0.
 143
 144 #.  Traverse the key array to find a key which has the same criteria
 145     value with the incoming packet. If found, go to the next step.
 146     Otherwise, insert a new key and a new item for the packet.
 147
 148 #. Locate the first packet in the item group via ``start_index``. Then
 149    traverse all packets in the item group via ``next_pkt_index``. If a
 150    packet is found which can be merged with the incoming one, merge them
 151    together. If one isn't found, insert the packet into this item group.
 152    Note that to merge two packets is to link them together via mbuf's
 153    ``next`` field.
 154
 155 When packets are flushed from the reassembly table, TCP/IPv4 GRO updates
 156 packet header fields for the merged packets. Note that before reassembling
 157 the packet, TCP/IPv4 GRO doesn't check if the checksums of packets are
 158 correct. Also, TCP/IPv4 GRO doesn't re-calculate checksums for merged
 159 packets.