doc: announce API change in mbuf
diff mbox series

Message ID 20200731160349.3198317-1-thomas@monjalon.net
State Accepted
Headers show
Series
  • doc: announce API change in mbuf
Related show

Checks

Context Check Description
ci/travis-robot success Travis build: passed
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Thomas Monjalon July 31, 2020, 4:03 p.m. UTC
In order to prepare for adding more features requiring more space in mbuf,
some static fields must become dynamic.
Some small layout changes may have performance benefits as well.

The deprecation notice for atomic refcount is moved and reworded
to fit below the layout deprecation.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 doc/guides/rel_notes/deprecation.rst | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

Comments

Olivier Matz Aug. 2, 2020, 7:28 p.m. UTC | #1
On Fri, Jul 31, 2020 at 06:03:49PM +0200, Thomas Monjalon wrote:
> In order to prepare for adding more features requiring more space in mbuf,
> some static fields must become dynamic.
> Some small layout changes may have performance benefits as well.
> 
> The deprecation notice for atomic refcount is moved and reworded
> to fit below the layout deprecation.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>

Acked-by: Olivier Matz <olivier.matz@6wind.com>
Andrew Rybchenko Aug. 3, 2020, 12:43 p.m. UTC | #2
On 8/2/20 10:28 PM, Olivier Matz wrote:
> On Fri, Jul 31, 2020 at 06:03:49PM +0200, Thomas Monjalon wrote:
>> In order to prepare for adding more features requiring more space in mbuf,
>> some static fields must become dynamic.
>> Some small layout changes may have performance benefits as well.
>>
>> The deprecation notice for atomic refcount is moved and reworded
>> to fit below the layout deprecation.
>>
>> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> 
> Acked-by: Olivier Matz <olivier.matz@6wind.com>
> 

Acked-by: Andrew Rybchenko <arybchenko@solarflare.com>
David Marchand Aug. 3, 2020, 2:25 p.m. UTC | #3
On Fri, Jul 31, 2020 at 6:04 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> In order to prepare for adding more features requiring more space in mbuf,
> some static fields must become dynamic.
> Some small layout changes may have performance benefits as well.
>
> The deprecation notice for atomic refcount is moved and reworded
> to fit below the layout deprecation.
>
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>

Acked-by: David Marchand <david.marchand@redhat.com>
Kinsella, Ray Aug. 5, 2020, 9:28 a.m. UTC | #4
On 31/07/2020 17:03, Thomas Monjalon wrote:
> In order to prepare for adding more features requiring more space in mbuf,
> some static fields must become dynamic.
> Some small layout changes may have performance benefits as well.
> 
> The deprecation notice for atomic refcount is moved and reworded
> to fit below the layout deprecation.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>  doc/guides/rel_notes/deprecation.rst | 26 ++++++++++++++++++++------
>  1 file changed, 20 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index ea4cfa7a48..015c386c76 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -67,6 +67,26 @@ Deprecation Notices
>    us extending existing enum/define.
>    One solution can be using a fixed size array instead of ``.*MAX.*`` value.
>  
> +* mbuf: Some fields will be converted to dynamic API in DPDK 20.11
> +  in order to reserve more space for the dynamic fields.
> +  The following static fields will be moved as dynamic:
> +
> +  - ``timestamp``
> +  - ``userdata`` / ``udata64``
> +  - ``seqn``
> +
> +  As a consequence, the layout of the ``struct rte_mbuf`` will be re-arranged,
> +  avoiding impact on vectorized implementation of the driver datapaths,
> +  while evaluating performance gains of a better use of the first cache line.
> +
> +  The deprecated unioned fields ``buf_physaddr`` and ``refcnt_atomic``
> +  (as explained below) will be removed in DPDK 20.11.

So what does anyone using these fields do - except panic perhaps.
Can we include a reference to the DPDK Userspace presentation, 
in advance of the documentation supporting the dynamic mbuf.
To prepare people for what is to come ... 

https://www.youtube.com/watch?v=Ttl6MlhmzWY

