From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 1F49E377A for ; Fri, 4 Aug 2017 11:57:32 +0200 (CEST) Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 04 Aug 2017 02:57:32 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.41,320,1498546800"; d="scan'208";a="135446145" Received: from dpdk15.sh.intel.com ([10.67.111.77]) by fmsmga005.fm.intel.com with ESMTP; 04 Aug 2017 02:57:31 -0700 From: Jiayu Hu To: dev@dpdk.org Cc: john.mcnamara@intel.com, thomas@monjalon.net, Jiayu Hu Date: Fri, 4 Aug 2017 17:59:16 +0800 Message-Id: <1501840756-47351-1-git-send-email-jiayu.hu@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1501834844-25765-1-git-send-email-jiayu.hu@intel.com> References: <1501834844-25765-1-git-send-email-jiayu.hu@intel.com> Subject: [dpdk-dev] [PATCH v3] doc: add prog_guide for the GRO library X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 04 Aug 2017 09:57:33 -0000 Add prog_guide doc to explain the design of the GRO library. Signed-off-by: Jiayu Hu Acked-by: John McNamara --- changes in v3: - change "inputted" to "input" and update the text changes in v2: - update the text and remove changes to source_org.rst MAINTAINERS | 1 + .../prog_guide/generic_receive_offload_lib.rst | 159 +++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + 3 files changed, 161 insertions(+) create mode 100644 doc/guides/prog_guide/generic_receive_offload_lib.rst diff --git a/MAINTAINERS b/MAINTAINERS index 52e048f..8581849 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -638,6 +638,7 @@ F: doc/guides/sample_app_ug/ip_reassembly.rst Generic Receive Offload - EXPERIMENTAL M: Jiayu Hu F: lib/librte_gro/ +F: doc/guides/prog_guide/generic_receive_offload_lib.rst Distributor M: Bruce Richardson diff --git a/doc/guides/prog_guide/generic_receive_offload_lib.rst b/doc/guides/prog_guide/generic_receive_offload_lib.rst new file mode 100644 index 0000000..22e50ec --- /dev/null +++ b/doc/guides/prog_guide/generic_receive_offload_lib.rst @@ -0,0 +1,159 @@ +.. BSD LICENSE + Copyright(c) 2017 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Generic Receive Offload Library +=============================== + +Generic Receive Offload (GRO) is a widely used SW-based offloading +technique to reduce per-packet processing overhead. It gains performance +by reassembling small packets into large ones. To enable more flexibility +to applications, DPDK implements GRO as a standalone library. Applications +explicitly use the GRO library to merge small packets into large ones. + +The GRO library assumes all input packets have correct checksums. In +addition, the GRO library doesn't re-calculate checksums for merged +packets. If input packets are IP fragmented, the GRO library assumes +they are complete packets (i.e. with L4 headers). + +Currently, the GRO library implements TCP/IPv4 packet reassembly. + +Reassembly Modes +---------------- + +The GRO library provides two reassembly modes: lightweight and +heavyweight mode. If applications want to merge packets in a simple way, +they can use the lightweight mode API. If applications want more +fine-grained controls, they can choose the heavyweight mode API. + +Lightweight Mode +~~~~~~~~~~~~~~~~ + +The ``rte_gro_reassemble_burst()`` function is used for reassembly in +lightweight mode. It tries to merge N input packets at a time, where +N should be less than or equal to ``RTE_GRO_MAX_BURST_ITEM_NUM``. + +In each invocation, ``rte_gro_reassemble_burst()`` allocates temporary +reassembly tables for the desired GRO types. Note that the reassembly +table is a table structure used to reassemble packets and different GRO +types (e.g. TCP/IPv4 GRO and TCP/IPv6 GRO) have different reassembly table +structures. The ``rte_gro_reassemble_burst()`` function uses the reassembly +tables to merge the N input packets. + +For applications, performing GRO in lightweight mode is simple. They +just need to invoke ``rte_gro_reassemble_burst()``. Applications can get +GROed packets as soon as ``rte_gro_reassemble_burst()`` returns. + +Heavyweight Mode +~~~~~~~~~~~~~~~~ + +The ``rte_gro_reassemble()`` function is used for reassembly in heavyweight +mode. Compared with the lightweight mode, performing GRO in heavyweight mode +is relatively complicated. + +Before performing GRO, applications need to create a GRO context object +by calling ``rte_gro_ctx_create()``. A GRO context object holds the +reassembly tables of desired GRO types. Note that all update/lookup +operations on the context object are not thread safe. So if different +processes or threads want to access the same context object simultaneously, +some external syncing mechanisms must be used. + +Once the GRO context is created, applications can then use the +``rte_gro_reassemble()`` function to merge packets. In each invocation, +``rte_gro_reassemble()`` tries to merge input packets with the packets +in the reassembly tables. If an input packet is an unsupported GRO type, +or other errors happen (e.g. SYN bit is set), ``rte_gro_reassemble()`` +returns the packet to applications. Otherwise, the input packet is either +merged or inserted into a reassembly table. + +When applications want to get GRO processed packets, they need to use +``rte_gro_timeout_flush()`` to flush them from the tables manually. + +TCP/IPv4 GRO +------------ + +TCP/IPv4 GRO supports merging small TCP/IPv4 packets into large ones, +using a table structure called the TCP/IPv4 reassembly table. + +TCP/IPv4 Reassembly Table +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A TCP/IPv4 reassembly table includes a "key" array and an "item" array. +The key array keeps the criteria to merge packets and the item array +keeps the packet information. + +Each key in the key array points to an item group, which consists of +packets which have the same criteria values but can't be merged. A key +in the key array includes two parts: + +* ``criteria``: the criteria to merge packets. If two packets can be + merged, they must have the same criteria values. + +* ``start_index``: the item array index of the first packet in the item + group. + +Each element in the item array keeps the information of a packet. An item +in the item array mainly includes three parts: + +* ``firstseg``: the mbuf address of the first segment of the packet. + +* ``lastseg``: the mbuf address of the last segment of the packet. + +* ``next_pkt_index``: the item array index of the next packet in the same + item group. TCP/IPv4 GRO uses ``next_pkt_index`` to chain the packets + that have the same criteria value but can't be merged together. + +Procedure to Reassemble a Packet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To reassemble an incoming packet needs three steps: + +#. Check if the packet should be processed. Packets with one of the + following properties aren't processed and are returned immediately: + + * FIN, SYN, RST, URG, PSH, ECE or CWR bit is set. + + * L4 payload length is 0. + +#. Traverse the key array to find a key which has the same criteria + value with the incoming packet. If found, go to the next step. + Otherwise, insert a new key and a new item for the packet. + +#. Locate the first packet in the item group via ``start_index``. Then + traverse all packets in the item group via ``next_pkt_index``. If a + packet is found which can be merged with the incoming one, merge them + together. If one isn't found, insert the packet into this item group. + Note that to merge two packets is to link them together via mbuf's + ``next`` field. + +When packets are flushed from the reassembly table, TCP/IPv4 GRO updates +packet header fields for the merged packets. Note that before reassembling +the packet, TCP/IPv4 GRO doesn't check if the checksums of packets are +correct. Also, TCP/IPv4 GRO doesn't re-calculate checksums for merged +packets. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 13e03db..40f04a1 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -55,6 +55,7 @@ Programmer's Guide packet_distrib_lib reorder_lib ip_fragment_reassembly_lib + generic_receive_offload_lib pdump_lib multi_proc_support kernel_nic_interface -- 2.7.4