Add device tree bindings for the RPMI clock service group based
message proxy implemented by the SBI implementation (machine mode
firmware or hypervisor).

The RPMI clock service group is defined by the RISC-V platform
management interface (RPMI) specification.

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Signed-off-by: Anup Patel <apatel@ventanamicro.com>
---
 .../bindings/clock/riscv,rpmi-mpxy-clock.yaml | 64 +++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml

diff --git a/Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml b/Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml
new file mode 100644
index 000000000000..70ffc88d0110
--- /dev/null
+++ b/Documentation/devicetree/bindings/clock/riscv,rpmi-mpxy-clock.yaml
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/clock/riscv,rpmi-mpxy-clock.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: RISC-V RPMI clock service group based message proxy
+
+maintainers:
+  - Anup Patel <anup@brainfault.org>
+
+description: |
+  The RISC-V Platform Management Interface (RPMI) [1] defines a
+  messaging protocol which is modular and extensible. The supervisor
+  software can send/receive RPMI messages via SBI MPXY extension [2]
+  or some dedicated supervisor-mode RPMI transport.
+
+  The RPMI specification [1] defines clock service group for accessing
+  system clocks managed by a platform microcontroller. The SBI implementation
+  (machine mode firmware or hypervisor) can implement an SBI MPXY channel
+  to allow RPMI clock service group access to the supervisor software.
+
+  ===========================================
+  References
+  ===========================================
+
+  [1] RISC-V Platform Management Interface (RPMI) v1.0 (or higher)
+      https://github.com/riscv-non-isa/riscv-rpmi/releases
+
+  [2] RISC-V Supervisor Binary Interface (SBI) v3.0 (or higher)
+      https://github.com/riscv-non-isa/riscv-sbi-doc/releases
+
+properties:
+  compatible:
+    description:
+      Intended for use by the SBI implementation.
+    const: riscv,rpmi-mpxy-clock
+
+  mboxes:
+    maxItems: 1
+    description:
+      Mailbox channel of the underlying RPMI transport.
+
+  riscv,sbi-mpxy-channel-id:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      The SBI MPXY channel id to be used for providing RPMI access to
+      the supervisor software.
+
+required:
+  - compatible
+  - mboxes
+  - riscv,sbi-mpxy-channel-id
+
+additionalProperties: false
+
+examples:
+  - |
+    clock-controller {
+        compatible = "riscv,rpmi-mpxy-clock";
+        mboxes = <&rpmi_shmem_mbox 0x8>;
+        riscv,sbi-mpxy-channel-id = <0x1000>;
+    };
+...
-- 
2.43.0

Quoting Anup Patel (2025-07-04 00:03:40)
> Add device tree bindings for the RPMI clock service group based
> message proxy implemented by the SBI implementation (machine mode
> firmware or hypervisor).
> 
> The RPMI clock service group is defined by the RISC-V platform
> management interface (RPMI) specification.
> 
> Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> Signed-off-by: Anup Patel <apatel@ventanamicro.com>
[...]
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    clock-controller {

Maybe the name should be 'clock-service' then? I don't understand SBI so
not sure why this is in DT to begin with. Is something consuming this
node? Or a driver is binding to it?

> +        compatible = "riscv,rpmi-mpxy-clock";
> +        mboxes = <&rpmi_shmem_mbox 0x8>;
> +        riscv,sbi-mpxy-channel-id = <0x1000>;
> +    };

