From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id CB49D5587 for ; Thu, 21 Jul 2016 17:23:19 +0200 (CEST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga101.jf.intel.com with ESMTP; 21 Jul 2016 08:23:18 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.28,399,1464678000"; d="scan'208";a="1021358727" Received: from gklab-246-023.igk.intel.com (HELO Sent) ([10.217.246.23]) by orsmga002.jf.intel.com with SMTP; 21 Jul 2016 08:23:14 -0700 Received: by Sent (sSMTP sendmail emulation); Thu, 21 Jul 2016 17:24:23 +0200 From: Tomasz Kulasek To: dev@dpdk.org Date: Thu, 21 Jul 2016 17:24:19 +0200 Message-Id: <1469114659-66063-1-git-send-email-tomaszx.kulasek@intel.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1469024691-58750-1-git-send-email-tomaszx.kulasek@intel.com> References: <1469024691-58750-1-git-send-email-tomaszx.kulasek@intel.com> Subject: [dpdk-dev] [PATCH v2] doc: announce ABI change for rte_eth_dev structure 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: , X-List-Received-Date: Thu, 21 Jul 2016 15:23:20 -0000 This is an ABI deprecation notice for DPDK 16.11 in librte_ether about changes in rte_eth_dev and rte_eth_desc_lim structures. As discussed in that thread: http://dpdk.org/ml/archives/dev/2015-September/023603.html Different NIC models depending on HW offload requested might impose different requirements on packets to be TX-ed in terms of: - Max number of fragments per packet allowed - Max number of fragments per TSO segments - The way pseudo-header checksum should be pre-calculated - L3/L4 header fields filling - etc. MOTIVATION: ----------- 1) Some work cannot (and didn't should) be done in rte_eth_tx_burst. However, this work is sometimes required, and now, it's an application issue. 2) Different hardware may have different requirements for TX offloads, other subset can be supported and so on. 3) Some parameters (eg. number of segments in ixgbe driver) may hung device. These parameters may be vary for different devices. For example i40e HW allows 8 fragments per packet, but that is after TSO segmentation. While ixgbe has a 38-fragment pre-TSO limit. 4) Fields in packet may require different initialization (like eg. will require pseudo-header checksum precalculation, sometimes in a different way depending on packet type, and so on). Now application needs to care about it. 5) Using additional API (rte_eth_tx_prep) before rte_eth_tx_burst let to prepare packet burst in acceptable form for specific device. 6) Some additional checks may be done in debug mode keeping tx_burst implementation clean. PROPOSAL: --------- To help user to deal with all these varieties we propose to: 1. Introduce rte_eth_tx_prep() function to do necessary preparations of packet burst to be safely transmitted on device for desired HW offloads (set/reset checksum field according to the hardware requirements) and check HW constraints (number of segments per packet, etc). While the limitations and requirements may differ for devices, it requires to extend rte_eth_dev structure with new function pointer "tx_pkt_prep" which can be implemented in the driver to prepare and verify packets, in devices specific way, before burst, what should to prevent application to send malformed packets. 2. Also new fields will be introduced in rte_eth_desc_lim: nb_seg_max and nb_mtu_seg_max, providing an information about max segments in TSO and non-TSO packets acceptable by device. This information is useful for application to not create/limit malicious packet. APPLICATION (CASE OF USE): -------------------------- 1) Application should to initialize burst of packets to send, set required tx offload flags and required fields, like l2_len, l3_len, l4_len, and tso_segsz 2) Application passes burst to the rte_eth_tx_prep to check conditions required to send packets through the NIC. 3) The result of rte_eth_tx_prep can be used to send valid packets and/or restore invalid if function fails. eg. for (i = 0; i < nb_pkts; i++) { /* initialize or process packet */ bufs[i]->tso_segsz = 800; bufs[i]->ol_flags = PKT_TX_TCP_SEG | PKT_TX_IPV4 | PKT_TX_IP_CKSUM; bufs[i]->l2_len = sizeof(struct ether_hdr); bufs[i]->l3_len = sizeof(struct ipv4_hdr); bufs[i]->l4_len = sizeof(struct tcp_hdr); } /* Prepare burst of TX packets */ nb_prep = rte_eth_tx_prep(port, 0, bufs, nb_pkts); if (nb_prep < nb_pkts) { printf("tx_prep failed\n"); /* drop or restore invalid packets */ } /* Send burst of TX packets */ nb_tx = rte_eth_tx_burst(port, 0, bufs, nb_prep); /* Free any unsent packets. */ Signed-off-by: Tomasz Kulasek --- doc/guides/rel_notes/deprecation.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index f502f86..485aacb 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -41,3 +41,10 @@ Deprecation Notices * The mempool functions for single/multi producer/consumer are deprecated and will be removed in 16.11. It is replaced by rte_mempool_generic_get/put functions. + +* In 16.11 ABI changes are plained: the ``rte_eth_dev`` structure will be + extended with new function pointer ``tx_pkt_prep`` allowing verification + and processing of packet burst to meet HW specific requirements before + transmit. Also new fields will be added to the ``rte_eth_desc_lim`` structure: + ``nb_seg_max`` and ``nb_mtu_seg_max`` provideing information about number of + segments limit to be transmitted by device for TSO/non-TSO packets. -- 1.7.9.5