pcim_ionumap_region() has recently been made a public function and does
not have the disadvantage of having to deal with the legacy iomap table,
as pcim_iounmap_regions() does.

Deprecate pcim_iounmap_regions().

Signed-off-by: Philipp Stanner <pstanner@redhat.com>
---
 drivers/pci/devres.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/pci/devres.c b/drivers/pci/devres.c
index 7b12e2a3469c..a486bce18e0d 100644
--- a/drivers/pci/devres.c
+++ b/drivers/pci/devres.c
@@ -1016,11 +1016,14 @@ int pcim_iomap_regions_request_all(struct pci_dev *pdev, int mask,
 EXPORT_SYMBOL(pcim_iomap_regions_request_all);
 
 /**
- * pcim_iounmap_regions - Unmap and release PCI BARs
+ * pcim_iounmap_regions - Unmap and release PCI BARs (DEPRECATED)
  * @pdev: PCI device to map IO resources for
  * @mask: Mask of BARs to unmap and release
  *
  * Unmap and release regions specified by @mask.
+ *
+ * This function is DEPRECATED. Do not use it in new code.
+ * Use pcim_iounmap_region() instead.
  */
 void pcim_iounmap_regions(struct pci_dev *pdev, int mask)
 {
-- 
2.47.0

On Wed, Oct 16, 2024 at 11:49:05AM +0200, Philipp Stanner wrote:
> pcim_ionumap_region() has recently been made a public function and does
> not have the disadvantage of having to deal with the legacy iomap table,
> as pcim_iounmap_regions() does.
> 
> Deprecate pcim_iounmap_regions().

...

> + * This function is DEPRECATED. Do not use it in new code.

Interestingly that the syntax of the DEPRECATED is not documented (yet?),
however the sphinx parser hints us about **DEPRECATED** format — see
Documentation/sphinx/parse-headers.pl:251. In any case the above seems
like second used (in a form of the full sentence) and will be updated
in accordance with the above mentioned script.

-- 
With Best Regards,
Andy Shevchenko

On Wed, 2024-10-16 at 13:38 +0300, Andy Shevchenko wrote:
> On Wed, Oct 16, 2024 at 11:49:05AM +0200, Philipp Stanner wrote:
> > pcim_ionumap_region() has recently been made a public function and
> > does
> > not have the disadvantage of having to deal with the legacy iomap
> > table,
> > as pcim_iounmap_regions() does.
> > 
> > Deprecate pcim_iounmap_regions().
> 
> ...
> 
> > + * This function is DEPRECATED. Do not use it in new code.
> 
> Interestingly that the syntax of the DEPRECATED is not documented
> (yet?),
> however the sphinx parser hints us about **DEPRECATED** format — see
> Documentation/sphinx/parse-headers.pl:251. In any case the above
> seems
> like second used (in a form of the full sentence) and will be updated
> in accordance with the above mentioned script.

Can't completely follow – so one should always write "**DEPRECATED**",
correct?

Is that a blocker for you?

All the docstrings in pci/pci.c and pci/devres.c so far just use
"DEPRECATED".


P.

On Fri, Oct 18, 2024 at 12:52:15PM +0200, Philipp Stanner wrote:
> On Wed, 2024-10-16 at 13:38 +0300, Andy Shevchenko wrote:
> > On Wed, Oct 16, 2024 at 11:49:05AM +0200, Philipp Stanner wrote:

...

> > > + * This function is DEPRECATED. Do not use it in new code.
> > 
> > Interestingly that the syntax of the DEPRECATED is not documented
> > (yet?),
> > however the sphinx parser hints us about **DEPRECATED** format — see
> > Documentation/sphinx/parse-headers.pl:251. In any case the above
> > seems
> > like second used (in a form of the full sentence) and will be updated
> > in accordance with the above mentioned script.
> 
> Can't completely follow – so one should always write "**DEPRECATED**",
> correct?

I can't answer to this, because there may be "rendered" form and in this case
it should not be surrounded by double asterisks, otherwise it's better to have
at the start.

> Is that a blocker for you?

Nope, I mentioned this in the last sentence in my previous reply.

> All the docstrings in pci/pci.c and pci/devres.c so far just use
> "DEPRECATED".

Yeah, this, if ever needed, has to be changed at once.

-- 
With Best Regards,
Andy Shevchenko