Re: [PATCH v6 04/15] PCI: Add pci_find_vsec_capability() to find a specific VSEC

From: Bjorn Helgaas
Date: Wed Feb 17 2021 - 17:28:44 EST


[+cc Krzysztof, since he commented on a previous version]
[+cc Lukas, who previously proposed exactly what I suggest below,
sorry for repeating. I think Lukas was right to propose passing in
the vendor ID because it makes it easier to read the caller.]

When you post new versions of a series, please cc people who commented
on previous versions.

On Fri, Feb 12, 2021 at 06:37:39PM +0100, Gustavo Pimentel wrote:
> Adds another helper to ones that already exist called
> pci_find_vsec_capability. This helper crawls through the device PCI
> config space searching for a specific ID on the Vendor-Specific Extended
> Capabilities section.

Add pci_find_vsec_capability() to locate a Vendor-Specific Extended
Capability with the specified VSEC ID.
>
> The Vendor-Specific Extended Capability (VSEC) is a special PCI
> capability (acts like container) defined by PCI-SIG that allows the one
> or more proprietary capabilities defined by the vendor which aren't
> standard or shared between the manufactures.

s/is a special ... by PCI-SIG that//
s/allows the one/allows one/
s/the manufactures/manufacturers/ (or maybe "vendors" to match previous use)

> Signed-off-by: Gustavo Pimentel <gustavo.pimentel@xxxxxxxxxxxx>
> ---
> drivers/pci/pci.c | 34 ++++++++++++++++++++++++++++++++++
> include/linux/pci.h | 2 ++
> include/uapi/linux/pci_regs.h | 6 ++++++
> 3 files changed, 42 insertions(+)
>
> diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> index b9fecc2..628aa9f 100644
> --- a/drivers/pci/pci.c
> +++ b/drivers/pci/pci.c
> @@ -693,6 +693,40 @@ u8 pci_find_ht_capability(struct pci_dev *dev, int ht_cap)
> EXPORT_SYMBOL_GPL(pci_find_ht_capability);
>
> /**
> + * pci_find_vsec_capability - Find a vendor-specific extended capability
> + * @dev: PCI device to query
> + * @cap: vendor-specific capability ID code
> + *
> + * Typically this function will be called by the PCI driver, which passes
> + * through argument the 'struct pci_dev *' already pointing for the device
> + * config space that is associated with the vendor and device ID which will
> + * know which ID to search and what to do with it, however, there might be
> + * cases that this function could be called outside of this scope and
> + * therefore is the caller responsibility to check the vendor and/or
> + * device ID first.

This is important because it's a bit subtle. IIUC, each vendor
(identified by Vendor ID at 0x00 in config space) can define its own
VSEC IDs, so it can define up to 2^16 == 64K VSEC structures.

Of course there's not room for that many in config space; but the
point is that the vendor chooses its own VSEC IDs and doesn't need to
coordinate with anybody.

So a VSEC ID 0x0006 in a Synopsys device (Vendor ID 0x16c3) has
nothing to do with a VSEC ID 0x0006 in an Intel device (Vendor ID
0x8086), and it's up to the caller to make sure it's using the correct
one.

I wonder if it would help avoid mistakes if we made the interface look
like this:

u16 pci_find_vsec_capability(struct pci_dev *dev, u16 vendor, int vsec_cap_id)
{
if (vendor != dev->vendor)
return 0;

while ((vsec = ...))
...
}

so calls would look like this:

vsec = pci_find_vsec_capability(dev, PCI_VENDOR_ID_SYNOPSYS, DW_PCIE_VSEC_DMA_ID);

which would make it more obvious that DW_PCIE_VSEC_DMA_ID is only
valid in a Synopsys device.

The function comment could be something like this:

pci_find_vsec_capability - Find a vendor-specific extended capability
@dev: PCI device to query
@vendor: Vendor ID for which capability is defined
@vsec_cap_id: Vendor-specific capability ID

If @dev has Vendor ID @vendor, search for a VSEC capability with
VSEC ID @vsec_cap_id. If found, return the capability offset in
config space; otherwise return 0.

Or maybe it's even more subtle than I thought, and I'm missing
something :)

> + * Returns the address of the vendor-specific structure that matches the
> + * requested capability ID code within the device's PCI configuration space
> + * or 0 if it does not find a match.
> + */
> +u16 pci_find_vsec_capability(struct pci_dev *dev, int vsec_cap_id)
> +{
> + u16 vsec = 0;
> + u32 header;
> +
> + while ((vsec = pci_find_next_ext_capability(dev, vsec,
> + PCI_EXT_CAP_ID_VNDR))) {
> + if (pci_read_config_dword(dev, vsec + PCI_VSEC_HDR,
> + &header) == PCIBIOS_SUCCESSFUL &&
> + PCI_VSEC_CAP_ID(header) == vsec_cap_id)
> + return vsec;
> + }
> +
> + return 0;
> +}
> +EXPORT_SYMBOL_GPL(pci_find_vsec_capability);
> +
> +/**
> * pci_find_parent_resource - return resource region of parent bus of given
> * region
> * @dev: PCI device structure contains resources to be searched
> diff --git a/include/linux/pci.h b/include/linux/pci.h
> index b32126d..da6ab6a 100644
> --- a/include/linux/pci.h
> +++ b/include/linux/pci.h
> @@ -1080,6 +1080,8 @@ struct pci_bus *pci_find_next_bus(const struct pci_bus *from);
>
> u64 pci_get_dsn(struct pci_dev *dev);
>
> +u16 pci_find_vsec_capability(struct pci_dev *dev, int vsec_cap_id);

Can you put this declaration up with the other "find_capability"
declarations just a few lines up?

> struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device,
> struct pci_dev *from);
> struct pci_dev *pci_get_subsys(unsigned int vendor, unsigned int device,
> diff --git a/include/uapi/linux/pci_regs.h b/include/uapi/linux/pci_regs.h
> index e709ae8..deae275 100644
> --- a/include/uapi/linux/pci_regs.h
> +++ b/include/uapi/linux/pci_regs.h
> @@ -983,6 +983,12 @@
> #define PCI_VSEC_HDR 4 /* extended cap - vendor-specific */
> #define PCI_VSEC_HDR_LEN_SHIFT 20 /* shift for length field */
>
> +/* Vendor-Specific Extended Capabilities */
> +#define PCI_VSEC_HEADER 4 /* Vendor-Specific Header */
> +#define PCI_VSEC_CAP_ID(x) ((x) & 0xffff)
> +#define PCI_VSEC_CAP_REV(x) (((x) >> 16) & 0xf)
> +#define PCI_VSEC_CAP_LEN(x) (((x) >> 20) & 0xfff)

The VSEC #defines are a mess. We have already have some duplication
and inconsistent names. But I think what you need is already there:

/* Vendor-Specific (VSEC, PCI_EXT_CAP_ID_VNDR) */
#define PCI_VNDR_HEADER 4 /* Vendor-Specific Header */
#define PCI_VNDR_HEADER_ID(x) ((x) & 0xffff)
#define PCI_VNDR_HEADER_REV(x) (((x) >> 16) & 0xf)
#define PCI_VNDR_HEADER_LEN(x) (((x) >> 20) & 0xfff)

> /* SATA capability */
> #define PCI_SATA_REGS 4 /* SATA REGs specifier */
> #define PCI_SATA_REGS_MASK 0xF /* location - BAR#/inline */
> --
> 2.7.4
>