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
