From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <tomaszx.kulasek@intel.com>
Received: from mga01.intel.com (mga01.intel.com [192.55.52.88])
by dpdk.org (Postfix) with ESMTP id B41542B9D
for <dev@dpdk.org>; Wed, 20 Jul 2016 17:42:54 +0200 (CEST)
Received: from fmsmga002.fm.intel.com ([10.253.24.26])
by fmsmga101.fm.intel.com with ESMTP; 20 Jul 2016 08:42:53 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.28,394,1464678000"; d="scan'208";a="1025650721"
Received: from irsmsx151.ger.corp.intel.com ([163.33.192.59])
by fmsmga002.fm.intel.com with ESMTP; 20 Jul 2016 08:42:53 -0700
Received: from irsmsx102.ger.corp.intel.com ([169.254.2.123]) by
IRSMSX151.ger.corp.intel.com ([169.254.4.151]) with mapi id 14.03.0248.002;
Wed, 20 Jul 2016 16:42:52 +0100
From: "Kulasek, TomaszX" <tomaszx.kulasek@intel.com>
To: Thomas Monjalon <thomas.monjalon@6wind.com>, "Ananyev, Konstantin"
<konstantin.ananyev@intel.com>
CC: "dev@dpdk.org" <dev@dpdk.org>
Thread-Topic: [dpdk-dev] [PATCH] doc: announce ABI change for rte_eth_dev
structure
Thread-Index: AQHR4pqXDSGwrIIVX0yyRoQiG5wJsqAhcP8w
Date: Wed, 20 Jul 2016 15:42:51 +0000
Message-ID: <3042915272161B4EB253DA4D77EB373A14EEA916@IRSMSX102.ger.corp.intel.com>
References: <1469024691-58750-1-git-send-email-tomaszx.kulasek@intel.com>
<2192482.DY91PqGyRQ@xps13>
<2601191342CEEE43887BDE71AB97725836B7FFB6@irsmsx105.ger.corp.intel.com>
<2792307.Hs7AniM9ZW@xps13>
In-Reply-To: <2792307.Hs7AniM9ZW@xps13>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
x-originating-ip: [163.33.239.181]
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
Subject: Re: [dpdk-dev] [PATCH] 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 <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
<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>,
<mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Wed, 20 Jul 2016 15:42:55 -0000
> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Wednesday, July 20, 2016 17:22
> To: Ananyev, Konstantin <konstantin.ananyev@intel.com>
> Cc: Kulasek, TomaszX <tomaszx.kulasek@intel.com>; dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH] doc: announce ABI change for rte_eth_dev
> structure
>=20
> 2016-07-20 15:13, Ananyev, Konstantin:
> > Hi Thomas,
> >
> > > Hi,
> > >
> > > This patch announces an interesting change in the DPDK design.
> > >
> > > 2016-07-20 16:24, Tomasz Kulasek:
> > > > 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.
> > > >
> > > > In 16.11, we plan to 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.
> > > >
> > > > 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.
> > >
> > > We cannot acknowledge such notice without a prior design discussion.
> > > Please explain why you plan to work on this change and give a draft o=
f
> the new structures (a RFC patch would be ideal).
> >
> > I think it is not really a deprecation note, but announce ABI change fo=
r
> rte_ethdev.h structures.
>=20
> An ABI break requires a deprecation notice. So it is :)
>=20
> > The plan is to implement what was proposed & discussed the following
> thread:
> > http://dpdk.org/ml/archives/dev/2015-September/023603.html
>=20
> Please could you summarize it here?
Hi Thomas,
The implementation of rte_eth_tx_prep() will be similar to the rte_eth_tx_b=
urst(), passing same arguments to the driver, so packets can be checked and=
modified before real burst will be done.
The API for new function will be implemented in the fallowed way:
+/**
+ * Process a burst of output packets on a transmit queue of an Ethernet de=
vice.
+ *
+ * The rte_eth_tx_prep() function is invoked to prepare output packets to =
be
+ * transmitted on the output queue *queue_id* of the Ethernet device desig=
nated
+ * by its *port_id*.
+ * The *nb_pkts* parameter is the number of packets to be prepared which a=
re
+ * supplied in the *tx_pkts* array of *rte_mbuf* structures, each of them
+ * allocated from a pool created with rte_pktmbuf_pool_create().
+ * For each packet to send, the rte_eth_tx_prep() function performs
+ * the following operations:
+ *
+ * - Check if packet meets devices requirements for tx offloads.
+ *
+ * - Check limitations about number of segments.
+ *
+ * - Check additional requirements when debug is enabled.
+ *
+ * - Update and/or reset required checksums when tx offload is set for pac=
ket.
+ *
+ * The rte_eth_tx_prep() function returns the number of packets ready it
+ * actually sent. A return value equal to *nb_pkts* means that all packets
+ * are valid and ready to be sent.
+ *
+ * @param port_id
+ * The port identifier of the Ethernet device.
+ * @param queue_id
+ * The index of the transmit queue through which output packets must be
+ * sent.
+ * The value must be in the range [0, nb_tx_queue - 1] previously suppli=
ed
+ * to rte_eth_dev_configure().
+ * @param tx_pkts
+ * The address of an array of *nb_pkts* pointers to *rte_mbuf* structure=
s
+ * which contain the output packets.
+ * @param nb_pkts
+ * The maximum number of packets to process.
+ * @return
+ * The number of packets correct and ready to be sent. The return value =
can be
+ * less than the value of the *tx_pkts* parameter when some packet doesn=
't
+ * meet devices requirements with rte_errno set appropriately.
+ */
+static inline uint16_t
+rte_eth_tx_prep(uint8_t port_id, uint16_t queue_id, struct rte_mbuf **tx_p=
kts,
+ uint16_t nb_pkts)
+{
+ struct rte_eth_dev *dev =3D &rte_eth_devices[port_id];
+
+ if (!dev->tx_pkt_prep) {
+ rte_errno =3D -ENOTSUP;
+ return 0;
+ }
+
+#ifdef RTE_LIBRTE_ETHDEV_DEBUG
+ if (queue_id >=3D dev->data->nb_tx_queues) {
+ RTE_PMD_DEBUG_TRACE("Invalid TX queue_id=3D%d\n", queue_id);
+ rte_errno =3D -EINVAL;
+ return 0;
+ }
+#endif
+
+ return (*dev->tx_pkt_prep)(dev->data->tx_queues[queue_id], tx_pkts, nb_pk=
ts);
+}
Tomasz