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 31Generic Receive Offload Library 32=============================== 33 34Generic Receive Offload (GRO) is a widely used SW-based offloading 35technique to reduce per-packet processing overhead. It gains performance 36by reassembling small packets into large ones. To enable more flexibility 37to applications, DPDK implements GRO as a standalone library. Applications 38explicitly use the GRO library to merge small packets into large ones. 39 40The GRO library assumes all input packets have correct checksums. In 41addition, the GRO library doesn't re-calculate checksums for merged 42packets. If input packets are IP fragmented, the GRO library assumes 43they are complete packets (i.e. with L4 headers). 44 45Currently, the GRO library implements TCP/IPv4 packet reassembly. 46 47Reassembly Modes 48---------------- 49 50The GRO library provides two reassembly modes: lightweight and 51heavyweight mode. If applications want to merge packets in a simple way, 52they can use the lightweight mode API. If applications want more 53fine-grained controls, they can choose the heavyweight mode API. 54 55Lightweight Mode 56~~~~~~~~~~~~~~~~ 57 58The ``rte_gro_reassemble_burst()`` function is used for reassembly in 59lightweight mode. It tries to merge N input packets at a time, where 60N should be less than or equal to ``RTE_GRO_MAX_BURST_ITEM_NUM``. 61 62In each invocation, ``rte_gro_reassemble_burst()`` allocates temporary 63reassembly tables for the desired GRO types. Note that the reassembly 64table is a table structure used to reassemble packets and different GRO 65types (e.g. TCP/IPv4 GRO and TCP/IPv6 GRO) have different reassembly table 66structures. The ``rte_gro_reassemble_burst()`` function uses the reassembly 67tables to merge the N input packets. 68 69For applications, performing GRO in lightweight mode is simple. They 70just need to invoke ``rte_gro_reassemble_burst()``. Applications can get 71GROed packets as soon as ``rte_gro_reassemble_burst()`` returns. 72 73Heavyweight Mode 74~~~~~~~~~~~~~~~~ 75 76The ``rte_gro_reassemble()`` function is used for reassembly in heavyweight 77mode. Compared with the lightweight mode, performing GRO in heavyweight mode 78is relatively complicated. 79 80Before performing GRO, applications need to create a GRO context object 81by calling ``rte_gro_ctx_create()``. A GRO context object holds the 82reassembly tables of desired GRO types. Note that all update/lookup 83operations on the context object are not thread safe. So if different 84processes or threads want to access the same context object simultaneously, 85some external syncing mechanisms must be used. 86 87Once 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 90in the reassembly tables. If an input packet is an unsupported GRO type, 91or other errors happen (e.g. SYN bit is set), ``rte_gro_reassemble()`` 92returns the packet to applications. Otherwise, the input packet is either 93merged or inserted into a reassembly table. 94 95When applications want to get GRO processed packets, they need to use 96``rte_gro_timeout_flush()`` to flush them from the tables manually. 97 98TCP/IPv4 GRO 99------------ 100 101TCP/IPv4 GRO supports merging small TCP/IPv4 packets into large ones, 102using a table structure called the TCP/IPv4 reassembly table. 103 104TCP/IPv4 Reassembly Table 105~~~~~~~~~~~~~~~~~~~~~~~~~ 106 107A TCP/IPv4 reassembly table includes a "key" array and an "item" array. 108The key array keeps the criteria to merge packets and the item array 109keeps the packet information. 110 111Each key in the key array points to an item group, which consists of 112packets which have the same criteria values but can't be merged. A key 113in 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 121Each element in the item array keeps the information of a packet. An item 122in 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 132Procedure to Reassemble a Packet 133~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 134 135To 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 155When packets are flushed from the reassembly table, TCP/IPv4 GRO updates 156packet header fields for the merged packets. Note that before reassembling 157the packet, TCP/IPv4 GRO doesn't check if the checksums of packets are 158correct. Also, TCP/IPv4 GRO doesn't re-calculate checksums for merged 159packets. 160