doc: announce marking device and driver objects as internal

  rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
Announce that they will be made opaque in the public API and mark
associated API as internal.
This impacts all bus, as their driver registration mechanism will be
made internal.

Note: the PCI bus had a similar deprecation notice that we can remove as
the new one is more generic.

Signed-off-by: David Marchand <david.marchand@redhat.com>
---
 doc/guides/rel_notes/deprecation.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
  

On 7/10/22 09:17, David Marchand wrote:
> rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> Announce that they will be made opaque in the public API and mark
> associated API as internal.
> This impacts all bus, as their driver registration mechanism will be
> made internal.
> 
> Note: the PCI bus had a similar deprecation notice that we can remove as
> the new one is more generic.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>

Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
  

Hi David,

> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Sunday, July 10, 2022 2:18 PM
> To: dev@dpdk.org; techboard@dpdk.org
> Cc: Ray Kinsella <mdr@ashroe.eu>
> Subject: [PATCH] doc: announce marking device and driver objects as
> internal
> 
> rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> Announce that they will be made opaque in the public API and mark
> associated API as internal.
> This impacts all bus, as their driver registration mechanism will be
> made internal.
> 
> Note: the PCI bus had a similar deprecation notice that we can remove as
> the new one is more generic.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
>  doc/guides/rel_notes/deprecation.rst | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst
> b/doc/guides/rel_notes/deprecation.rst
> index a9fd6676be..b9cc267b30 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -38,6 +38,13 @@ Deprecation Notices
>    external users may still register their bus using a new driver header
> (see
>    ``enable_driver_sdk`` meson option).
> 
> +* drivers: As a followup on the work on the ``rte_bus`` object, the
> +  ``rte_driver`` and ``rte_device`` objects (and as a domino effect,
> their
> +  bus-specific counterparts) will be made opaque in DPDK 22.11.
> +  Registering a driver on a bus will be marked as an internal API:
> +  external users may still register their drivers using the bus specific
> +  driver header (see ``enable_driver_sdk`` meson option).
> +

Cc SPDK folks

Thanks for your work! My only concern is using enable_driver_sdk may not be
a good way for SPDK based on the discussion.
http://patchwork.dpdk.org/project/dpdk/cover/20210918022443.12719-1-chenbo.xia@intel.com/

But overall this idea makes sense, so:

Acked-by: Chenbo Xia <chenbo.xia@intel.com>


>  * mempool: Helper macro ``MEMPOOL_HEADER_SIZE()`` is deprecated and will
>    be removed in DPDK 22.11. The replacement macro
>    ``RTE_MEMPOOL_HEADER_SIZE()`` is internal only.
> @@ -49,11 +56,6 @@ Deprecation Notices
>  * mempool: The mempool API macros ``MEMPOOL_PG_*`` are deprecated and
>    will be removed in DPDK 22.11.
> 
> -* pci: To reduce unnecessary ABIs exposed by DPDK bus driver,
> "rte_bus_pci.h"
> -  will be made internal in 21.11 and macros/data structures/functions
> defined
> -  in the header will not be considered as ABI anymore. This change is
> inspired
> -  by the RFC https://patchwork.dpdk.org/project/dpdk/list/?series=17176.
> -
>  * lib: will fix extending some enum/define breaking the ABI. There are
> multiple
>    samples in DPDK that enum/define terminated with a ``.*MAX.*`` value
> which is
>    used by iterators, and arrays holding these values are sized with this
> --
> 2.36.1
  

11/07/2022 04:16, Xia, Chenbo:
> From: David Marchand <david.marchand@redhat.com>
> > rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> > Announce that they will be made opaque in the public API and mark
> > associated API as internal.
> > This impacts all bus, as their driver registration mechanism will be
> > made internal.
> > 
> > Note: the PCI bus had a similar deprecation notice that we can remove as
> > the new one is more generic.
[...]
> > --- a/doc/guides/rel_notes/deprecation.rst
> > +++ b/doc/guides/rel_notes/deprecation.rst
> > +* drivers: As a followup on the work on the ``rte_bus`` object, the
> > +  ``rte_driver`` and ``rte_device`` objects (and as a domino effect,
> > their
> > +  bus-specific counterparts) will be made opaque in DPDK 22.11.
> > +  Registering a driver on a bus will be marked as an internal API:
> > +  external users may still register their drivers using the bus specific
> > +  driver header (see ``enable_driver_sdk`` meson option).
> > +
> 
> Cc SPDK folks
> 
> Thanks for your work! My only concern is using enable_driver_sdk may not be
> a good way for SPDK based on the discussion.
> http://patchwork.dpdk.org/project/dpdk/cover/20210918022443.12719-1-chenbo.xia@intel.com/

Quick summary:
- Symbols exported by DPDK by default are supposed to be for applications.
- Option enable_driver_sdk allow installing headers to build drivers.
- Driver interface is not part of the stable ABI, i.e. no compat guarantee.
- SPDK is building drivers on top of DPDK bus drivers (PCI for now).
- SPDK was asked to check whether anything else is required.

There is no decision about ABI guarantee because we lack feedbacks.
After this cleanup, the option enable_driver_sdk would be required
when working with buses, like SPDK.
Is there a real need to build against distro-provided package?
Is there a way to provide bus drivers SDK without messing with app SDK?


