doc: announce some raw/ifpga API removal

  rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear
what could be done with it.
On the other hand, EAL provides a standard API to retrieve a bus object
by name.

Announce removal of this driver specific API for v22.11.

Signed-off-by: David Marchand <david.marchand@redhat.com>
---
A RFC series of the intended changes is available at:
https://patches.dpdk.org/project/dpdk/list/?series=23811&state=%2A&archive=both

---
 doc/guides/rel_notes/deprecation.rst | 2 ++
 1 file changed, 2 insertions(+)
  

Hi  David,

Got, thank you so much.


> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Thursday, June 30, 2022 17:41
> To: dev@dpdk.org; Xu, Rosen <rosen.xu@intel.com>; Zhang, Tianfei
> <tianfei.zhang@intel.com>
> Cc: Ray Kinsella <mdr@ashroe.eu>
> Subject: [PATCH] doc: announce some raw/ifpga API removal
> 
> rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear what
> could be done with it.
> On the other hand, EAL provides a standard API to retrieve a bus object by
> name.
> 
> Announce removal of this driver specific API for v22.11.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
> A RFC series of the intended changes is available at:
> https://patches.dpdk.org/project/dpdk/list/?series=23811&state=%2A&arch
> ive=both
> 
> ---
>  doc/guides/rel_notes/deprecation.rst | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst
> b/doc/guides/rel_notes/deprecation.rst
> index 4e5b23c53d..64d649777a 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -119,6 +119,8 @@ Deprecation Notices
>  * metrics: The function ``rte_metrics_init`` will have a non-void return
>    in order to notify errors instead of calling ``rte_exit``.
> 
> +* raw/ifgpa: The ``rte_pmd_ifpga_get_pci_bus`` will be removed in 22.11.
> +
>  * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
>    functionality is provided through the new ``dmadev`` infrastructure.
>    To continue to use hardware previously supported by the ``ioat`` rawdev
> driver,
> --
> 2.36.1
  

Hi David,

> -----Original Message-----
> From: Xu, Rosen <rosen.xu@intel.com>
> Sent: Friday, July 1, 2022 14:16
> To: David Marchand <david.marchand@redhat.com>; dev@dpdk.org; Zhang,
> Tianfei <tianfei.zhang@intel.com>; Huang, Wei <wei.huang@intel.com>
> Cc: Ray Kinsella <mdr@ashroe.eu>
> Subject: RE: [PATCH] doc: announce some raw/ifpga API removal
> 
> Hi  David,
> 
> Got, thank you so much.
> 
> 
> > -----Original Message-----
> > From: David Marchand <david.marchand@redhat.com>
> > Sent: Thursday, June 30, 2022 17:41
> > To: dev@dpdk.org; Xu, Rosen <rosen.xu@intel.com>; Zhang, Tianfei
> > <tianfei.zhang@intel.com>
> > Cc: Ray Kinsella <mdr@ashroe.eu>
> > Subject: [PATCH] doc: announce some raw/ifpga API removal
> >
> > rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear
> > what could be done with it.
> > On the other hand, EAL provides a standard API to retrieve a bus
> > object by name.
> >
Agree, this API is used in an external application, I can use rte_get_bus_by_name() to replace it.
I will submit a patch to remove rte_pmd_ifpga_get_pci_bus() after DPDK22.07 is released.

> > Announce removal of this driver specific API for v22.11.
> >
> > Signed-off-by: David Marchand <david.marchand@redhat.com>
> > ---
> > A RFC series of the intended changes is available at:
> >
> https://patches.dpdk.org/project/dpdk/list/?series=23811&state=%2A&arc
> > h
> > ive=both
> >
> > ---
> >  doc/guides/rel_notes/deprecation.rst | 2 ++
> >  1 file changed, 2 insertions(+)
> >
> > diff --git a/doc/guides/rel_notes/deprecation.rst
> > b/doc/guides/rel_notes/deprecation.rst
> > index 4e5b23c53d..64d649777a 100644
> > --- a/doc/guides/rel_notes/deprecation.rst
> > +++ b/doc/guides/rel_notes/deprecation.rst
> > @@ -119,6 +119,8 @@ Deprecation Notices
> >  * metrics: The function ``rte_metrics_init`` will have a non-void return
> >    in order to notify errors instead of calling ``rte_exit``.
> >
> > +* raw/ifgpa: The ``rte_pmd_ifpga_get_pci_bus`` will be removed in 22.11.
> > +
> >  * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
> >    functionality is provided through the new ``dmadev`` infrastructure.
> >    To continue to use hardware previously supported by the ``ioat``
> > rawdev driver,
> > --
> > 2.36.1
  

