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

[Simon Glass]

Hi Marek,

On 30 August 2018 at 04:20, Marek Vasut <marek.vasut at gmail.com> wrote:
> 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.

I feel that these two things are orthogonal.

You can probe the bus and find a device. That is the 'discoverable' part.

But it is not automatically configurable. If it it were, there would
be no DT node and no settings in the DT for the device. But from your
patch, in some cases we need more information, and the DT node
provides that.

So to get the settings to pass to the driver, you have to find the
device-tree node to use for the device. The only way U-Boot supports
is to use the 'reg' property, which specifies the PCI address. (We
don't support a compatible string starting with "pci...". We could
support that, but it is more code for essentially the same purpose.)

So we are not talking about the discoverability, which is already
supported by U-Boot. We are talking about the configuration of the
device, via settings passed to the driver.

In fact the only issue here is whether to require a compatible string
for PCI nodes or allow matching solely based on the 'reg' property. Is
the latter widely used in Linux? Presumably not on x86, which doesn't
even use DT.

Regards,
Simon