doc: announce changes to eventdev public data structures

  From: "McDaniel, Timothy" <timothy.mcdaniel@intel.com>

Signed-off-by: McDaniel, Timothy <timothy.mcdaniel@intel.com>
---
 doc/guides/rel_notes/deprecation.rst |   28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
  

>-----Original Message-----
>From: McDaniel, Timothy <timothy.mcdaniel@intel.com>
>Sent: Thursday, July 2, 2020 5:14 PM
>To: dev@dpdk.org
>Cc: jerinj@marvell.com; Eads, Gage <gage.eads@intel.com>; Van Haaren, Harry
><harry.van.haaren@intel.com>; mdr@ashroe.eu; nhorman@tuxdriver.com; Rao,
>Nikhil <nikhil.rao@intel.com>; Carrillo, Erik G <Erik.G.Carrillo@intel.com>; Gujjar,
>Abhinandan S <abhinandan.gujjar@intel.com>; pbhagavatula@marvell.com;
>hemant.agrawal@nxp.com; mattias.ronnblom@ericsson.com; Mccarthy, Peter
><Peter.Mccarthy@intel.com>; McDaniel, Timothy
><timothy.mcdaniel@intel.com>
>Subject: [PATCH] doc: announce changes to eventdev public data structures
>
>From: "McDaniel, Timothy" <timothy.mcdaniel@intel.com>
>
>Signed-off-by: McDaniel, Timothy <timothy.mcdaniel@intel.com>
>---
> doc/guides/rel_notes/deprecation.rst |   28 ++++++++++++++++++++++++++++
> 1 file changed, 28 insertions(+)
>
>diff --git a/doc/guides/rel_notes/deprecation.rst
>b/doc/guides/rel_notes/deprecation.rst
>index d1034f6..6af9b40 100644
>--- a/doc/guides/rel_notes/deprecation.rst
>+++ b/doc/guides/rel_notes/deprecation.rst
>@@ -130,3 +130,31 @@ Deprecation Notices
>   Python 2 support will be completely removed in 20.11.
>   In 20.08, explicit deprecation warnings will be displayed when running
>   scripts with Python 2.
>+
>+* eventdev: Three public data structures will be updated in 20.11;
>+  ``rte_event_dev_info``, ``rte_event_dev_config``, and
>+  ``rte_event_port_conf``.
>+  Two new members will be added to the ``rte_event_dev_info`` struct.
>+  The first, max_event_port_links, will be a uint8_t, and represents the
>+  maximum number of queues that can be linked to a single event port by
>+  this device. The second, max_single_link_event_port_queue_pairs, will be a
>+  uint8_t, and represents the maximum number of event ports and queues that
>+  are optimized for (and only capable of) single-link configurations
>+  supported by this device. These ports and queues are not accounted for in
>+  max_event_ports or max_event_queues.
>+  One new member will be added to the ``rte_event_dev_config`` struct. The
>+  nb_single_link_event_port_queues member will be a uint8_t, and will
>+  represent the number of event ports and queues that will be singly-linked
>+  to each other. These are a subset of the overall event ports and queues.
>+  This value cannot exceed nb_event_ports or nb_event_queues. If the
>+  device has ports and queues that are optimized for single-link usage, this
>+  field is a hint for how many to allocate; otherwise, regular event ports and
>+  queues can be used.
>+  Finally, the ``rte_event_port_conf`` struct will be
>+  modified as follows. The uint8_t implicit_release_disabled field
>+  will be replaced by a uint32_t event_port_cfg field. The new field will
>+  initially have two bits assigned. RTE_EVENT_PORT_CFG_DISABLE_IMPL_REL
>+  will have the same meaning as implicit_release_disabled. The second bit,
>+  RTE_EVENT_PORT_CFG_SINGLE_LINK will be set if the event port links only
>+  to a single event queue.
>+
>--
>1.7.10

Hello Jerin and DPDK community.  Please review and approve the eventdev interface changes announced in this notice.

Thanks,
Tim
  