> +
> +* mbuf: ``refcnt_atomic`` member in structures ``rte_mbuf`` and
> +  ``rte_mbuf_ext_shared_info`` is of type ``rte_atomic16_t``.
> +  Due to adoption of C11 atomic builtins, the field ``refcnt_atomic``
> +  will be replaced with ``refcnt`` of type ``uint16_t`` in DPDK 20.11.
> +
>  * ethdev: Split the ``struct eth_dev_ops`` struct to hide it as much as possible
>    will be done in 20.11.
>    Currently the ``struct eth_dev_ops`` struct is accessible by the application
> @@ -132,12 +152,6 @@ Deprecation Notices
>    in "rte_sched.h". These changes are aligned to improvements suggested in the
>    RFC https://mails.dpdk.org/archives/dev/2018-November/120035.html.
>  
> -* mbuf: ``refcnt_atomic`` member in structures ``rte_mbuf`` and
> -  ``rte_mbuf_ext_shared_info`` is of type ``rte_atomic16_t``. Due to adoption
> -  of C11 atomic builtins it will be of type ``uint16_t``. ``refcnt_atomic``
> -  will be removed in 20.11. It will be replaced with ``refcnt`` of type
> -  ``uint16_t``.
> -
>  * metrics: The function ``rte_metrics_init`` will have a non-void return
>    in order to notify errors instead of calling ``rte_exit``.
>  
>
Thomas Monjalon Aug. 6, 2020, 12:07 a.m. UTC | #5
05/08/2020 11:28, Kinsella, Ray:
> 
> On 31/07/2020 17:03, Thomas Monjalon wrote:
> > In order to prepare for adding more features requiring more space in mbuf,
> > some static fields must become dynamic.
> > Some small layout changes may have performance benefits as well.
> > 
> > The deprecation notice for atomic refcount is moved and reworded
> > to fit below the layout deprecation.
> > 
> > Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> > ---
> 
> So what does anyone using these fields do - except panic perhaps.
> Can we include a reference to the DPDK Userspace presentation, 
> in advance of the documentation supporting the dynamic mbuf.
> To prepare people for what is to come ... 
> 
> https://www.youtube.com/watch?v=Ttl6MlhmzWY

Good idea, link added.

Applied

Patch
diff mbox series

diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
index ea4cfa7a48..015c386c76 100644
--- a/doc/guides/rel_notes/deprecation.rst
+++ b/doc/guides/rel_notes/deprecation.rst
@@ -67,6 +67,26 @@  Deprecation Notices
   us extending existing enum/define.
   One solution can be using a fixed size array instead of ``.*MAX.*`` value.
 
+* mbuf: Some fields will be converted to dynamic API in DPDK 20.11
+  in order to reserve more space for the dynamic fields.
+  The following static fields will be moved as dynamic:
+
+  - ``timestamp``
+  - ``userdata`` / ``udata64``
+  - ``seqn``
+
+  As a consequence, the layout of the ``struct rte_mbuf`` will be re-arranged,
+  avoiding impact on vectorized implementation of the driver datapaths,
+  while evaluating performance gains of a better use of the first cache line.
+
+  The deprecated unioned fields ``buf_physaddr`` and ``refcnt_atomic``
+  (as explained below) will be removed in DPDK 20.11.
+
+* mbuf: ``refcnt_atomic`` member in structures ``rte_mbuf`` and
+  ``rte_mbuf_ext_shared_info`` is of type ``rte_atomic16_t``.
+  Due to adoption of C11 atomic builtins, the field ``refcnt_atomic``
+  will be replaced with ``refcnt`` of type ``uint16_t`` in DPDK 20.11.
+
 * ethdev: Split the ``struct eth_dev_ops`` struct to hide it as much as possible
   will be done in 20.11.
   Currently the ``struct eth_dev_ops`` struct is accessible by the application
@@ -132,12 +152,6 @@  Deprecation Notices
   in "rte_sched.h". These changes are aligned to improvements suggested in the
   RFC https://mails.dpdk.org/archives/dev/2018-November/120035.html.
 
-* mbuf: ``refcnt_atomic`` member in structures ``rte_mbuf`` and
-  ``rte_mbuf_ext_shared_info`` is of type ``rte_atomic16_t``. Due to adoption
-  of C11 atomic builtins it will be of type ``uint16_t``. ``refcnt_atomic``
-  will be removed in 20.11. It will be replaced with ``refcnt`` of type
-  ``uint16_t``.
-
 * metrics: The function ``rte_metrics_init`` will have a non-void return
   in order to notify errors instead of calling ``rte_exit``.