On Fri, Jul 1, 2022 at 8:25 AM Huang, Wei <wei.huang@intel.com> wrote:
> > >
> > > rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear
> > > what could be done with it.
> > > On the other hand, EAL provides a standard API to retrieve a bus
> > > object by name.
> > >
> Agree, this API is used in an external application, I can use rte_get_bus_by_name() to replace it.

What is the PCI bus used for, in this application?


> I will submit a patch to remove rte_pmd_ifpga_get_pci_bus() after DPDK22.07 is released.

I sent a patch a few days ago:
https://patches.dpdk.org/project/dpdk/patch/20220628144643.1213026-3-david.marchand@redhat.com/
  

> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Friday, July 1, 2022 15:01
> To: Huang, Wei <wei.huang@intel.com>; Xu, Rosen <rosen.xu@intel.com>;
> Zhang, Tianfei <tianfei.zhang@intel.com>
> Cc: dev@dpdk.org; Ray Kinsella <mdr@ashroe.eu>
> Subject: Re: [PATCH] doc: announce some raw/ifpga API removal
> 
> On Fri, Jul 1, 2022 at 8:25 AM Huang, Wei <wei.huang@intel.com> wrote:
> > > >
> > > > rte_pmd_ifpga_get_pci_bus() documentation is vague and it is
> > > > unclear what could be done with it.
> > > > On the other hand, EAL provides a standard API to retrieve a bus
> > > > object by name.
> > > >
> > Agree, this API is used in an external application, I can use
> rte_get_bus_by_name() to replace it.
> 
> What is the PCI bus used for, in this application?
> 
In this application, target PCI device is Intel FPGA, it supports some special operation like removing it from PCI bus and rescanning it back from PCI bus,
So there are two things need to be done directly on rte_pci_bus:
1. Rescan PCI bus
     pci_bus->bus.scan()
2. Get pci_dev by specified PCI address, and remove it
    TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
	if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
		return pci_dev;
    }
    ....
    pci_drv = pci_dev->driver;
    pci_drv->remove(pci_dev);
> 
> > I will submit a patch to remove rte_pmd_ifpga_get_pci_bus() after DPDK22.07
> is released.
> 
> I sent a patch a few days ago:
> https://patches.dpdk.org/project/dpdk/patch/20220628144643.1213026-3-
> david.marchand@redhat.com/
> 
> 
> --
> David Marchand
  

On Fri, Jul 1, 2022 at 9:16 AM Huang, Wei <wei.huang@intel.com> wrote:
> > What is the PCI bus used for, in this application?
> >
> In this application, target PCI device is Intel FPGA, it supports some special operation like removing it from PCI bus and rescanning it back from PCI bus,
> So there are two things need to be done directly on rte_pci_bus:
> 1. Rescan PCI bus
>      pci_bus->bus.scan()
> 2. Get pci_dev by specified PCI address, and remove it
>     TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
>         if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
>                 return pci_dev;
>     }
>     ....
>     pci_drv = pci_dev->driver;
>     pci_drv->remove(pci_dev);

Can't this application use rte_dev_remove and rte_dev_probe?
If not, we should add the missing parts in the API.
  

> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Friday, July 1, 2022 15:22
> To: Huang, Wei <wei.huang@intel.com>
> Cc: Xu, Rosen <rosen.xu@intel.com>; Zhang, Tianfei <tianfei.zhang@intel.com>;
> dev@dpdk.org; Ray Kinsella <mdr@ashroe.eu>
> Subject: Re: [PATCH] doc: announce some raw/ifpga API removal
> 
> On Fri, Jul 1, 2022 at 9:16 AM Huang, Wei <wei.huang@intel.com> wrote:
> > > What is the PCI bus used for, in this application?
> > >
> > In this application, target PCI device is Intel FPGA, it supports some
> > special operation like removing it from PCI bus and rescanning it back from PCI
> bus, So there are two things need to be done directly on rte_pci_bus:
> > 1. Rescan PCI bus
> >      pci_bus->bus.scan()
> > 2. Get pci_dev by specified PCI address, and remove it
> >     TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
> >         if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
> >                 return pci_dev;
> >     }
> >     ....
> >     pci_drv = pci_dev->driver;
> >     pci_drv->remove(pci_dev);
> 
> Can't this application use rte_dev_remove and rte_dev_probe?
> If not, we should add the missing parts in the API.
> 
Both rte_dev_remove and rte_dev_probe need rte_device pointer. In this application, it only know the device's PCI address, is there an
existing API to get the rte_pci_device pointer by its PCI address ?

For PCI rescan, I know there is an API called rte_bus_scan(), which seems to be able to replace pci_bus->bus.scan(). But is it reasonable to scan all buses
when I want to only scan PCI ?
Why I need to rescan PCI bus, the answer is current PCI scan only add PCI device to rte_pci_bus when it is bound to kernel driver. In our case, a FPGA
may not bind to any driver, this application bind vfio-pci to it and call bus scan to add it to rte_pci_bus.
> 
> --
> David Marchand
  

On Fri, Jul 1, 2022 at 10:02 AM Huang, Wei <wei.huang@intel.com> wrote:
>
>
>
> > -----Original Message-----
> > From: David Marchand <david.marchand@redhat.com>
> > Sent: Friday, July 1, 2022 15:22
> > To: Huang, Wei <wei.huang@intel.com>
> > Cc: Xu, Rosen <rosen.xu@intel.com>; Zhang, Tianfei <tianfei.zhang@intel.com>;
> > dev@dpdk.org; Ray Kinsella <mdr@ashroe.eu>
> > Subject: Re: [PATCH] doc: announce some raw/ifpga API removal
> >
> > On Fri, Jul 1, 2022 at 9:16 AM Huang, Wei <wei.huang@intel.com> wrote:
> > > > What is the PCI bus used for, in this application?
> > > >
> > > In this application, target PCI device is Intel FPGA, it supports some
> > > special operation like removing it from PCI bus and rescanning it back from PCI
> > bus, So there are two things need to be done directly on rte_pci_bus:
> > > 1. Rescan PCI bus
> > >      pci_bus->bus.scan()
> > > 2. Get pci_dev by specified PCI address, and remove it
> > >     TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
> > >         if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
> > >                 return pci_dev;
> > >     }
> > >     ....
> > >     pci_drv = pci_dev->driver;
> > >     pci_drv->remove(pci_dev);
> >
> > Can't this application use rte_dev_remove and rte_dev_probe?
> > If not, we should add the missing parts in the API.
> >
> Both rte_dev_remove and rte_dev_probe need rte_device pointer. In this application, it only know the device's PCI address, is there an
> existing API to get the rte_pci_device pointer by its PCI address ?

rte_dev_probe takes a devargs string as input.
int rte_dev_probe(const char *devargs);

You need the rte_device for removing which can be retrieved from
rte_rawdev_info_get.

>
> For PCI rescan, I know there is an API called rte_bus_scan(), which seems to be able to replace pci_bus->bus.scan(). But is it reasonable to scan all buses
> when I want to only scan PCI ?
> Why I need to rescan PCI bus, the answer is current PCI scan only add PCI device to rte_pci_bus when it is bound to kernel driver. In our case, a FPGA
> may not bind to any driver, this application bind vfio-pci to it and call bus scan to add it to rte_pci_bus.

Scanning is called on the relevant bus when probing, see local_dev_probe.
  

On Fri, Jul 1, 2022 at 10:09 AM David Marchand
<david.marchand@redhat.com> wrote:
> > > > 2. Get pci_dev by specified PCI address, and remove it
> > > >     TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
> > > >         if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
> > > >                 return pci_dev;
> > > >     }
> > > >     ....
> > > >     pci_drv = pci_dev->driver;
> > > >     pci_drv->remove(pci_dev);
> > >
> > > Can't this application use rte_dev_remove and rte_dev_probe?
> > > If not, we should add the missing parts in the API.
> > >
> > Both rte_dev_remove and rte_dev_probe need rte_device pointer. In this application, it only know the device's PCI address, is there an
> > existing API to get the rte_pci_device pointer by its PCI address ?
>
> rte_dev_probe takes a devargs string as input.
> int rte_dev_probe(const char *devargs);
>
> You need the rte_device for removing which can be retrieved from
> rte_rawdev_info_get.

