diff mbox series

[v2,02/11] PCI: Add the pci_get_class_masked() helper

Message ID 20230808223412.1743176-3-sui.jingfeng@linux.dev (mailing list archive)
State Changes Requested
Delegated to: Bjorn Helgaas
Headers show
Series Fix typos, comments and copyright | expand

Commit Message

Sui Jingfeng Aug. 8, 2023, 10:34 p.m. UTC 
From: Sui Jingfeng <suijingfeng@loongson.cn>

Because there is no good way to get the mask member used to searching for
devices that conform to a specific PCI class code, an application needs to
process all PCI display devices can achieve its goal as follows:

pdev = NULL;
do {
	pdev = pci_get_class_masked(PCI_BASE_CLASS_DISPLAY << 16, 0xFF0000, pdev);
	if (pdev)
		do_something_for_pci_display_device(pdev);
} while (pdev);

While previously, we just can not ignore Sub-Class code and the Programming
Interface byte when do the searching.

Signed-off-by: Sui Jingfeng <suijingfeng@loongson.cn>
---
 drivers/pci/search.c | 30 ++++++++++++++++++++++++++++++
 include/linux/pci.h  |  7 +++++++
 2 files changed, 37 insertions(+)

Comments

Ilpo Järvinen Aug. 9, 2023, 2:01 p.m. UTC | #1 
On Wed, 9 Aug 2023, Sui Jingfeng wrote:

> From: Sui Jingfeng <suijingfeng@loongson.cn>
> 
> Because there is no good way to get the mask member used to searching for
> devices that conform to a specific PCI class code, an application needs to
> process all PCI display devices can achieve its goal as follows:

This is mixing old and new way in a single sentence (which is confusing)?
 
> pdev = NULL;
> do {
> 	pdev = pci_get_class_masked(PCI_BASE_CLASS_DISPLAY << 16, 0xFF0000, pdev);
> 	if (pdev)
> 		do_something_for_pci_display_device(pdev);
> } while (pdev);
> 
> While previously, we just can not ignore Sub-Class code and the Programming

cannot

> Interface byte when do the searching.

doing the search.

