Re: [PATCH] doc: announce ethdev operation struct changes

[Thomas Monjalon <thomas@monjalon.net>]

28/07/2023 17:33, Morten Brørup:
> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > Sent: Friday, 28 July 2023 17.20
> > 
> > 28/07/2023 17:08, Morten Brørup:
> > > > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > > > Sent: Friday, 28 July 2023 16.57
> > > >
> > > > 04/07/2023 10:10, Feifei Wang:
> > > > > To support mbufs recycle mode, announce the coming ABI changes
> > > > > from DPDK 23.11.
> > > > >
> > > > > Signed-off-by: Feifei Wang <feifei.wang2@arm.com>
> > > > > Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
> > > > > ---
> > > > >  doc/guides/rel_notes/deprecation.rst | 4 ++++
> > > > >  1 file changed, 4 insertions(+)
> > > > >
> > > > > diff --git a/doc/guides/rel_notes/deprecation.rst
> > > > b/doc/guides/rel_notes/deprecation.rst
> > > > > index 66431789b0..c7e1ffafb2 100644
> > > > > --- a/doc/guides/rel_notes/deprecation.rst
> > > > > +++ b/doc/guides/rel_notes/deprecation.rst
> > > > > @@ -118,6 +118,10 @@ Deprecation Notices
> > > > >    The legacy actions should be removed
> > > > >    once ``MODIFY_FIELD`` alternative is implemented in drivers.
> > > > >
> > > > > +* ethdev: The Ethernet device data structure ``struct rte_eth_dev`` and
> > > > > +  the fast-path ethdev flat array ``struct rte_eth_fp_ops`` will be
> > updated
> > > > > +  with new fields to support mbufs recycle mode from DPDK 23.11.
> > >
> > > Existing fields will also be moved around [1]:
> > >
> > > @@ -83,15 +90,17 @@  struct rte_eth_fp_ops {
> > >  	 * Rx fast-path functions and related data.
> > >  	 * 64-bit systems: occupies first 64B line
> > >  	 */
> > > +	/** Rx queues data. */
> > > +	struct rte_ethdev_qdata rxq;
> > >  	/** PMD receive function. */
> > >  	eth_rx_burst_t rx_pkt_burst;
> > >  	/** Get the number of used Rx descriptors. */
> > >  	eth_rx_queue_count_t rx_queue_count;
> > >  	/** Check the status of a Rx descriptor. */
> > >  	eth_rx_descriptor_status_t rx_descriptor_status;
> > > -	/** Rx queues data. */
> > > -	struct rte_ethdev_qdata rxq;
> > > -	uintptr_t reserved1[3];
> > > +	/** Refill Rx descriptors with the recycling mbufs. */
> > > +	eth_recycle_rx_descriptors_refill_t recycle_rx_descriptors_refill;
> > > +	uintptr_t reserved1[2];
> > >  	/**@}*/
> > >
> > >  	/**@{*/
> > > @@ -99,15 +108,17 @@  struct rte_eth_fp_ops {
> > >  	 * Tx fast-path functions and related data.
> > >  	 * 64-bit systems: occupies second 64B line
> > >  	 */
> > > +	/** Tx queues data. */
> > > +	struct rte_ethdev_qdata txq;
> > >  	/** PMD transmit function. */
> > >  	eth_tx_burst_t tx_pkt_burst;
> > >  	/** PMD transmit prepare function. */
> > >  	eth_tx_prep_t tx_pkt_prepare;
> > >  	/** Check the status of a Tx descriptor. */
> > >  	eth_tx_descriptor_status_t tx_descriptor_status;
> > > -	/** Tx queues data. */
> > > -	struct rte_ethdev_qdata txq;
> > > -	uintptr_t reserved2[3];
> > > +	/** Copy used mbufs from Tx mbuf ring into Rx. */
> > > +	eth_recycle_tx_mbufs_reuse_t recycle_tx_mbufs_reuse;
> > > +	uintptr_t reserved2[2];
> > >  	/**@}*/
> > 
> > Removing existing fields should be announced explicitly.
> 
> Agreed. And the patch misses this. The "rxq" and "txq" fields are not being removed, they are being moved up in the structures. Your comment about explicit mentioning still applies!
> 
> If there's no time to wait for a new patch version from Feifei, perhaps you improve the description while merging.

If it's only moving fields, we can skip.
The real change is the size of the reserved fields,
so it looks acceptable without notice.