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
