devicetree: bindings: add top-level interrupt-source key

[mbolivar-nordic]

---

Note: this is prep work for system devicetree ( #51830 ) which is standalone and I believe is mergeable now.

We want to be able to re-use the same binding for the same peripheral IP blocks regardless of whether they appear in a single- or multi-core SoC. Switching to interrupt-source in Nordic bindings enables this.

---

Zephyr devicetree bindings support either the 'interrupts' or the
'interrupts-extended' method of specifying interrupts. These
properties are standard and defined in the Devicetree Specification.

The 'interrupts' property can be treated as a special case of the
'interrupts-extended' property; you can always write something like
this:

  node {
          interrupt-parent = <&parent>;
          interrupts = <1>;
  };

as this instead:

  node {
          interrupts-extended = <&parent 1>;
  };

The 'interrupts-extended' property, however, can be used when the node
in question is hooked up to more than one interrupt controller, and
can contain multiple elements, one per interrupt domain that the node
generates interrupts in.

Therefore, it is sensible semantically to allow an
interrupt-generating devicetree node to use either
'interrupts-extended' or 'interrupts' to specify its generated
interrupts, at the option of the devicetree author, and we can almost
do that today.

The missing piece is that we can't require in the binding that either
'interrupts' or 'interrupts-extended' is set: we can only require
individual properties; we can't say "at least one of these is
required".

You could write some BUILD_ASSERT()s to do this in the driver, but it
would be nicer to have this in the binding so the error messages are
easier to read. The extra effort seems worth it since this is a
special case where the properties are core to the specification
itself.

To enable this, add a top-level 'interrupt-source:' key to the
bindings syntax which, if true, indicates that one of 'interrupts' or
'interrupts-extended' must be set:

compatible: foo
interrupt-source: true
[...]

[galak]

I'd rather see if we can come up with a more generic way of describing the requirement instead of adding a new special case keyword.

Also, if we do go done the path of interrupt-source, is there any case in which either form should not be supported? (ie, thinking of changing base.yaml).

[galak]

Is there anything we can take / model off of on how this might be handled in dt-schema?

[galak]

Looking at dtschema/schemas/interrupts.yaml , seems we could possibly introduce a dependencies section:

dependencies:
    oneOf:
      - required:
          - interrupts
      - required:
          - interrupts-extended

[mbolivar-nordic]

I'd rather see if we can come up with a more generic way of describing the requirement instead of adding a new special case keyword.

Given that we want to go to schema eventually, is it really worth implementing this part of it now? Do you have a concrete other use case for this level of reimplementation in mind?

[mbolivar-nordic]

Looking at dtschema/schemas/interrupts.yaml , seems we could possibly introduce a dependencies section:

This syntax is pretty heavyweight to add just for this one thing and it would be harder to handle in gen_devicetree_rest. I was really hoping we could keep this minimal for now instead of start going down the road of reimplementing dt-schema when we know we'd like to transition eventually anyway

[galak]

This syntax is pretty heavyweight to add just for this one thing and it would be harder to handle in gen_devicetree_rest. I was really hoping we could keep this minimal for now instead of start going down the road of reimplementing dt-schema when we know we'd like to transition eventually anyway

Let's close if we think this needs to exist anywhere outside of base.yaml. I'm more inclined to be ok with doing interrupt-source if it really just ends up in one place.

[mbolivar-nordic]

At least for system DT, I don't know of any other place where I need to extend the bindings syntax so far. I might end up extending the compound type a bit to describe the contents of complicated properties like cpus in an execution domain, but that's all about being able to go beyond phandle-array in our current bindings, and I'm not even sure I need that.

TBH I would probably just drop this PR and add BUILD_ASSERT()s to the relevant drivers to make sure at least one property is defined rather than start re-implementing the more complicated parts of dt-schema one at a time.

[henrikbrixandersen]

TBH I would probably just drop this PR and add BUILD_ASSERT()s to the relevant drivers to make sure at least one property is defined rather than start re-implementing the more complicated parts of dt-schema one at a time.

I think that makes sense for now.

[mbolivar-nordic]

Not pursuing this further given feedback from @galak and @henrikbrixandersen