[U-Boot] [PATCH V2 2/2] pci: Update documentation to make 'compatible' string optional

[Marek Vasut]

On 08/30/2018 02:29 AM, Simon Glass wrote:
> Hi Marek,

Hi,

> On 24 August 2018 at 12:27, Marek Vasut <marek.vasut at gmail.com> wrote:
>> Reword the documentation to make it clear the compatible string is now
>> optional, yet still matching on it takes precedence over PCI IDs and
>> PCI classes.
>>
>> Signed-off-by: Marek Vasut <marek.vasut+renesas at gmail.com>
>> Cc: Simon Glass <sjg at chromium.org>
>> Cc: Tom Rini <trini at konsulko.com>
>> ---
>> V2: New patch
>> ---
>>  doc/driver-model/pci-info.txt | 14 +++++++++-----
>>  1 file changed, 9 insertions(+), 5 deletions(-)
>>
>> diff --git a/doc/driver-model/pci-info.txt b/doc/driver-model/pci-info.txt
>> index e1701d1fbc..14364c5c75 100644
>> --- a/doc/driver-model/pci-info.txt
>> +++ b/doc/driver-model/pci-info.txt
>> @@ -34,11 +34,15 @@ under that bus.
>>  Note that this is all done on a lazy basis, as needed, so until something is
>>  touched on PCI (eg: a call to pci_find_devices()) it will not be probed.
>>
>> -PCI devices can appear in the flattened device tree. If they do this serves to
>> -specify the driver to use for the device. In this case they will be bound at
>> -first. Each PCI device node must have a compatible string list as well as a
>> -<reg> property, as defined by the IEEE Std 1275-1994 PCI bus binding document
>> -v2.1. Note we must describe PCI devices with the same bus hierarchy as the
>> +PCI devices can appear in the flattened device tree. If they do, their node
>> +often contains extra information which cannot be derived from the PCI IDs or
>> +PCI class of the device. Each PCI device node must have a <reg> property, as
>> +defined by the IEEE Std 1275-1994 PCI bus binding document v2.1. Compatible
>> +string list is optional and generally not needed, since PCI is discoverable
>> +bus, albeit there are justified exceptions. If the compatible string is
>> +present, matching on it takes precedence over PCI IDs and PCI classes.
>> +
>> +Note we must describe PCI devices with the same bus hierarchy as the
>>  hardware, otherwise driver model cannot detect the correct parent/children
>>  relationship during PCI bus enumeration thus PCI devices won't be bound to
>>  their drivers accordingly. A working example like below:
>> --
>> 2.16.2
>>
> 
> Are we really saying that compatible strings are 'generally not needed'?

Yes, PCI is a discoverable bus.

> device tree pci supplement 2.1 talks about some new formats for the
> compatible string, but doesn't say it is not needed. I much prefer a
> compatible string since it is easy to find the driver in the source
> code.

But it duplicates (badly) what the PCI IDs and classes are used for
since PCI's inception.

> Can way say that a compatible string is preferred, but in extremis you
> can avoid it by...

No, see above, PCI is discoverable by design.

-- 
Best regards,
Marek Vasut