> 
> Signed-off-by: Sui Jingfeng <suijingfeng@loongson.cn>
> ---
>  drivers/pci/search.c | 30 ++++++++++++++++++++++++++++++
>  include/linux/pci.h  |  7 +++++++
>  2 files changed, 37 insertions(+)
> 
> diff --git a/drivers/pci/search.c b/drivers/pci/search.c
> index b4c138a6ec02..f1c15aea868b 100644
> --- a/drivers/pci/search.c
> +++ b/drivers/pci/search.c
> @@ -334,6 +334,36 @@ struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device,
>  }
>  EXPORT_SYMBOL(pci_get_device);
>  
> +/**
> + * pci_get_class_masked - begin or continue searching for a PCI device by class and mask
> + * @class: search for a PCI device with this class designation
> + * @from: Previous PCI device found in search, or %NULL for new search.
> + *
> + * Iterates through the list of known PCI devices.  If a PCI device is

No double spaces in kernel comments. Perhaps your editor might be adding 
them on reflow (might be configurable to not do that).

> + * found with a matching @class, the reference count to the device is
> + * incremented and a pointer to its device structure is returned.
> + * Otherwise, %NULL is returned.
> + * A new search is initiated by passing %NULL as the @from argument.
> + * Otherwise if @from is not %NULL, searches continue from next device
> + * on the global list.  The reference count for @from is always decremented
> + * if it is not %NULL.

Use kerneldoc's Return: section for describing return value.

> + */
> +struct pci_dev *pci_get_class_masked(unsigned int class, unsigned int mask,
> +				     struct pci_dev *from)
> +{
> +	struct pci_device_id id = {
> +		.vendor = PCI_ANY_ID,
> +		.device = PCI_ANY_ID,
> +		.subvendor = PCI_ANY_ID,
> +		.subdevice = PCI_ANY_ID,
> +		.class_mask = mask,
> +		.class = class,
> +	};
> +
> +	return pci_get_dev_by_id(&id, from);
> +}
> +EXPORT_SYMBOL(pci_get_class_masked);
> +
>  /**
>   * pci_get_class - begin or continue searching for a PCI device by class
>   * @class: search for a PCI device with this class designation
> diff --git a/include/linux/pci.h b/include/linux/pci.h
> index 0ff7500772e6..b20e7ba844bf 100644
> --- a/include/linux/pci.h
> +++ b/include/linux/pci.h
> @@ -1180,6 +1180,9 @@ struct pci_dev *pci_get_slot(struct pci_bus *bus, unsigned int devfn);
>  struct pci_dev *pci_get_domain_bus_and_slot(int domain, unsigned int bus,
>  					    unsigned int devfn);
>  struct pci_dev *pci_get_class(unsigned int class, struct pci_dev *from);
> +struct pci_dev *pci_get_class_masked(unsigned int class, unsigned int mask,
> +				     struct pci_dev *from);
> +
>  int pci_dev_present(const struct pci_device_id *ids);
>  
>  int pci_bus_read_config_byte(struct pci_bus *bus, unsigned int devfn,
> @@ -1895,6 +1898,10 @@ static inline struct pci_dev *pci_get_class(unsigned int class,
>  					    struct pci_dev *from)
>  { return NULL; }
>  
> +static inline struct pci_dev *pci_get_class_masked(unsigned int class,
> +						   unsigned int mask,
> +						   struct pci_dev *from)
> +{ return NULL; }
>  
>  static inline int pci_dev_present(const struct pci_device_id *ids)
>  { return 0; }
>
Sui Jingfeng Aug. 10, 2023, 1:05 p.m. UTC | #2 
Hi,


On 2023/8/9 22:01, Ilpo Järvinen wrote:
> On Wed, 9 Aug 2023, Sui Jingfeng wrote:
>
>> From: Sui Jingfeng <suijingfeng@loongson.cn>
>>
>> Because there is no good way to get the mask member used to searching for
>> devices that conform to a specific PCI class code, an application needs to
>> process all PCI display devices can achieve its goal as follows:
> This is mixing old and new way in a single sentence (which is confusing)?


Thanks for reviewing, but I can't understand this sentence.
Are you telling me that my description have grammar problem or something else?


I means that before apply this patch, we don't have a function can be used
to get all PCI(e) devices in a system by matching against its the PCI base class code only,
while keep the Sub-Class code and the Programming Interface ignored.
By supply a mask as argument, such thing become possible.

If an application want to process all PCI display devices in the system,
then it can achieve its goal by calling pci_get_class_masked() function.


>> pdev = NULL;
>> do {
>> 	pdev = pci_get_class_masked(PCI_BASE_CLASS_DISPLAY << 16, 0xFF0000, pdev);
>> 	if (pdev)
>> 		do_something_for_pci_display_device(pdev);
>> } while (pdev);
>>
>> While previously, we just can not ignore Sub-Class code and the Programming
> cannot
>
>> Interface byte when do the searching.
> doing the search.


OK, will be fixed at the next version.


>> Signed-off-by: Sui Jingfeng <suijingfeng@loongson.cn>
>> ---
>>   drivers/pci/search.c | 30 ++++++++++++++++++++++++++++++
>>   include/linux/pci.h  |  7 +++++++
>>   2 files changed, 37 insertions(+)
>>
>> diff --git a/drivers/pci/search.c b/drivers/pci/search.c
>> index b4c138a6ec02..f1c15aea868b 100644
>> --- a/drivers/pci/search.c
>> +++ b/drivers/pci/search.c
>> @@ -334,6 +334,36 @@ struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device,
>>   }
>>   EXPORT_SYMBOL(pci_get_device);
>>   
>> +/**
>> + * pci_get_class_masked - begin or continue searching for a PCI device by class and mask
>> + * @class: search for a PCI device with this class designation
>> + * @from: Previous PCI device found in search, or %NULL for new search.
>> + *
>> + * Iterates through the list of known PCI devices.  If a PCI device is
> No double spaces in kernel comments. Perhaps your editor might be adding
> them on reflow (might be configurable to not do that).
>
>> + * found with a matching @class, the reference count to the device is
>> + * incremented and a pointer to its device structure is returned.
>> + * Otherwise, %NULL is returned.
>> + * A new search is initiated by passing %NULL as the @from argument.
>> + * Otherwise if @from is not %NULL, searches continue from next device
>> + * on the global list.  The reference count for @from is always decremented
>> + * if it is not %NULL.
> Use kerneldoc's Return: section for describing return value.
>
>> + */
>> +struct pci_dev *pci_get_class_masked(unsigned int class, unsigned int mask,
>> +				     struct pci_dev *from)
>> +{
>> +	struct pci_device_id id = {
>> +		.vendor = PCI_ANY_ID,
>> +		.device = PCI_ANY_ID,
>> +		.subvendor = PCI_ANY_ID,
>> +		.subdevice = PCI_ANY_ID,
>> +		.class_mask = mask,
>> +		.class = class,
>> +	};
>> +
>> +	return pci_get_dev_by_id(&id, from);
>> +}
>> +EXPORT_SYMBOL(pci_get_class_masked);
>> +
>>   /**
>>    * pci_get_class - begin or continue searching for a PCI device by class
>>    * @class: search for a PCI device with this class designation
>> diff --git a/include/linux/pci.h b/include/linux/pci.h
>> index 0ff7500772e6..b20e7ba844bf 100644
>> --- a/include/linux/pci.h
>> +++ b/include/linux/pci.h
>> @@ -1180,6 +1180,9 @@ struct pci_dev *pci_get_slot(struct pci_bus *bus, unsigned int devfn);
>>   struct pci_dev *pci_get_domain_bus_and_slot(int domain, unsigned int bus,
>>   					    unsigned int devfn);
>>   struct pci_dev *pci_get_class(unsigned int class, struct pci_dev *from);
>> +struct pci_dev *pci_get_class_masked(unsigned int class, unsigned int mask,
>> +				     struct pci_dev *from);
>> +
>>   int pci_dev_present(const struct pci_device_id *ids);
>>   
>>   int pci_bus_read_config_byte(struct pci_bus *bus, unsigned int devfn,
>> @@ -1895,6 +1898,10 @@ static inline struct pci_dev *pci_get_class(unsigned int class,
>>   					    struct pci_dev *from)
>>   { return NULL; }
>>   
>> +static inline struct pci_dev *pci_get_class_masked(unsigned int class,
>> +						   unsigned int mask,
>> +						   struct pci_dev *from)
>> +{ return NULL; }
>>   
>>   static inline int pci_dev_present(const struct pci_device_id *ids)
>>   { return 0; }
>>
Ilpo Järvinen Aug. 11, 2023, 6:31 a.m. UTC | #3 
On Thu, 10 Aug 2023, suijingfeng wrote:

> Hi,
> 
> 
> On 2023/8/9 22:01, Ilpo Järvinen wrote:
> > On Wed, 9 Aug 2023, Sui Jingfeng wrote:
> > 
> > > From: Sui Jingfeng <suijingfeng@loongson.cn>
> > > 
> > > Because there is no good way to get the mask member used to searching for
> > > devices that conform to a specific PCI class code, an application needs to
> > > process all PCI display devices can achieve its goal as follows:
> > This is mixing old and new way in a single sentence (which is confusing)?
> 
> 
> Thanks for reviewing, but I can't understand this sentence.
> Are you telling me that my description have grammar problem or something else?

I think it's a bit of both.

> I means that before apply this patch, we don't have a function can be used
> to get all PCI(e) devices in a system by matching against its the PCI base
> class code only,
> while keep the Sub-Class code and the Programming Interface ignored.
> By supply a mask as argument, such thing become possible.

This explanation you put into this reply is much easier to follow and 
understand. I recommend you'd use it to replace the unclear fragment 
above. So something along the lines of:

  There is no function that can be used to get all PCI(e) devices in a 
  system by matching against its the PCI base class code only, while keep 
  the Sub-Class code and the Programming Interface ignored.

  Add pci_get_class_masked() to allow supplying a mask for the get.

  [After this you can put the explanining code block+its intro if you 
   want]
diff mbox series

Patch

diff --git a/drivers/pci/search.c b/drivers/pci/search.c
index b4c138a6ec02..f1c15aea868b 100644
--- a/drivers/pci/search.c
+++ b/drivers/pci/search.c
@@ -334,6 +334,36 @@  struct pci_dev *pci_get_device(unsigned int vendor, unsigned int device,
 }
 EXPORT_SYMBOL(pci_get_device);
 
+/**
+ * pci_get_class_masked - begin or continue searching for a PCI device by class and mask
+ * @class: search for a PCI device with this class designation
+ * @from: Previous PCI device found in search, or %NULL for new search.
+ *
+ * Iterates through the list of known PCI devices.  If a PCI device is
+ * found with a matching @class, the reference count to the device is
+ * incremented and a pointer to its device structure is returned.
+ * Otherwise, %NULL is returned.
+ * A new search is initiated by passing %NULL as the @from argument.
+ * Otherwise if @from is not %NULL, searches continue from next device
+ * on the global list.  The reference count for @from is always decremented
+ * if it is not %NULL.
+ */
+struct pci_dev *pci_get_class_masked(unsigned int class, unsigned int mask,
+				     struct pci_dev *from)
+{
+	struct pci_device_id id = {
+		.vendor = PCI_ANY_ID,
+		.device = PCI_ANY_ID,
+		.subvendor = PCI_ANY_ID,
+		.subdevice = PCI_ANY_ID,
+		.class_mask = mask,
+		.class = class,
+	};
+
+	return pci_get_dev_by_id(&id, from);
+}
+EXPORT_SYMBOL(pci_get_class_masked);
+
 /**
  * pci_get_class - begin or continue searching for a PCI device by class
  * @class: search for a PCI device with this class designation
diff --git a/include/linux/pci.h b/include/linux/pci.h
index 0ff7500772e6..b20e7ba844bf 100644
--- a/include/linux/pci.h
+++ b/include/linux/pci.h
@@ -1180,6 +1180,9 @@  struct pci_dev *pci_get_slot(struct pci_bus *bus, unsigned int devfn);
 struct pci_dev *pci_get_domain_bus_and_slot(int domain, unsigned int bus,
 					    unsigned int devfn);
 struct pci_dev *pci_get_class(unsigned int class, struct pci_dev *from);
+struct pci_dev *pci_get_class_masked(unsigned int class, unsigned int mask,
+				     struct pci_dev *from);
+
 int pci_dev_present(const struct pci_device_id *ids);
 
 int pci_bus_read_config_byte(struct pci_bus *bus, unsigned int devfn,
@@ -1895,6 +1898,10 @@  static inline struct pci_dev *pci_get_class(unsigned int class,
 					    struct pci_dev *from)
 { return NULL; }
 
+static inline struct pci_dev *pci_get_class_masked(unsigned int class,
+						   unsigned int mask,
+						   struct pci_dev *from)
+{ return NULL; }
 
 static inline int pci_dev_present(const struct pci_device_id *ids)
 { return 0; }