Additionnaly, rte_eal_hotplug_{add,remove} do the same jobs, but with
an easier(?) interface.
  

> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Friday, July 1, 2022 16:15
> To: Huang, Wei <wei.huang@intel.com>
> Cc: Xu, Rosen <rosen.xu@intel.com>; Zhang, Tianfei <tianfei.zhang@intel.com>;
> dev@dpdk.org; Ray Kinsella <mdr@ashroe.eu>
> Subject: Re: [PATCH] doc: announce some raw/ifpga API removal
> 
> On Fri, Jul 1, 2022 at 10:09 AM David Marchand <david.marchand@redhat.com>
> wrote:
> > > > > 2. Get pci_dev by specified PCI address, and remove it
> > > > >     TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
> > > > >         if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
> > > > >                 return pci_dev;
> > > > >     }
> > > > >     ....
> > > > >     pci_drv = pci_dev->driver;
> > > > >     pci_drv->remove(pci_dev);
> > > >
> > > > Can't this application use rte_dev_remove and rte_dev_probe?
> > > > If not, we should add the missing parts in the API.
> > > >
> > > Both rte_dev_remove and rte_dev_probe need rte_device pointer. In
> > > this application, it only know the device's PCI address, is there an existing API
> to get the rte_pci_device pointer by its PCI address ?
> >
> > rte_dev_probe takes a devargs string as input.
> > int rte_dev_probe(const char *devargs);
> >
> > You need the rte_device for removing which can be retrieved from
> > rte_rawdev_info_get.
> 
> Additionnaly, rte_eal_hotplug_{add,remove} do the same jobs, but with an
> easier(?) interface.
> 
> 
I checked rte_eal_hotplug_{add,remove}, they should meet my requirements, thanks a lot.
> --
> David Marchand
  

On Fri, Jul 1, 2022 at 10:32 AM Huang, Wei <wei.huang@intel.com> wrote:
> > > > > > 2. Get pci_dev by specified PCI address, and remove it
> > > > > >     TAILQ_FOREACH(pci_dev, &pci_bus->device_list, next) {
> > > > > >         if (!rte_pci_addr_cmp(&pci_dev->addr, &addr))
> > > > > >                 return pci_dev;
> > > > > >     }
> > > > > >     ....
> > > > > >     pci_drv = pci_dev->driver;
> > > > > >     pci_drv->remove(pci_dev);
> > > > >
> > > > > Can't this application use rte_dev_remove and rte_dev_probe?
> > > > > If not, we should add the missing parts in the API.
> > > > >
> > > > Both rte_dev_remove and rte_dev_probe need rte_device pointer. In
> > > > this application, it only know the device's PCI address, is there an existing API
> > to get the rte_pci_device pointer by its PCI address ?
> > >
> > > rte_dev_probe takes a devargs string as input.
> > > int rte_dev_probe(const char *devargs);
> > >
> > > You need the rte_device for removing which can be retrieved from
> > > rte_rawdev_info_get.
> >
> > Additionnaly, rte_eal_hotplug_{add,remove} do the same jobs, but with an
> > easier(?) interface.
> >
> >
> I checked rte_eal_hotplug_{add,remove}, they should meet my requirements, thanks a lot.

Cool, thanks.
  

On Fri, Jul 1, 2022 at 10:35 AM David Marchand
<david.marchand@redhat.com> wrote:
> > > > > > Can't this application use rte_dev_remove and rte_dev_probe?
> > > > > > If not, we should add the missing parts in the API.
> > > > > >
> > > > > Both rte_dev_remove and rte_dev_probe need rte_device pointer. In
> > > > > this application, it only know the device's PCI address, is there an existing API
> > > to get the rte_pci_device pointer by its PCI address ?
> > > >
> > > > rte_dev_probe takes a devargs string as input.
> > > > int rte_dev_probe(const char *devargs);
> > > >
> > > > You need the rte_device for removing which can be retrieved from
> > > > rte_rawdev_info_get.
> > >
> > > Additionnaly, rte_eal_hotplug_{add,remove} do the same jobs, but with an
> > > easier(?) interface.
> > >
> > >
> > I checked rte_eal_hotplug_{add,remove}, they should meet my requirements, thanks a lot.
>
> Cool, thanks.

