From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 8FF77532D for ; Tue, 11 Jul 2017 05:25:56 +0200 (CEST) Received: from orsmga004.jf.intel.com ([10.7.209.38]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 10 Jul 2017 20:25:54 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.40,344,1496127600"; d="scan'208";a="106830456" Received: from dpdk15.sh.intel.com ([10.67.111.77]) by orsmga004.jf.intel.com with ESMTP; 10 Jul 2017 20:25:53 -0700 From: Jiayu Hu To: dev@dpdk.org Cc: thomas@monjalon.net, Jiayu Hu Date: Tue, 11 Jul 2017 11:27:35 +0800 Message-Id: <1499743655-86736-1-git-send-email-jiayu.hu@intel.com> X-Mailer: git-send-email 2.7.4 Subject: [dpdk-dev] [PATCH] doc: update programmer's 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: Tue, 11 Jul 2017 03:25:57 -0000 Add description to programmer's guide to explain the design of the GRO library. Signed-off-by: Jiayu Hu --- MAINTAINERS | 1 + .../prog_guide/generic_receive_offload_lib.rst | 163 +++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/source_org.rst | 1 + 4 files changed, 166 insertions(+) create mode 100644 doc/guides/prog_guide/generic_receive_offload_lib.rst diff --git a/MAINTAINERS b/MAINTAINERS index 804ac04..14bee21 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -618,6 +618,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..6d61d35 --- /dev/null +++ b/doc/guides/prog_guide/generic_receive_offload_lib.rst @@ -0,0 +1,163 @@ +.. 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 inputted packets are with correct checksums. +Besides, the GRO library doesn't re-calculate checksums for merged +packets. If inputted 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. + +Two Reassembly Modes +-------------------- + +The GRO library provides two reassembly modes. One is called lightweight +mode, the other is called 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 +~~~~~~~~~~~~~~~~~~~~ + +``rte_gro_reassemble_burst()`` is the reassembly API in lightweight mode, +which tries to merge N inputted packets at a time, where N should be +less than ``RTE_GRO_MAX_BURST_ITEM_NUM``. + +In each invocation of ``rte_gro_reassemble_burst()``, +``rte_gro_reassemble_burst()`` allocates temporary reassembly tables for +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. +``rte_gro_reassemble_burst()`` uses the reassembly tables to merge the N +inputted 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 +~~~~~~~~~~~~~~~~~~~~ + +``rte_gro_reassemble()`` is the reassembly API 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 ``rte_gro_ctx_create()`` first. A GRO context object keeps reassembly +tables of desired GRO types. Note that all update/lookup operations on +context object are not thread safe. So if different processes or threads +want to access the same context object simultaneously, some external +syncing mechanism have to be provided. + +Then applications can use ``rte_gro_reassemble()`` to merge packets. In +each invocation of ``rte_gro_reassemble()``, ``rte_gro_reassemble()`` +tries to merge inputted packets with the packets in the reassembly tables. +If an inputted packet is with unsupported GRO type, or other errors happen +(e.g. SYN bit is set), ``rte_gro_reassemble()`` returns the packet to +applications. Otherwise, the inputted packet is either merged or inserted +into one 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 to merge small TCP/IPv4 packets into large ones, +which uses a table structure, called TCP/IPv4 reassembly table, to +reassemble packets. + +TCP/IPv4 Reassembly Table +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A TCP/IPv4 reassembly table includes a key array and a item array, where +the key array keeps the criteria to merge packets and the item array keeps +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 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: + + a) FIN, SYN, RST, URG, PSH, ECE or CWR bit is set. + + b) L4 payload length is 0. + +#. Traverse the key array to find a key which has the same criteria + value with the incoming packet. + If find, 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 find one packet which can merge with the incoming one, merge them + together. If can't find, 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. Besides, TCP/IPv4 GRO doesn'tre-calculate checksums for merged +packets. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 7578395..f05d70c 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -53,6 +53,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 diff --git a/doc/guides/prog_guide/source_org.rst b/doc/guides/prog_guide/source_org.rst index d5d01f3..18c390a 100644 --- a/doc/guides/prog_guide/source_org.rst +++ b/doc/guides/prog_guide/source_org.rst @@ -68,6 +68,7 @@ The lib directory contains:: +-- librte_distributor # Packet distributor +-- librte_eal # Environment abstraction layer +-- librte_ether # Generic interface to poll mode driver + +-- librte_gro # Generic receive offload library +-- librte_hash # Hash library +-- librte_ip_frag # IP fragmentation library +-- librte_kni # Kernel NIC interface -- 2.7.4