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

[Krzysztof Kozlowski]

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.

> 
> 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