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