scripts: edtlib: Automatically include base.yaml in all bindings

[ulfalizer]

Main commits:

scripts: edtlib: Automatically include base.yaml in all bindings

This removes some boilerplate from bindings and makes things more
consistent. One downside is that all properties declared in base.yaml
can now appear on all nodes, including on nodes where they don't make
sense, but it's probably worth it.

base.yaml is moved to scripts/dts/base.yaml, and is considered part of
edtlib internals.

The automatic base.yaml inclusion is documented in
dts/binding-template.yaml and in the legacy syntax section of
doc/guides/dts/index.rst.

'include: base.yaml' is still accepted, but is ignored, and makes edtlib
print a deprecation warning. The warning mentions the new location of
base.yaml.

Remove a 'clocks' declaration from dts/bindings/clock/fixed-clock.yaml,
which declares it as 'type: array'. It clashes with the declaration for
'clocks' in base.yaml, which has it as 'type: phandle-array'. No 'clocks
= <(number) (number) ...>' assignments exist anywhere, which is the form
of assignment expected for 'type: array'.

Piggyback some binding consistency nits and a small bugfix that allows
empty files to be included (the crux is that PyYAML returns None instead
of an empty dict for them).

The empty file fix is needed because of dts/bindings/mmc/mmc.yaml, which
turns empty besides some comments if the 'include: base.yaml' is
removed. Maybe it should be removed instead.

dts: bindings: Remove base.yaml includes

base.yaml is now included automatically, so it doesn't need to be
included explicitly.

Piggybacked nit:

scripts: edtlib: Fix some *-map-mask/*-map-pass-thru typos in comments

The "map" part got lost.

[zephyrbot]

All checks are passing now.

Tip: The bot edits this comment instead of posting a new one, so you can check the comment's history to see earlier messages.

[erwango]

@ulfalizer, I understand the interest but I'm afraid this could confuse people. One advantage of current inclusion of base.yaml is that it makes script logic vs bindings quite transparent to users.
If we're doing this change, would be nice to keep a clear enought comment in all bindings to make base.yaml inclusion less opaque.

[ulfalizer]

@ulfalizer, I understand the interest but I'm afraid this could confuse people. One advantage of current inclusion of base.yaml is that it makes script logic vs bindings quite transparent to users.

Yeah, it needs to be well-documented and discoverable at least.

I've now documented it in dts/binding-template.yaml and in the legacy syntax section of doc/guides/dts/index.rst. I also added a warning to edtlib.py that's printed if base.yaml is included:

for fname in fnames:
    if fname == "base.yaml":
        self._warn(
            "'include: base.yaml' in {} is deprecated and redundant. "
            "base.yaml is now automatically included in all bindings, "
            "and can be found at scripts/dts/base.yaml."
            .format(binding_path))
        continue

I wonder if it could be mentioned elsewhere too.

If we're doing this change, would be nice to keep a clear enought comment in all bindings to make base.yaml inclusion less opaque.

I wonder if the added documentation and warning might make it easy enough to figure out. Feels a bit spammy to add 2-3 lines to every binding, especially once you already know it.

[ulfalizer]

I'm not sure I think this makes sense. I get the value in reducing the need to include base.yaml everywhere, but I think its better to be explicit vs having an implied "inclusion".

One nice thing about it besides shortening bindings is that it forces consistency. If someone tries to add a property to a binding that clashes with something in base.yaml, it will be an error, even if they forget to include base.yaml. That revealed an issue in fixed-clock.yaml in this PR, for example.

Some other systems (e.g. bitbake and dt-schema) also have base configuration files that are included implicitly.

It makes things slightly less transparent, but I think people will pick up on it pretty quickly.

[ulfalizer]

Should also speed up binding parsing a bit btw, because base.yaml is only parsed once now.

[dbkinder]

LGTM, thanks.

[erwango]

@galak, should we keep this one ?