On Thu, Jul 30, 2020 at 10:03 PM McDaniel, Timothy
<timothy.mcdaniel@intel.com> wrote:
>
>
> >-----Original Message-----
> >From: McDaniel, Timothy <timothy.mcdaniel@intel.com>
> >Sent: Thursday, July 2, 2020 5:14 PM
> >To: dev@dpdk.org
> >Cc: jerinj@marvell.com; Eads, Gage <gage.eads@intel.com>; Van Haaren, Harry
> ><harry.van.haaren@intel.com>; mdr@ashroe.eu; nhorman@tuxdriver.com; Rao,
> >Nikhil <nikhil.rao@intel.com>; Carrillo, Erik G <Erik.G.Carrillo@intel.com>; Gujjar,
> >Abhinandan S <abhinandan.gujjar@intel.com>; pbhagavatula@marvell.com;
> >hemant.agrawal@nxp.com; mattias.ronnblom@ericsson.com; Mccarthy, Peter
> ><Peter.Mccarthy@intel.com>; McDaniel, Timothy
> ><timothy.mcdaniel@intel.com>
> >Subject: [PATCH] doc: announce changes to eventdev public data structures
> >
> >From: "McDaniel, Timothy" <timothy.mcdaniel@intel.com>
> >
> >Signed-off-by: McDaniel, Timothy <timothy.mcdaniel@intel.com>
> >---
> > doc/guides/rel_notes/deprecation.rst |   28 ++++++++++++++++++++++++++++
> > 1 file changed, 28 insertions(+)
> >
> >diff --git a/doc/guides/rel_notes/deprecation.rst
> >b/doc/guides/rel_notes/deprecation.rst
> >index d1034f6..6af9b40 100644
> >--- a/doc/guides/rel_notes/deprecation.rst
> >+++ b/doc/guides/rel_notes/deprecation.rst
> >@@ -130,3 +130,31 @@ Deprecation Notices
> >   Python 2 support will be completely removed in 20.11.
> >   In 20.08, explicit deprecation warnings will be displayed when running
> >   scripts with Python 2.
> >+
> >+* eventdev: Three public data structures will be updated in 20.11;
> >+  ``rte_event_dev_info``, ``rte_event_dev_config``, and
> >+  ``rte_event_port_conf``.
> >+  Two new members will be added to the ``rte_event_dev_info`` struct.
> >+  The first, max_event_port_links, will be a uint8_t, and represents the
> >+  maximum number of queues that can be linked to a single event port by
> >+  this device. The second, max_single_link_event_port_queue_pairs, will be a
> >+  uint8_t, and represents the maximum number of event ports and queues that
> >+  are optimized for (and only capable of) single-link configurations
> >+  supported by this device. These ports and queues are not accounted for in
> >+  max_event_ports or max_event_queues.
> >+  One new member will be added to the ``rte_event_dev_config`` struct. The
> >+  nb_single_link_event_port_queues member will be a uint8_t, and will
> >+  represent the number of event ports and queues that will be singly-linked
> >+  to each other. These are a subset of the overall event ports and queues.
> >+  This value cannot exceed nb_event_ports or nb_event_queues. If the
> >+  device has ports and queues that are optimized for single-link usage, this
> >+  field is a hint for how many to allocate; otherwise, regular event ports and
> >+  queues can be used.
> >+  Finally, the ``rte_event_port_conf`` struct will be
> >+  modified as follows. The uint8_t implicit_release_disabled field
> >+  will be replaced by a uint32_t event_port_cfg field. The new field will
> >+  initially have two bits assigned. RTE_EVENT_PORT_CFG_DISABLE_IMPL_REL
> >+  will have the same meaning as implicit_release_disabled. The second bit,
> >+  RTE_EVENT_PORT_CFG_SINGLE_LINK will be set if the event port links only
> >+  to a single event queue.
> >+
> >--
> >1.7.10
>
> Hello Jerin and DPDK community.  Please review and approve the eventdev interface changes announced in this notice.

Changes look good to me in general. Could you reword the description
such way or similar like below to accommodate
1) DLB PMD requirements
2) Future extensions[1]

I think, We don't need exact mention the data structure member additions,
(This is to get the flexibility on additions/deletion on member fields
after the patch rework)

something like:

