From patchwork Thu Mar 19 16:36:38 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Olivier Matz X-Patchwork-Id: 4077 Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [IPv6:::1]) by dpdk.org (Postfix) with ESMTP id 6E4389A8B; Thu, 19 Mar 2015 17:36:57 +0100 (CET) Received: from mail-wi0-f177.google.com (mail-wi0-f177.google.com [209.85.212.177]) by dpdk.org (Postfix) with ESMTP id 97E715683 for ; Thu, 19 Mar 2015 17:36:54 +0100 (CET) Received: by wixw10 with SMTP id w10so74471790wix.0 for ; Thu, 19 Mar 2015 09:36:54 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-type:content-transfer-encoding; bh=0bkhU3xXR8Gr2me3yvLX9GkPJqa/oxZAQOJky5unECI=; b=hiftqe2Juag3KuooA+nf9L1h3P09Oonza/ThUjdexrLYVDFL0CbgrtPiCSswmZqVyT EA/EJuCXfs6mC8ossLrtXBs/UwIr94K4KNyDGQLrI0zLVUROJnc67yUdTwXOv+I3Czsp GSthJqA3a5FOd1/GEajsEeg22APBkFf+07eq8C6f198utyhlu0bEGKTyJgMZBVsvtk8A p1xy4hqjQOAjYwCvdJijVz5TBQEPM8XIn8ypwGGl76AhCANAn2FZqtI92ndOAmx4isFn keT2/RTAeYMCDD41t2E4jrXYhGAMgW3I1fh/faaSkcIBv09tZtdwnt3rcMkLGPYvxc3g H6ZA== X-Gm-Message-State: ALoCoQnTq/9kVzMac2XnOjTa+rTsPmjx7xTJoOb7L6n9t+zOR+AY7D5UIuR1Owl5SJZJZ5oSK3RD X-Received: by 10.194.23.39 with SMTP id j7mr156886048wjf.9.1426783014485; Thu, 19 Mar 2015 09:36:54 -0700 (PDT) Received: from glumotte.dev.6wind.com (6wind.net2.nerim.net. [213.41.180.237]) by mx.google.com with ESMTPSA id fo9sm8146449wib.16.2015.03.19.09.36.53 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Thu, 19 Mar 2015 09:36:54 -0700 (PDT) From: Olivier Matz To: dev@dpdk.org Date: Thu, 19 Mar 2015 17:36:38 +0100 Message-Id: <1426782998-11280-3-git-send-email-olivier.matz@6wind.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: <1426782998-11280-1-git-send-email-olivier.matz@6wind.com> References: <1426782998-11280-1-git-send-email-olivier.matz@6wind.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH 2/2] doc: add a description of the offload API X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Signed-off-by: Olivier Matz --- doc/guides/prog_guide/mbuf_lib.rst | 89 +++++++++++++++++++++++++++++++++ doc/guides/prog_guide/poll_mode_drv.rst | 24 +++++---- 2 files changed, 104 insertions(+), 9 deletions(-) diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index 3d59e96..6e3b209 100644 --- a/doc/guides/prog_guide/mbuf_lib.rst +++ b/doc/guides/prog_guide/mbuf_lib.rst @@ -148,6 +148,95 @@ An mbuf also contains the input port (where it comes from), and the number of se For chained buffers, only the first mbuf of the chain stores this meta information. +For instance, this is the case on RX side for the IEEE1588 packet +timestamp mechanism, the VLAN tagging and the IP checksum computation. + +On TX side, it is also possible for an application to delegate some +processing to the hardware if it supports it. For instance, the +PKT_TX_IP_CKSUM flag allows to offload the computation of the IPv4 +checksum. + +The following examples explain how to configure different TX offloads on +a vxlan-encapsulated tcp packet: +``out_eth/out_ip/out_udp/vxlan/in_eth/in_ip/in_tcp/payload`` + +- calculate checksum of out_ip:: + + mb->l2_len = len(out_eth) + mb->l3_len = len(out_ip) + mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM + set out_ip checksum to 0 in the packet + + This is supported on hardwares advertising DEV_TX_OFFLOAD_IPV4_CKSUM. + +- calculate checksum of out_ip and out_udp:: + + mb->l2_len = len(out_eth) + mb->l3_len = len(out_ip) + mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_UDP_CKSUM + set out_ip checksum to 0 in the packet + set out_udp checksum to pseudo header using rte_ipv4_phdr_cksum() + + This is supported on hardwares advertising DEV_TX_OFFLOAD_IPV4_CKSUM + and DEV_TX_OFFLOAD_UDP_CKSUM. + +- calculate checksum of in_ip:: + + mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth) + mb->l3_len = len(in_ip) + mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM + set in_ip checksum to 0 in the packet + + This is similar to case 1), but l2_len is different. It is supported + on hardwares advertising DEV_TX_OFFLOAD_IPV4_CKSUM. + Note that it can only work if outer L4 checksum is 0. + +- calculate checksum of in_ip and in_tcp:: + + mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth) + mb->l3_len = len(in_ip) + mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CSUM | PKT_TX_TCP_CKSUM + set in_ip checksum to 0 in the packet + set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum() + + This is similar to case 2), but l2_len is different. It is supported + on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM and + DEV_TX_OFFLOAD_TCP_CKSUM. + Note that it can only work if outer L4 checksum is 0. + +- segment inner TCP:: + + mb->l2_len = len(out_eth + out_ip + out_udp + vxlan + in_eth) + mb->l3_len = len(in_ip) + mb->l4_len = len(in_tcp) + mb->ol_flags |= PKT_TX_IPV4 | PKT_TX_IP_CKSUM | PKT_TX_TCP_CKSUM | + PKT_TX_TCP_SEG; + set in_ip checksum to 0 in the packet + set in_tcp checksum to pseudo header without including the IP + payload length using rte_ipv4_phdr_cksum() + + This is supported on hardware advertising DEV_TX_OFFLOAD_TCP_TSO. + Note that it can only work if outer L4 checksum is 0. + +- calculate checksum of out_ip, in_ip, in_tcp:: + + mb->outer_l2_len = len(out_eth) + mb->outer_l3_len = len(out_ip) + mb->l2_len = len(out_udp + vxlan + in_eth) + mb->l3_len = len(in_ip) + mb->ol_flags |= PKT_TX_OUTER_IPV4 | PKT_TX_OUTER_IP_CKSUM | \ + PKT_TX_IP_CKSUM | PKT_TX_TCP_CKSUM; + set out_ip checksum to 0 in the packet + set in_ip checksum to 0 in the packet + set in_tcp checksum to pseudo header using rte_ipv4_phdr_cksum() + + This is supported on hardware advertising DEV_TX_OFFLOAD_IPV4_CKSUM, + DEV_TX_OFFLOAD_UDP_CKSUM and DEV_TX_OFFLOAD_OUTER_IPV4_CKSUM. + +The list of flags and their precise meaning is described in the mbuf API +documentation (rte_mbuf.h). Also refer to the testpmd source code +(specifically the csumonly.c file) for details. + Direct and Indirect Buffers --------------------------- diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/poll_mode_drv.rst index e9e1132..7b9e7ca 100755 --- a/doc/guides/prog_guide/poll_mode_drv.rst +++ b/doc/guides/prog_guide/poll_mode_drv.rst @@ -198,15 +198,7 @@ the Intel® 82599 10 Gigabit Ethernet Controller controllers in the testpmd appl Other features such as the L3/L4 5-Tuple packet filtering feature of a port can be configured in the same way. Ethernet* flow control (pause frame) can be configured on the individual port. Refer to the testpmd source code for details. -Also, L4 (UDP/TCP/ SCTP) checksum offload by the NIC can be enabled for an individual packet as long as the packet mbuf is set up correctly. -In terms of UDP tunneling packet, the PKT_TX_UDP_TUNNEL_PKT flag must be set to enable tunneling packet TX checksum offload for both outer layer and inner layer. -Refer to the testpmd source code (specifically the csumonly.c file) for details. - -That being said, the support of some offload features implies the addition of dedicated status bit(s) and value field(s) into the rte_mbuf -data structure, along with their appropriate handling by the receive/transmit functions exported by each PMD. - -For instance, this is the case for the IEEE1588 packet timestamp mechanism, the VLAN tagging and the IP checksum computation, as described in -the Section 7.6 "Meta Information". +Also, L4 (UDP/TCP/ SCTP) checksum offload by the NIC can be enabled for an individual packet as long as the packet mbuf is set up correctly. See `Hardware Offload`_ for details. Configuration of Transmit and Receive Queues ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -257,6 +249,20 @@ One descriptor in the TX ring is used as a sentinel to avoid a hardware race con When configuring for DCB operation, at port initialization, both the number of transmit queues and the number of receive queues must be set to 128. +Hardware Offload +~~~~~~~~~~~~~~~~ + +Depending on driver capabilities advertised by +``rte_eth_dev_info_get()``, the PMD may support hardware offloading +feature like checksumming, TCP segmentation or VLAN insertion. + +The support of these offload features implies the addition of dedicated +status bit(s) and value field(s) into the rte_mbuf data structure, along +with their appropriate handling by the receive/transmit functions +exported by each PMD. The list of flags and their precise meaning is +described in the mbuf API documentation and in the in :ref:`Mbuf Library +`, section "Meta Information". + Poll Mode Driver API --------------------