> But overall this idea makes sense, so:
> 
> Acked-by: Chenbo Xia <chenbo.xia@intel.com>

I like the cleanup as well. It will allow more enhancements in future.
I hope and believe we can accomodate SDK needs when it will be clear.

Acked-by: Thomas Monjalon <thomas@monjalon.net>
  

On Sun, Jul 10, 2022 at 11:48 AM David Marchand
<david.marchand@redhat.com> wrote:
>
> rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> Announce that they will be made opaque in the public API and mark
> associated API as internal.
> This impacts all bus, as their driver registration mechanism will be
> made internal.
>
> Note: the PCI bus had a similar deprecation notice that we can remove as
> the new one is more generic.
>
> Signed-off-by: David Marchand <david.marchand@redhat.com>

Acked-by: Jerin Jacob <jerinj@marvell.com>

> ---
>  doc/guides/rel_notes/deprecation.rst | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)
>
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index a9fd6676be..b9cc267b30 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -38,6 +38,13 @@ Deprecation Notices
>    external users may still register their bus using a new driver header (see
>    ``enable_driver_sdk`` meson option).
>
> +* drivers: As a followup on the work on the ``rte_bus`` object, the
> +  ``rte_driver`` and ``rte_device`` objects (and as a domino effect, their
> +  bus-specific counterparts) will be made opaque in DPDK 22.11.
> +  Registering a driver on a bus will be marked as an internal API:
> +  external users may still register their drivers using the bus specific
> +  driver header (see ``enable_driver_sdk`` meson option).
> +
>  * mempool: Helper macro ``MEMPOOL_HEADER_SIZE()`` is deprecated and will
>    be removed in DPDK 22.11. The replacement macro
>    ``RTE_MEMPOOL_HEADER_SIZE()`` is internal only.
> @@ -49,11 +56,6 @@ Deprecation Notices
>  * mempool: The mempool API macros ``MEMPOOL_PG_*`` are deprecated and
>    will be removed in DPDK 22.11.
>
> -* pci: To reduce unnecessary ABIs exposed by DPDK bus driver, "rte_bus_pci.h"
> -  will be made internal in 21.11 and macros/data structures/functions defined
> -  in the header will not be considered as ABI anymore. This change is inspired
> -  by the RFC https://patchwork.dpdk.org/project/dpdk/list/?series=17176.
> -
>  * lib: will fix extending some enum/define breaking the ABI. There are multiple
>    samples in DPDK that enum/define terminated with a ``.*MAX.*`` value which is
>    used by iterators, and arrays holding these values are sized with this
> --
> 2.36.1
>
  

On 7/10/2022 11:47 AM, David Marchand wrote:
> rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> Announce that they will be made opaque in the public API and mark
> associated API as internal.
> This impacts all bus, as their driver registration mechanism will be
> made internal.
>
> Note: the PCI bus had a similar deprecation notice that we can remove as
> the new one is more generic.
>
> Signed-off-by: David Marchand <david.marchand@redhat.com>

Acked-by:  Hemant Agrawal <hemant.agrawal@nxp.com>
  

On 10/07/2022 07:17, David Marchand wrote:
> rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> Announce that they will be made opaque in the public API and mark
> associated API as internal.
> This impacts all bus, as their driver registration mechanism will be
> made internal.
>
> Note: the PCI bus had a similar deprecation notice that we can remove as
> the new one is more generic.
>
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
>   doc/guides/rel_notes/deprecation.rst | 12 +++++++-----
>   1 file changed, 7 insertions(+), 5 deletions(-)
>
Thanks for working on this cleanup, David!

Acked-by: Kevin Laatz <kevin.laatz@intel.com>
  

On 7/12/22 11:24, Kevin Laatz wrote:
> On 10/07/2022 07:17, David Marchand wrote:
>> rte_driver and rte_device are unnecessarily exposed in the public 
>> API/ABI.
>> Announce that they will be made opaque in the public API and mark
>> associated API as internal.
>> This impacts all bus, as their driver registration mechanism will be
>> made internal.
>>
>> Note: the PCI bus had a similar deprecation notice that we can remove as
>> the new one is more generic.
>>
>> Signed-off-by: David Marchand <david.marchand@redhat.com>
>> ---
>>   doc/guides/rel_notes/deprecation.rst | 12 +++++++-----
>>   1 file changed, 7 insertions(+), 5 deletions(-)
>>
> Thanks for working on this cleanup, David!
> 
> Acked-by: Kevin Laatz <kevin.laatz@intel.com>
> 

Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
  

10/07/2022 08:17, David Marchand:
> rte_driver and rte_device are unnecessarily exposed in the public API/ABI.
> Announce that they will be made opaque in the public API and mark
> associated API as internal.
> This impacts all bus, as their driver registration mechanism will be
> made internal.
> 
> Note: the PCI bus had a similar deprecation notice that we can remove as
> the new one is more generic.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>

    Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>
    Acked-by: Chenbo Xia <chenbo.xia@intel.com>
    Acked-by: Thomas Monjalon <thomas@monjalon.net>
    Acked-by: Jerin Jacob <jerinj@marvell.com>
    Acked-by: Hemant Agrawal <hemant.agrawal@nxp.com>
    Acked-by: Kevin Laatz <kevin.laatz@intel.com>
    Acked-by: Andrew Rybchenko <andrew.rybchenko@oktetlabs.ru>

Applied, thanks.