Re: [PATCH mlx5-next 1/2] PCI/TPH: Expose pcie_tph_get_st_table_loc()

[Bjorn Helgaas <helgaas@kernel.org>]

On Mon, Nov 03, 2025 at 06:23:26PM +0200, Yishai Hadas wrote:
> On 03/11/2025 17:43, Bjorn Helgaas wrote:
> > On Mon, Oct 27, 2025 at 11:34:01AM +0200, Leon Romanovsky wrote:
> > > From: Yishai Hadas <yishaih@nvidia.com>
> > > 
> > > Expose pcie_tph_get_st_table_loc() to be used by drivers as will be done
> > > in the next patch from the series.
> > > 
> > > Signed-off-by: Yishai Hadas <yishaih@nvidia.com>
> > > Signed-off-by: Edward Srouji <edwards@nvidia.com>
> > > Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> > > ---
> > >   drivers/pci/tph.c       | 7 ++++---
> > >   include/linux/pci-tph.h | 1 +
> > >   2 files changed, 5 insertions(+), 3 deletions(-)
> > > 
> > > diff --git a/drivers/pci/tph.c b/drivers/pci/tph.c
> > > index cc64f93709a4..8f8457ec9adb 100644
> > > --- a/drivers/pci/tph.c
> > > +++ b/drivers/pci/tph.c
> > > @@ -155,7 +155,7 @@ static u8 get_st_modes(struct pci_dev *pdev)
> > >   	return reg;
> > >   }
> > > -static u32 get_st_table_loc(struct pci_dev *pdev)
> > > +u32 pcie_tph_get_st_table_loc(struct pci_dev *pdev)
> > >   {
> > >   	u32 reg;
> > > @@ -163,6 +163,7 @@ static u32 get_st_table_loc(struct pci_dev *pdev)
> > >   	return FIELD_GET(PCI_TPH_CAP_LOC_MASK, reg);
> > >   }
> > > +EXPORT_SYMBOL(pcie_tph_get_st_table_loc);
> > 
> > OK by me, but I think we should add kernel-doc for the return value.
> > 
> > With that doc added:
> > 
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> 
> Thanks Bjorn.
> 
> We may add the below hunk.
> 
> Can that work for you ?

No, because (a) it just restates the function name and doesn't say how
to interpret the return value (you would need a PCIe spec to look it
up) and (b) kernel-doc syntax would be "Return: " (see
Documentation/doc-guide/kernel-doc.rst for examples).

> diff --git a/drivers/pci/tph.c b/drivers/pci/tph.c
> index 8f8457ec9adb..385307a9a328 100644
> --- a/drivers/pci/tph.c
> +++ b/drivers/pci/tph.c
> @@ -155,6 +155,12 @@ static u8 get_st_modes(struct pci_dev *pdev)
>         return reg;
>  }
> 
> +/**
> + * pcie_tph_get_st_table_loc - query the device for its ST table location
> + * @pdev: PCI device to query
> + *
> + * Return the location of the ST table
> + */
>  u32 pcie_tph_get_st_table_loc(struct pci_dev *pdev)
>  {
>         u32 reg;
> 
> Yishai
> 
> > 
> > 
> > >   /*
> > >    * Return the size of ST table. If ST table is not in TPH Requester Extended
> > > @@ -174,7 +175,7 @@ u16 pcie_tph_get_st_table_size(struct pci_dev *pdev)
> > >   	u32 loc;
> > >   	/* Check ST table location first */
> > > -	loc = get_st_table_loc(pdev);
> > > +	loc = pcie_tph_get_st_table_loc(pdev);
> > >   	/* Convert loc to match with PCI_TPH_LOC_* defined in pci_regs.h */
> > >   	loc = FIELD_PREP(PCI_TPH_CAP_LOC_MASK, loc);
> > > @@ -299,7 +300,7 @@ int pcie_tph_set_st_entry(struct pci_dev *pdev, unsigned int index, u16 tag)
> > >   	 */
> > >   	set_ctrl_reg_req_en(pdev, PCI_TPH_REQ_DISABLE);
> > > -	loc = get_st_table_loc(pdev);
> > > +	loc = pcie_tph_get_st_table_loc(pdev);
> > >   	/* Convert loc to match with PCI_TPH_LOC_* */
> > >   	loc = FIELD_PREP(PCI_TPH_CAP_LOC_MASK, loc);
> > > diff --git a/include/linux/pci-tph.h b/include/linux/pci-tph.h
> > > index 9e4e331b1603..ba28140ce670 100644
> > > --- a/include/linux/pci-tph.h
> > > +++ b/include/linux/pci-tph.h
> > > @@ -29,6 +29,7 @@ int pcie_tph_get_cpu_st(struct pci_dev *dev,
> > >   void pcie_disable_tph(struct pci_dev *pdev);
> > >   int pcie_enable_tph(struct pci_dev *pdev, int mode);
> > >   u16 pcie_tph_get_st_table_size(struct pci_dev *pdev);
> > > +u32 pcie_tph_get_st_table_loc(struct pci_dev *pdev);
> > >   #else
> > >   static inline int pcie_tph_set_st_entry(struct pci_dev *pdev,
> > >   					unsigned int index, u16 tag)
> > > 
> > > -- 
> > > 2.51.0
> > > 
>