2 Copyright(c) 2017 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
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.
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.
31 Generic Receive Offload Library
32 ===============================
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.
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).
45 Currently, the GRO library implements TCP/IPv4 packet reassembly.
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.
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``.
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.
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.
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.
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.
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.
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.
101 TCP/IPv4 GRO supports merging small TCP/IPv4 packets into large ones,
102 using a table structure called the TCP/IPv4 reassembly table.
104 TCP/IPv4 Reassembly Table
105 ~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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:
115 * ``criteria``: the criteria to merge packets. If two packets can be
116 merged, they must have the same criteria values.
118 * ``start_index``: the item array index of the first packet in the item
121 Each element in the item array keeps the information of a packet. An item
122 in the item array mainly includes three parts:
124 * ``firstseg``: the mbuf address of the first segment of the packet.
126 * ``lastseg``: the mbuf address of the last segment of the packet.
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.
132 Procedure to Reassemble a Packet
133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135 To reassemble an incoming packet needs three steps:
137 #. Check if the packet should be processed. Packets with one of the
138 following properties aren't processed and are returned immediately:
140 * FIN, SYN, RST, URG, PSH, ECE or CWR bit is set.
142 * L4 payload length is 0.
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.
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
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