Re: [PATCH 2/3] dt-bindings: interrupt-controller: RISC-V local interrupt controller docs

[Palmer Dabbelt]

On Mon, 25 Jun 2018 13:04:48 PDT (-0700), christoph@xxxxxxxxxxxxxx wrote:
> On Fri, Jun 22, 2018 at 04:20:05PM -0700, Palmer Dabbelt wrote:
> > From: Palmer Dabbelt <palmer@xxxxxxxxxxx>
> >
> > This patch adds documentation on the RISC-V local interrupt controller,
> > which is a per-hart interrupt controller that manages all interrupts
> > entering a RISC-V hart.  This interrupt controller is present on all
> > RISC-V systems.
> >
> > Signed-off-by: Palmer Dabbelt <palmer@xxxxxxxxxxx>
> > ---
> >  .../interrupt-controller/riscv,cpu-intc.txt        | 41 ++++++++++++++++++++++
> >  1 file changed, 41 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt
> >
> > diff --git a/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt
> > new file mode 100644
> > index 000000000000..61900e2e3868
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/interrupt-controller/riscv,cpu-intc.txt
> > @@ -0,0 +1,41 @@
> > +RISC-V Hart-Level Interrupt Controller (HLIC)
> > +---------------------------------------------
> > +
> > +RISC-V cores include Control Status Registers (CSRs) which are local to each
> > +hart and can be read or written by software. Some of these CSRs are used to
> > +control local interrupts connected to the core.  Every interrupt is ultimately
> > +routed through a hart's HLIC before it interrupts that hart.
> > +
> > +The RISC-V supervisor ISA manual specifies three interrupt sources that are
> > +attached to every HLIC: software interrupts, the timer interrupt, and external
> > +interrupts.  Software interrupts are used to send IPIs between cores.  The
> > +timer interrupt comes from an architecturally mandated real-time timer that is
> > +controller via SBI calls and CSR reads.  External interrupts connect all other
> > +device interrupts to the HLIC, which are routed via the platform-level
> > +interrupt controller (PLIC).
> > +
> > +All RISC-V systems that conform to the supervisor ISA specification are
> > +required to have a HLIC with these three interrupt sources present.  Since the
> > +interrupt map is defined by the ISA it's not listed in the HLIC's device tree
> > +entry, though external interrupt controllers (like the PLIC, for example) will
> > +need to define how their interrupts map to the relevant HLICs.
> > +
> > +Required properties:
> > +- compatible : "riscv,cpu-intc"
> > +- #interrupt-cells : should be <1>
> > +- interrupt-controller : Identifies the node as an interrupt controller
> > +
> > +Furthermore, this interrupt-controller MUST be embedded inside the cpu
> > +definition of the hart whose CSRs control these local interrupts.
> > +
> > +An example device tree entry for a HLIC is show below.
>
> Spotted a typo here, "show" -> "shown".

Thanks.  It looks like we're actually dropping this binding and integrating 
this first-level interrupt controller into the core RISC-V arch code as keeping 
it split out results in too many inefficiencies.

> > +
> > +	cpu1: cpu@1 {
> > +		compatible = "riscv";
> > +		...
> > +		cpu1-intc: interrupt-controller {
> > +			#interrupt-cells = <1>;
> > +			compatible = "riscv,cpu-intc";
> > +			interrupt-controller;
> > +		};
> > +	};
> > --
> > 2.16.4
>
> Also, I've noticed that double spaces after punctuation are used pretty
> inconsistently throughout the document. Is that intended?

No.  I noticed this in the PLIC document as well, I'll fix that one up.

Thanks!