[PATCH] doc: announce marking device and driver objects as internal

[PATCH] doc: announce marking device and driver objects as internal

[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>
---
 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

Re: [PATCH] doc: announce marking device and driver objects as internal

[Andrew Rybchenko]

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>

RE: [PATCH] doc: announce marking device and driver objects as internal

[Xia, Chenbo]

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

Re: [PATCH] doc: announce marking device and driver objects as internal

[Thomas Monjalon]

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>

Re: [PATCH] doc: announce marking device and driver objects as internal

[Jerin Jacob]

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
>

Re: [PATCH] doc: announce marking device and driver objects as internal

[Hemant Agrawal]

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>

Re: [PATCH] doc: announce marking device and driver objects as internal

[Kevin Laatz]

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>

Re: [PATCH] doc: announce marking device and driver objects as internal

[Andrew Rybchenko]

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>

Re: [PATCH] doc: announce marking device and driver objects as internal

[Thomas Monjalon]

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.