eventdev: ABI change to support DLB  PMD and future extensions

The following structures and will be modified to support to DLB PMD and future
extension in the eventdev library.

And then please enumerate the structures[2] of your patch which needs change,
[2]``rte_event_dev_info``, ``rte_event_dev_config``, and
``rte_event_port_conf``
and structures in [1]. Please mention the patches [1] and your spec change patch
as a reference in the description.


[1]
http://patches.dpdk.org/patch/72786/
http://patches.dpdk.org/patch/72787/
>
> Thanks,
> Tim
  

On 02/07/2020 23:13, McDaniel, Timothy wrote:
> From: "McDaniel, Timothy" <timothy.mcdaniel@intel.com>
> 
> Signed-off-by: McDaniel, Timothy <timothy.mcdaniel@intel.com>
> ---
>  doc/guides/rel_notes/deprecation.rst |   28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index d1034f6..6af9b40 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -130,3 +130,31 @@ Deprecation Notices
>    Python 2 support will be completely removed in 20.11.
>    In 20.08, explicit deprecation warnings will be displayed when running
>    scripts with Python 2.
> +
> +* eventdev: Three public data structures will be updated in 20.11;
> +  ``rte_event_dev_info``, ``rte_event_dev_config``, and
> +  ``rte_event_port_conf``.

At a minimum a sub-bullet here for each of the public data structures, 
would a gift to readability. 

> +  Two new members will be added to the ``rte_event_dev_info`` struct.
> +  The first, max_event_port_links, will be a uint8_t, and represents the
> +  maximum number of queues that can be linked to a single event port by
> +  this device. The second, max_single_link_event_port_queue_pairs, will be a
> +  uint8_t, and represents the maximum number of event ports and queues that
> +  are optimized for (and only capable of) single-link configurations
> +  supported by this device. These ports and queues are not accounted for in
> +  max_event_ports or max_event_queues.
> +  One new member will be added to the ``rte_event_dev_config`` struct. The
> +  nb_single_link_event_port_queues member will be a uint8_t, and will
> +  represent the number of event ports and queues that will be singly-linked
> +  to each other. These are a subset of the overall event ports and queues.
> +  This value cannot exceed nb_event_ports or nb_event_queues. If the
> +  device has ports and queues that are optimized for single-link usage, this
> +  field is a hint for how many to allocate; otherwise, regular event ports and
> +  queues can be used.
> +  Finally, the ``rte_event_port_conf`` struct will be
> +  modified as follows. The uint8_t implicit_release_disabled field
> +  will be replaced by a uint32_t event_port_cfg field. The new field will
> +  initially have two bits assigned. RTE_EVENT_PORT_CFG_DISABLE_IMPL_REL
> +  will have the same meaning as implicit_release_disabled. The second bit,
> +  RTE_EVENT_PORT_CFG_SINGLE_LINK will be set if the event port links only
> +  to a single event queue.
> +
>
  

05/08/2020 11:36, Kinsella, Ray:
> 
> On 02/07/2020 23:13, McDaniel, Timothy wrote:
> > From: "McDaniel, Timothy" <timothy.mcdaniel@intel.com>
> > 
> > Signed-off-by: McDaniel, Timothy <timothy.mcdaniel@intel.com>
> > ---
> >  doc/guides/rel_notes/deprecation.rst |   28 ++++++++++++++++++++++++++++
> >  1 file changed, 28 insertions(+)
> > 
> > diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> > index d1034f6..6af9b40 100644
> > --- a/doc/guides/rel_notes/deprecation.rst
> > +++ b/doc/guides/rel_notes/deprecation.rst
> > @@ -130,3 +130,31 @@ Deprecation Notices
> >    Python 2 support will be completely removed in 20.11.
> >    In 20.08, explicit deprecation warnings will be displayed when running
> >    scripts with Python 2.
> > +
> > +* eventdev: Three public data structures will be updated in 20.11;
> > +  ``rte_event_dev_info``, ``rte_event_dev_config``, and
> > +  ``rte_event_port_conf``.
> 
> At a minimum a sub-bullet here for each of the public data structures, 
> would a gift to readability.

I've converted the list into bullets while applying.