So it seems there is nothing blocking for this API change.
Could you ack the deprecation notice?

Thanks.
  

> -----Original Message-----
> From: David Marchand <david.marchand@redhat.com>
> Sent: Thursday, July 7, 2022 17:30
> To: Huang, Wei <wei.huang@intel.com>; Zhang, Tianfei
> <tianfei.zhang@intel.com>; Xu, Rosen <rosen.xu@intel.com>
> Cc: dev@dpdk.org; Ray Kinsella <mdr@ashroe.eu>
> Subject: Re: [PATCH] doc: announce some raw/ifpga API removal
> 
> On Fri, Jul 1, 2022 at 10:35 AM David Marchand <david.marchand@redhat.com>
> wrote:
> > > > > > > Can't this application use rte_dev_remove and rte_dev_probe?
> > > > > > > If not, we should add the missing parts in the API.
> > > > > > >
> > > > > > Both rte_dev_remove and rte_dev_probe need rte_device pointer.
> > > > > > In this application, it only know the device's PCI address, is
> > > > > > there an existing API
> > > > to get the rte_pci_device pointer by its PCI address ?
> > > > >
> > > > > rte_dev_probe takes a devargs string as input.
> > > > > int rte_dev_probe(const char *devargs);
> > > > >
> > > > > You need the rte_device for removing which can be retrieved from
> > > > > rte_rawdev_info_get.
> > > >
> > > > Additionnaly, rte_eal_hotplug_{add,remove} do the same jobs, but
> > > > with an
> > > > easier(?) interface.
> > > >
> > > >
> > > I checked rte_eal_hotplug_{add,remove}, they should meet my requirements,
> thanks a lot.
> >
> > Cool, thanks.
> 
> So it seems there is nothing blocking for this API change.
> Could you ack the deprecation notice?
> 
This API can be removed.
Acked

> Thanks.
> 
> --
> David Marchand
  

30/06/2022 11:41, David Marchand:
> rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear
> what could be done with it.
> On the other hand, EAL provides a standard API to retrieve a bus object
> by name.
> 
> Announce removal of this driver specific API for v22.11.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>

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

Some educational work is required to better explain probing mechanisms
to the users it seems.
  

On 6/30/22 11:41, David Marchand wrote:
> rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear
> what could be done with it.
> On the other hand, EAL provides a standard API to retrieve a bus object
> by name.
> 
> Announce removal of this driver specific API for v22.11.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
> A RFC series of the intended changes is available at:
> https://patches.dpdk.org/project/dpdk/list/?series=23811&state=%2A&archive=both
> 
> ---
>   doc/guides/rel_notes/deprecation.rst | 2 ++
>   1 file changed, 2 insertions(+)
> 
> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> index 4e5b23c53d..64d649777a 100644
> --- a/doc/guides/rel_notes/deprecation.rst
> +++ b/doc/guides/rel_notes/deprecation.rst
> @@ -119,6 +119,8 @@ Deprecation Notices
>   * metrics: The function ``rte_metrics_init`` will have a non-void return
>     in order to notify errors instead of calling ``rte_exit``.
>   
> +* raw/ifgpa: The ``rte_pmd_ifpga_get_pci_bus`` will be removed in 22.11.
> +
>   * raw/ioat: The ``ioat`` rawdev driver has been deprecated, since it's
>     functionality is provided through the new ``dmadev`` infrastructure.
>     To continue to use hardware previously supported by the ``ioat`` rawdev driver,

Acked-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Thanks,
Maxime
  

30/06/2022 11:41, David Marchand:
> rte_pmd_ifpga_get_pci_bus() documentation is vague and it is unclear
> what could be done with it.
> On the other hand, EAL provides a standard API to retrieve a bus object
> by name.
> 
> Announce removal of this driver specific API for v22.11.
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>

Acked-by: Wei Huang <wei.huang@intel.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Applied, thanks.