On Fri, Jul 25, 2025 at 8:12 AM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Anup Patel (2025-07-04 00:03:40)
> > Add device tree bindings for the RPMI clock service group based
> > message proxy implemented by the SBI implementation (machine mode
> > firmware or hypervisor).
> >
> > The RPMI clock service group is defined by the RISC-V platform
> > management interface (RPMI) specification.
> >
> > Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> > Signed-off-by: Anup Patel <apatel@ventanamicro.com>
> [...]
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    clock-controller {
>
> Maybe the name should be 'clock-service' then? I don't understand SBI so
> not sure why this is in DT to begin with. Is something consuming this
> node? Or a driver is binding to it?

SBI is a syscall style interface between SBI implementation (aka
M-mode firmware or hypervisor) and supervisor software (aka
Linux kernel).

We have DT based drivers in OpenSBI (M-mode firmware). This
binding allows Clock message proxy driver to be probed on the
OpenSBI side. The clock message proxy driver allows Linux
RPMI clock driver to send RPMI messages via OpenSBI as
proxy thereby sharing the RPMI transport between OpenSBI
and Linux kernel.

Regards,
Anup

Quoting Anup Patel (2025-07-25 09:16:12)
> On Fri, Jul 25, 2025 at 8:12 AM Stephen Boyd <sboyd@kernel.org> wrote:
> >
> > Quoting Anup Patel (2025-07-04 00:03:40)
> > > Add device tree bindings for the RPMI clock service group based
> > > message proxy implemented by the SBI implementation (machine mode
> > > firmware or hypervisor).
> > >
> > > The RPMI clock service group is defined by the RISC-V platform
> > > management interface (RPMI) specification.
> > >
> > > Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> > > Signed-off-by: Anup Patel <apatel@ventanamicro.com>
> > [...]
> > > +additionalProperties: false
> > > +
> > > +examples:
> > > +  - |
> > > +    clock-controller {
> >
> > Maybe the name should be 'clock-service' then? I don't understand SBI so
> > not sure why this is in DT to begin with. Is something consuming this
> > node? Or a driver is binding to it?
> 
> SBI is a syscall style interface between SBI implementation (aka
> M-mode firmware or hypervisor) and supervisor software (aka
> Linux kernel).
> 
> We have DT based drivers in OpenSBI (M-mode firmware). This
> binding allows Clock message proxy driver to be probed on the
> OpenSBI side. The clock message proxy driver allows Linux
> RPMI clock driver to send RPMI messages via OpenSBI as
> proxy thereby sharing the RPMI transport between OpenSBI
> and Linux kernel.

Let me try to clarify my confusion. A 'clock-controller' node without a
'#clock-cells' property is confusing.

It's not providing clks? The SBI firmware is not discoverable? Do you
have a pointer to the DTS for this node and the clock controller node in
the next patch? I'd like to understand why this is named a clock
controller when it doesn't provide clks.

On Sun, Jul 27, 2025 at 11:53 AM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Anup Patel (2025-07-25 09:16:12)
> > On Fri, Jul 25, 2025 at 8:12 AM Stephen Boyd <sboyd@kernel.org> wrote:
> > >
> > > Quoting Anup Patel (2025-07-04 00:03:40)
> > > > Add device tree bindings for the RPMI clock service group based
> > > > message proxy implemented by the SBI implementation (machine mode
> > > > firmware or hypervisor).
> > > >
> > > > The RPMI clock service group is defined by the RISC-V platform
> > > > management interface (RPMI) specification.
> > > >
> > > > Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
> > > > Signed-off-by: Anup Patel <apatel@ventanamicro.com>
> > > [...]
> > > > +additionalProperties: false
> > > > +
> > > > +examples:
> > > > +  - |
> > > > +    clock-controller {
> > >
> > > Maybe the name should be 'clock-service' then? I don't understand SBI so
> > > not sure why this is in DT to begin with. Is something consuming this
> > > node? Or a driver is binding to it?
> >
> > SBI is a syscall style interface between SBI implementation (aka
> > M-mode firmware or hypervisor) and supervisor software (aka
> > Linux kernel).
> >
> > We have DT based drivers in OpenSBI (M-mode firmware). This
> > binding allows Clock message proxy driver to be probed on the
> > OpenSBI side. The clock message proxy driver allows Linux
> > RPMI clock driver to send RPMI messages via OpenSBI as
> > proxy thereby sharing the RPMI transport between OpenSBI
> > and Linux kernel.
>
> Let me try to clarify my confusion. A 'clock-controller' node without a
> '#clock-cells' property is confusing.

Ahh, I see your point. The node name need not be 'clock-controller'
since the node is for a firmware driver which provides MPXY channel
to supervisor software (aka Linux kernel).

>
> It's not providing clks? The SBI firmware is not discoverable? Do you
> have a pointer to the DTS for this node and the clock controller node in
> the next patch? I'd like to understand why this is named a clock
> controller when it doesn't provide clks.

The firmware driver is not providing clks. Also, the SBI firmware and
various SBI extensions are indeed discoverable from supervisor software.

On the Linux side, we have two DT nodes:
1) One DT node for the SBI MPXY based mailbox-controller
    (Refer, https://lore.kernel.org/all/20250704070356.1683992-3-apatel@ventanamicro.com/)
2) Second DT node for the clock-controller based on the
    RPMI clock service group.
    (Refer, https://lore.kernel.org/all/20250704070356.1683992-10-apatel@ventanamicro.com/)

Regards,
Anup

Quoting Anup Patel (2025-07-28 02:19:23)
> On Sun, Jul 27, 2025 at 11:53 AM Stephen Boyd <sboyd@kernel.org> wrote:
> >
> > It's not providing clks? The SBI firmware is not discoverable? Do you
> > have a pointer to the DTS for this node and the clock controller node in
> > the next patch? I'd like to understand why this is named a clock
> > controller when it doesn't provide clks.
> 
> The firmware driver is not providing clks. Also, the SBI firmware and
> various SBI extensions are indeed discoverable from supervisor software.

If SBI extensions are discoverable from software why do we need a DT
binding?

On Thu, Jul 31, 2025 at 10:20 PM Stephen Boyd <sboyd@kernel.org> wrote:
>
> Quoting Anup Patel (2025-07-28 02:19:23)
> > On Sun, Jul 27, 2025 at 11:53 AM Stephen Boyd <sboyd@kernel.org> wrote:
> > >
> > > It's not providing clks? The SBI firmware is not discoverable? Do you
> > > have a pointer to the DTS for this node and the clock controller node in
> > > the next patch? I'd like to understand why this is named a clock
> > > controller when it doesn't provide clks.
> >
> > The firmware driver is not providing clks. Also, the SBI firmware and
> > various SBI extensions are indeed discoverable from supervisor software.
>
> If SBI extensions are discoverable from software why do we need a DT
> binding?

The firmware which implements the SBI MPXY channel needs to
discover the underlying RPMI service group from DT.

Let's say we have only one RPMI shared memory transport between
application processors and platform microcontroller. This RPMI transport
will be shared between M-mode firmware (OpenSBI) and S-mode (Linux).

The OpenSBI will use the following example DT nodes to probe the
mailbox driver and MPXY driver to expose MPXY channel to S-mode.

mb: mailbox@10080000 {
    compatible = "riscv,rpmi-shmem-mbox";
    reg = <0x00 0x10080000 0x00 0x10000>,
         <0x00 0x10090000 0x00 0x10000>,
         <0x00 0x100a0000 0x00 0x10000>;
    reg-names = "a2p-req", "p2a-ack", "a2p-doorbell";
    #mbox-cells = <0x01>;
    riscv,slot-size = <0x40>;
    riscv,p2a-doorbell-sysmsi-index = <3>;
};

clock-service {
    compatible = "riscv,rpmi-mpxy-clock";
    mboxes = <&mb 0x08>;
    riscv,sbi-mpxy-channel-id = <0x1001>;
};

Based on the above, Linux will use the following example DT nodes
to probe the Linux MPXY mailbox driver and RPMI clock driver.

mpxy_mbox: sbi-mpxy-mbox {
    compatible = "riscv,sbi-mpxy-mbox";
    #mbox-cells = <2>;
    msi-parent = <&imsic_slevel>;
};

rpmi-clk {
    compatible = "riscv,rpmi-clock";
    #clock-cells = <1>;
    mboxes = <&mpxy_mbox 0x1001 0x0>;
};

I hope the above example DT node provides a better picture
about how DT bindings are used in firmware and Linux.

Regards,
Anup