[PATCH v2 4/5] dt-bindings/perf: Add Arm CoreSight PMU

[Robin Murphy]

On 2023-12-20 7:30 am, Krzysztof Kozlowski wrote:
> On 19/12/2023 15:24, Robin Murphy wrote:
>> On 2023-12-18 7:03 am, Krzysztof Kozlowski wrote:
>>> On 15/12/2023 19:39, Robin Murphy wrote:
>>>>>> +required:
>>>>>> +  - compatible
>>>>>> +  - reg
>>>>>> +
>>>>>> +additionalProperties: false
>>>>>
>>>>> Why no example to validate the binding?
>>>>
>>>> IMO for such a trivial binding built out of common properties, an
>>>> equally trivial example isn't going to add any value, since it won't do
>>>> anything more than re-state the individual property definitions above.
>>>> In bindings where we have conditional relationships between properties,
>>>> or complex encodings where a practical example can help explain a
>>>> definition (e.g. a map/mask pair for a set of input values), then
>>>> absolutely, an example can add something more to help the author and/or
>>>> users. But otherwise, the thing I've really grown to like about schema
>>>> is how thoroughly self-describing the definitions themselves can now be.
>>>
>>> The example is used to validate the schema.
>>
>> Can you clarify what that *means*, though? As far as I can tell from a
>> bit of experimentation, "make dt_bindings_check" picks up errors in the
>> schema definition itself just the same whether an example is present or
>> not. Thus I still fail to understand what else would be validated by me
>> writing an example here, other than my personal ability to comprehend my
>> own binding.
> 
> You miss here the part that the actual binding is used to verify the
> example used. This is something entirely different than validating
> schema against meta-schema.

If I say "All cats are orange.", it's certainly meta-valid in terms of 
being a well-constructed English sentence, but is it true? If I then 
show you a picture of Garfield as an example to prove my assertion, does 
that make it any more true?

As long as a definition is self-consistent to begin with, contriving a 
"correct" example *from* it does not and can not prove anything about 
the overall correctness of that definition. However, I guess that the 
subtlety of that initial condition might be where your argument comes 
from - I've been taking it for granted here since I'm sufficiently 
confident that I can write correct schema which means what I intend it 
to mean, but as a reviewer I appreciate that you're not necessarily 
going to make the same assumption, so there's value for you if patches 
include a sanity check to give the bot a chance to weed out stuff that's 
completely broken. I would still hesitate to call that "validation", though.

Thanks,
Robin.

>>
>> Yes, I'm well aware that back when we were bootstrapping dtschema it was
>> useful to confirm that schemas were written to correctly describe
>> *existing* known-good DT fragments. However with new bindings like this
>> we've already reached the end goal, where we write an authoritative
>> schema first, then the users follow from there. As I alluded to above,
>> there are reasons why I would actually prefer *not* to provide a usage
>> example here - frankly if a user doesn't understand which parts of the
>> architecture their hardware implements, and/or can't figure out how to
>> copy a single compatible string and write a standard reg property, I
>> would much rather they come to me asking how to write a DT entry, than
>> blindly copy-paste a verbatim example into their DTS, then come to me
>> reporting a "bug" with the driver crashing or failing to probe. I'd love
>> to say I have no experience to base that judgement on, but...
> 
> Sure, considering the size of the binding the benefits of the example
> here are rather low.
> 
> Best regards,
> Krzysztof
>