Re: [PATCH 6/9] dt-bindings: Add RISC-V advanced PLIC bindings

Conor Dooley
2022-11-13T15:44:57Z

Hey Anup,

Ditto the $subject nit here.

On Fri, Nov 11, 2022 at 10:12:04AM +0530, Anup Patel wrote:
> We add DT bindings document for RISC-V advanced platform level interrupt
> controller (APLIC) defined by the RISC-V advanced interrupt architecture
> (AIA) specification.
>
> Signed-off-by: Anup Patel <apatel@ventanamicro.com>
> ---
> .../interrupt-controller/riscv,aplic.yaml | 136 ++++++++++++++++++
> 1 file changed, 136 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml
>
> diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml b/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml
> new file mode 100644
> index 000000000000..0aa48571f3bc
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,aplic.yaml
> @@ -0,0 +1,136 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/interrupt-controller/riscv,aplic.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: RISC-V Advancded Platform Level Interrupt Controller (APLIC)

Typo: Advanced

> +
> +maintainers:
> + - Anup Patel <anup@brainfault.org>
> +
> +description:
> + The RISC-V advanced interrupt architecture (AIA) defines advanced platform
^
Missing an article here?

> + level interrupt controller (APLIC) for handling wired interrupts in a
> + RISC-V platform. The RISC-V AIA specification can be found at
> + https://github.com/riscv/riscv-aia.
> +
> + The RISC-V APLIC is implemented as hierarchical APLIC domains where all
> + interrupt sources connect to the root domain which can further delegate
> + interrupts to child domains. We have one device tree node for each APLIC

While I am nitpicking, s/We have/There is/ ?

> + domain.
> +
> +allOf:
> + - $ref: /schemas/interrupt-controller.yaml#
> +
> +properties:
> + compatible:
> + items:
> + - enum:
> + - vendor,chip-aplic

Same comment here about the validity of this placeholder.

> + - const: riscv,aplic
> +
> + reg:
> + maxItems: 1
> +
> + interrupt-controller: true
> +
> + "#interrupt-cells":
> + const: 2
> +
> + interrupts-extended:
> + minItems: 1
> + maxItems: 16384
> + description:
> + The presence of this property implies that given APLIC domain directly
^
Missing indefinite article here (and in msi-parent)?

> + injects external interrupts to a set of RISC-V HARTS (or CPUs). Each
> + node pointed to should be a riscv,cpu-intc node, which has a riscv node
> + (i.e. RISC-V HART) as parent.
> +
> + msi-parent:
> + description:
> + The presence of this property implies that given APLIC domain forwards
> + wired interrupts as MSIs to a AIA incoming message signaled interrupt
> + controller (IMSIC). This property should be considered only when the
> + interrupts-extended property is absent.

This mutual exclusion can be represented, can't it?
IIRC it is some sort of oneOf thing, somewhat like below:
oneOf:
- required:
- msi-parent
- required:
- interrupts-extended

AFAIR from doing the i2c ocores binding, this will force the addition of
one, but not both, to a node.

Or is this not actually mutually exclusive & the msi-parent property is
permitted but just left unused if interrupts-extended is present?

> + riscv,num-sources:
> + $ref: "/schemas/types.yaml#/definitions/uint32"
> + minimum: 1
> + maximum: 1023
> + description:
> + Specifies how many wired interrupts are supported by this APLIC domain.
> +
> + riscv,children:
> + $ref: '/schemas/types.yaml#/definitions/phandle-array'
> + minItems: 1
> + maxItems: 1024
> + description:
> + This property represents a list of child APLIC domains for the given
> + APLIC domain. Each child APLIC domain is assigned child index in
> + increasing order with the first child APLIC domain assigned child
> + index 0. The APLIC domain child index is used by firmware to delegate
> + interrupts from the given APLIC domain to a particular child APLIC
> + domain.
> +
> + riscv,delegate:
> + $ref: '/schemas/types.yaml#/definitions/phandle-array'
> + minItems: 1
> + maxItems: 1024
> + description:
> + This property represents a interrupt delegation list where each entry
> + is a triple consisting of child APLIC domain phandle, first interrupt
> + number, and last interrupt number. The firmware will configure interrupt
> + delegation registers based on interrupt delegation list.

What is the inter dependence of the children and delegate?
Is it valid to have a delegate property without children?
Can the firmware delegate interrupts without the delegation list, based
on the children property alone? Or is it effectively useless without a
children property?

In your examples, the second has msi-parent but neither of these custom
properties. Do the children/delegate properties have a meaning in the
msi-parent case?

I think the binding should enforce whatever dependency exists there.
Thanks,
Conor.

> +
> +additionalProperties: false
> +
> +required:
> + - compatible
> + - reg
> + - interrupt-controller
> + - "#interrupt-cells"
> + - riscv,num-sources
> +
> +examples:
> + - |
> + // Example 1 (APIC domain directly injecting interrupt to HARTs):
> +
> + aplic0: interrupt-controller@c000000 {
> + compatible = "vendor,chip-aplic", "riscv,aplic";
> + interrupts-extended = <&cpu1_intc 11>,
> + <&cpu2_intc 11>,
> + <&cpu3_intc 11>,
> + <&cpu4_intc 11>;
> + reg = <0xc000000 0x4080>;
> + interrupt-controller;
> + #interrupt-cells = <2>;
> + riscv,num-sources = <63>;
> + riscv,children = <&aplic1>;
> + riscv,delegate = <&aplic1 1 63>;
> + };
> +
> + aplic1: interrupt-controller@d000000 {
> + compatible = "vendor,chip-aplic", "riscv,aplic";
> + interrupts-extended = <&cpu1_intc 9>,
> + <&cpu2_intc 9>,
> + <&cpu3_intc 9>,
> + <&cpu4_intc 9>;
> + reg = <0xd000000 0x4080>;
> + interrupt-controller;
> + #interrupt-cells = <2>;
> + riscv,num-sources = <63>;
> + };
> +
> + - |
> + // Example 2 (APIC domain forwarding interrupts as MSIs):
> +
> + interrupt-controller@d000000 {
> + compatible = "vendor,chip-aplic", "riscv,aplic";
> + msi-parent = <&imsics>;
> + reg = <0xd000000 0x4000>;
> + interrupt-controller;
> + #interrupt-cells = <2>;
> + riscv,num-sources = <63>;
> + };
> +...
> --
> 2.34.1
>
>
> _______________________________________________
> linux-riscv mailing list
> linux-riscv@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-riscv