Hi,
This series adds support for the new ARM Message Handling Unit v3 mailbox
controller [1].
The ARM MHUv3 can optionally support various extensions, enabling the
usage of different transport protocols.
Patch [2/2] adds a platform driver which, as of now, provides support only
for the Doorbell extension using the combined interrupt.
On the other side, bindings in [1/2] are introduced for all the extensions
described by the specification, as long as they are of interest to an
entity running from Normal world, like Linux: as such, Doorbell, FIFO and
FastChannel extensions are documented.
In these regards, note that the ARM MHUv3 controller can optionally
implement a considerable number of interrupts to express a great deal of
events and many of such interrupts are defined as being per-channel: with
the total maximum amount of possibly implemented channels across all
extensions being 1216 (1024+128+64), it would mean *a lot* of
interrupt-names to enumerate in the bindings.
So, since, I could not find a proper yaml/DT way to just define and verify
interrupt-names as:
my_interrupt-<N> with <N> in [0, N] range
the binding as of now only introduces interrupt-names for a mere 4-channels
in the range (0,3) for each per-channel interrupt type: the idea is to
leave open the possibility to add more to this list of numbered items only
when (and if) new real HW appears that effectively needs more than four
channels. (like AMBA, where the maximum number of IRQ was progressively
increased when needed, AFAIU); any suggestion on how to better express
this, is very much welcome.
Based on v6.9-rc1, tested on ARM TCS23 [2]
(TCS23 reference SW stack is still to be made fully publicly available)
Thanks,
Cristian
[1]: https://developer.arm.com/documentation/aes0072/aa/?lang=en
[2]: https://community.arm.com/arm-community-blogs/b/tools-software-ides-blog/posts/total-compute-solutions-platform-software-stack-and-fvp
Cristian Marussi (2):
dt-bindings: mailbox: arm,mhuv3: Add bindings
mailbox: arm_mhuv3: Add driver
.../bindings/mailbox/arm,mhuv3.yaml | 239 ++++
MAINTAINERS | 9 +
drivers/mailbox/Kconfig | 11 +
drivers/mailbox/Makefile | 2 +
drivers/mailbox/arm_mhuv3.c | 1061 +++++++++++++++++
5 files changed, 1322 insertions(+)
create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
create mode 100644 drivers/mailbox/arm_mhuv3.c
--
2.34.1
Add bindings for the ARM MHUv3 Mailbox controller.
Signed-off-by: Cristian Marussi <[email protected]>
---
.../bindings/mailbox/arm,mhuv3.yaml | 239 ++++++++++++++++++
1 file changed, 239 insertions(+)
create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
new file mode 100644
index 000000000000..bfb8ec341d26
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
@@ -0,0 +1,239 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM MHUv3 Mailbox Controller
+
+maintainers:
+ - Sudeep Holla <[email protected]>
+ - Cristian Marussi <[email protected]>
+
+description: |
+ The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that
+ enables unidirectional communications with remote processors through various
+ possible transport protocols.
+ The controller can optionally support a varying number of extensions that, in
+ turn, enable different kinds of transport to be used for communication.
+ Number, type and characteristics of each supported extension can be discovered
+ dynamically at runtime.
+
+ Given the unidirectional nature of the controller, an MHUv3 mailbox controller
+ is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU
+ Receiver (MHUR) containing a MailBox (MBX) block, where
+
+ PBX is used to
+ - Configure the MHU
+ - Send Transfers to the Receiver
+ - Optionally receive acknowledgment of a Transfer from the Receiver
+
+ MBX is used to
+ - Configure the MHU
+ - Receive Transfers from the Sender
+ - Optionally acknowledge Transfers sent by the Sender
+
+ Both PBX and MBX need to be present and defined in the DT description if you
+ need to establish a bidirectional communication, since you will have to
+ acquire two distinct unidirectional channels, one for each block.
+
+ As a consequence both blocks needs to be represented separately and specified
+ as distinct DT nodes in order to properly describe their resources.
+
+ Note that, though, thanks to the runtime discoverability, there is no need to
+ identify the type of blocks with distinct compatibles.
+
+ Following are the MHUv3 possible extensions.
+
+ - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell
+ Channel (DBCH). DBCH enables a single bit Transfer to be sent from the
+ Sender to Receiver. The Transfer indicates that an event has occurred.
+ When DBE is implemented, the number of DBCHs implemented is between 1 and
+ 128, numbered starting from 0 in ascending order.
+ Each DBCH contains 32 individual fields, referred to as flags, each of which
+ can be used independently. It is possible for the Sender to send multiple
+ Transfers at once using a single DBCH, so long as each Transfer uses
+ a different flag in the DBCH.
+ Optionally, data may be transmitted through an out-of-band shared memory
+ region, wherein the MHU Doorbell is used strictly as an interrupt generation
+ mechanism, but this is out of the scope of these bindings.
+
+ - FastChannel Extension (FCE): FCE defines a type of channel called a Fast
+ Channel (FCH). FCH is intended for lower overhead communication between
+ Sender and Receiver at the expense of determinism. An FCH allows the Sender
+ to update the channel value at any time, regardless of whether the previous
+ value has been seen by the Receiver. When the Receiver reads the channel's
+ content it gets the last value written to the channel.
+ FCH is considered lossy in nature, and means that the Sender has no way of
+ knowing if, or when, the Receiver will act on the Transfer.
+ FCHs are expected to behave as RAM which generates interrupts when writes
+ occur to the locations within the RAM.
+ When FCE is implemented, the number of FCH that an implementation of the MHU
+ can support is between 1-1024, if the Fast Channel word-size is 32-bits, or
+ between 1-512, when the Fast Channel word-size is 64-bits.
+ FCHs are numbered from 0 in ascending order.
+ Note that Fast Channel word-size is implementation defined, not configurable
+ but discoverable at run-time.
+ Optionally, data may be transmitted through an out-of-band shared memory
+ region, wherein the MHU FastChannel is used as an interrupt generation
+ mechanism which carries also a pointer to such out-of-band data, but this
+ is out of the scope of these bindings.
+
+ - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH).
+ FFCH allows a Sender to send
+ - Multiple Transfer to the Receiver without having to wait for a previous
+ Transfer to be acknowledged by the Receiver, as long as the FIFO has
+ room for the Transfer.
+ - Transfers which require the Receiver to provide acknowledgment.
+ - Transfers which have in-band payload.
+ In all cases, the data is guaranteed to be observed by the Receiver in the
+ same order which the Sender sent it.
+ When FE is implemented, the number of FFCH an implementation of the MHU can
+ support is between 1 and 64, numbered starting from the 0 in ascending
+ order. The FIFO size is implementation defined and not configurable.
+ Optionally, additional data may be transmitted through an out-of-band shared
+ memory region, wherein the MHU FIFO is used to transmit, in order, a small
+ part of the payload (like a header) and a reference to the shared memory
+ area holding the remaining, bigger, chunk of the payload, but this is out of
+ the scope of these bindings.
+
+properties:
+ compatible:
+ const: arm,mhuv3
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ minItems: 1
+ maxItems: 38
+
+ interrupt-names:
+ description: |
+ The MHUv3 controller generates a number of events some of which are used
+ to generate interrupts; as a consequence it can expose a varying number of
+ optional PBX/MBX interrupts, representing the events generated during the
+ operation of the various transport protocols associated with different
+ extensions. All interrupts of the MHU are level-sensitive.
+ Some of these optional interrupts are defined per-channel, where the
+ number of channels effectively available is implementation defined and
+ run-time discoverable.
+ In the following, for sake of simplicity, only a limited number of
+ per-channel interrupt names are enumerated, out of all the possible
+ channels allowed by the specification for each extension type.
+
+ - "combined": PBX/MBX Combined interrupt
+ - "combined-ffch": PBX/MBX FIFO Combined interrupt
+ - "ffch-low-tide-<N>": PBX/MBX FIFO Channel <N> Low Tide interrupt
+ - "ffch-high-tide-<N>": PBX/MBX FIFO Channel <N> High Tide interrupt
+ - "ffch-flush-<N>": PBX/MBX FIFO Channel <N> Flush interrupt
+ - "mbx-dbch-xfer-<N>": MBX Doorbell Channel <N> Transfer interrupt
+ - "mbx-fch-xfer-<N>": MBX Fast Channel <N> Transfer interrupt
+ - "mbx-fchgrp-xfer-<N>": MBX Fast Channel <N> Group Transfer interrupt
+ - "mbx-ffch-xfer-<N>": MBX FIFO Channel <N> Transfer interrupt
+ - "pbx-dbch-xfer-ack-<N>": PBX Doorbell Channel <N> Transfer Ack interrupt
+ - "pbx-ffch-xfer-ack-<N>": PBX FIFO Channel <N> Transfer Ack interrupt
+
+ The only mandatory interrupts on the MHU are:
+ - combined
+ - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented.
+
+ minItems: 1
+ maxItems: 38
+ items:
+ enum:
+ - combined
+ - combined-ffch
+ - ffch-low-tide-0
+ - ffch-low-tide-1
+ - ffch-low-tide-2
+ - ffch-low-tide-3
+ - ffch-high-tide-0
+ - ffch-high-tide-1
+ - ffch-high-tide-2
+ - ffch-high-tide-3
+ - ffch-flush-0
+ - ffch-flush-1
+ - ffch-flush-2
+ - ffch-flush-3
+ - mbx-dbch-xfer-0
+ - mbx-dbch-xfer-1
+ - mbx-dbch-xfer-2
+ - mbx-dbch-xfer-3
+ - mbx-fch-xfer-0
+ - mbx-fch-xfer-1
+ - mbx-fch-xfer-2
+ - mbx-fch-xfer-3
+ - mbx-fchgrp-xfer-0
+ - mbx-fchgrp-xfer-1
+ - mbx-fchgrp-xfer-2
+ - mbx-fchgrp-xfer-3
+ - mbx-ffch-xfer-0
+ - mbx-ffch-xfer-1
+ - mbx-ffch-xfer-2
+ - mbx-ffch-xfer-3
+ - pbx-dbch-xfer-ack-0
+ - pbx-dbch-xfer-ack-1
+ - pbx-dbch-xfer-ack-2
+ - pbx-dbch-xfer-ack-3
+ - pbx-ffch-xfer-ack-0
+ - pbx-ffch-xfer-ack-1
+ - pbx-ffch-xfer-ack-2
+ - pbx-ffch-xfer-ack-3
+
+ '#mbox-cells':
+ description: |
+ The first argument in the consumers 'mboxes' property represents the
+ extension type, the second is for the channel number while the third
+ depends on extension type.
+
+ Extension type for DBE is 0 and the third parameter represents the
+ doorbell flag number to use.
+ Extension type for FCE is 1, third parameter unused.
+ Extension type for FE is 2, third parameter unused.
+
+ mboxes = <&mhu 0 0 5>; // DBE, Doorbell Channel Window 0, doorbell flag 5.
+ mboxes = <&mhu 0 1 7>; // DBE, Doorbell Channel Window 1, doorbell flag 7.
+ mboxes = <&mhu 1 0 0>; // FCE, Fast Channel Window 0.
+ mboxes = <&mhu 1 3 0>; // FCE, Fast Channel Window 3.
+ mboxes = <&mhu 2 1 0>; // FE, FIFO Channel Window 1.
+ mboxes = <&mhu 2 7 0>; // FE, FIFO Channel Window 7.
+ const: 3
+
+ clocks:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+ - interrupt-names
+ - '#mbox-cells'
+
+additionalProperties: false
+
+examples:
+ - |
+ soc {
+ #address-cells = <2>;
+ #size-cells = <2>;
+
+ mhu_tx: mailbox@2aaa0000 {
+ compatible = "arm,mhuv3";
+ #mbox-cells = <3>;
+ reg = <0 0x2aaa0000 0 0x10000>;
+ clocks = <&clock 0>;
+ interrupt-names = "combined", "pbx-dbch-xfer-ack-1",
+ "ffch-high-tide-0";
+ interrupts = <0 36 4>, <0 37 4>;
+ };
+
+ mhu_rx: mailbox@2ab00000 {
+ compatible = "arm,mhuv3";
+ #mbox-cells = <3>;
+ reg = <0 0x2aab0000 0 0x10000>;
+ clocks = <&clock 0>;
+ interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0";
+ interrupts = <0 35 4>, <0 38 4>, <0 39 4>;
+ };
+ };
--
2.34.1
On Mon, Mar 25, 2024 at 4:28 AM Cristian Marussi
<[email protected]> wrote:
>
> Add bindings for the ARM MHUv3 Mailbox controller.
>
> Signed-off-by: Cristian Marussi <[email protected]>
> ---
> .../bindings/mailbox/arm,mhuv3.yaml | 239 ++++++++++++++++++
> 1 file changed, 239 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
>
> diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
> new file mode 100644
> index 000000000000..bfb8ec341d26
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
> @@ -0,0 +1,239 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: ARM MHUv3 Mailbox Controller
> +
> +maintainers:
> + - Sudeep Holla <[email protected]>
> + - Cristian Marussi <[email protected]>
> +
> +description: |
> + The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that
> + enables unidirectional communications with remote processors through various
> + possible transport protocols.
> + The controller can optionally support a varying number of extensions that, in
> + turn, enable different kinds of transport to be used for communication.
> + Number, type and characteristics of each supported extension can be discovered
> + dynamically at runtime.
> +
> + Given the unidirectional nature of the controller, an MHUv3 mailbox controller
> + is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU
> + Receiver (MHUR) containing a MailBox (MBX) block, where
> +
> + PBX is used to
> + - Configure the MHU
> + - Send Transfers to the Receiver
> + - Optionally receive acknowledgment of a Transfer from the Receiver
> +
> + MBX is used to
> + - Configure the MHU
> + - Receive Transfers from the Sender
> + - Optionally acknowledge Transfers sent by the Sender
> +
> + Both PBX and MBX need to be present and defined in the DT description if you
> + need to establish a bidirectional communication, since you will have to
> + acquire two distinct unidirectional channels, one for each block.
> +
> + As a consequence both blocks needs to be represented separately and specified
> + as distinct DT nodes in order to properly describe their resources.
> +
> + Note that, though, thanks to the runtime discoverability, there is no need to
> + identify the type of blocks with distinct compatibles.
> +
> + Following are the MHUv3 possible extensions.
> +
> + - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell
> + Channel (DBCH). DBCH enables a single bit Transfer to be sent from the
> + Sender to Receiver. The Transfer indicates that an event has occurred.
> + When DBE is implemented, the number of DBCHs implemented is between 1 and
> + 128, numbered starting from 0 in ascending order.
> + Each DBCH contains 32 individual fields, referred to as flags, each of which
> + can be used independently. It is possible for the Sender to send multiple
> + Transfers at once using a single DBCH, so long as each Transfer uses
> + a different flag in the DBCH.
> + Optionally, data may be transmitted through an out-of-band shared memory
> + region, wherein the MHU Doorbell is used strictly as an interrupt generation
> + mechanism, but this is out of the scope of these bindings.
> +
> + - FastChannel Extension (FCE): FCE defines a type of channel called a Fast
> + Channel (FCH). FCH is intended for lower overhead communication between
> + Sender and Receiver at the expense of determinism. An FCH allows the Sender
> + to update the channel value at any time, regardless of whether the previous
> + value has been seen by the Receiver. When the Receiver reads the channel's
> + content it gets the last value written to the channel.
> + FCH is considered lossy in nature, and means that the Sender has no way of
> + knowing if, or when, the Receiver will act on the Transfer.
> + FCHs are expected to behave as RAM which generates interrupts when writes
> + occur to the locations within the RAM.
> + When FCE is implemented, the number of FCH that an implementation of the MHU
> + can support is between 1-1024, if the Fast Channel word-size is 32-bits, or
> + between 1-512, when the Fast Channel word-size is 64-bits.
Be consistent: FastChannel
> + FCHs are numbered from 0 in ascending order.
> + Note that Fast Channel word-size is implementation defined, not configurable
> + but discoverable at run-time.
> + Optionally, data may be transmitted through an out-of-band shared memory
> + region, wherein the MHU FastChannel is used as an interrupt generation
> + mechanism which carries also a pointer to such out-of-band data, but this
> + is out of the scope of these bindings.
> +
> + - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH).
> + FFCH allows a Sender to send
> + - Multiple Transfer to the Receiver without having to wait for a previous
> + Transfer to be acknowledged by the Receiver, as long as the FIFO has
> + room for the Transfer.
> + - Transfers which require the Receiver to provide acknowledgment.
> + - Transfers which have in-band payload.
> + In all cases, the data is guaranteed to be observed by the Receiver in the
> + same order which the Sender sent it.
> + When FE is implemented, the number of FFCH an implementation of the MHU can
> + support is between 1 and 64, numbered starting from the 0 in ascending
> + order. The FIFO size is implementation defined and not configurable.
Size is discoverable or opaque to s/w?
> + Optionally, additional data may be transmitted through an out-of-band shared
> + memory region, wherein the MHU FIFO is used to transmit, in order, a small
> + part of the payload (like a header) and a reference to the shared memory
> + area holding the remaining, bigger, chunk of the payload, but this is out of
> + the scope of these bindings.
> +
> +properties:
> + compatible:
> + const: arm,mhuv3
> +
> + reg:
> + maxItems: 1
> +
> + interrupts:
> + minItems: 1
> + maxItems: 38
> +
> + interrupt-names:
> + description: |
> + The MHUv3 controller generates a number of events some of which are used
> + to generate interrupts; as a consequence it can expose a varying number of
> + optional PBX/MBX interrupts, representing the events generated during the
> + operation of the various transport protocols associated with different
> + extensions. All interrupts of the MHU are level-sensitive.
> + Some of these optional interrupts are defined per-channel, where the
> + number of channels effectively available is implementation defined and
> + run-time discoverable.
> + In the following, for sake of simplicity, only a limited number of
> + per-channel interrupt names are enumerated, out of all the possible
> + channels allowed by the specification for each extension type.
> +
> + - "combined": PBX/MBX Combined interrupt
> + - "combined-ffch": PBX/MBX FIFO Combined interrupt
> + - "ffch-low-tide-<N>": PBX/MBX FIFO Channel <N> Low Tide interrupt
> + - "ffch-high-tide-<N>": PBX/MBX FIFO Channel <N> High Tide interrupt
> + - "ffch-flush-<N>": PBX/MBX FIFO Channel <N> Flush interrupt
> + - "mbx-dbch-xfer-<N>": MBX Doorbell Channel <N> Transfer interrupt
> + - "mbx-fch-xfer-<N>": MBX Fast Channel <N> Transfer interrupt
> + - "mbx-fchgrp-xfer-<N>": MBX Fast Channel <N> Group Transfer interrupt
> + - "mbx-ffch-xfer-<N>": MBX FIFO Channel <N> Transfer interrupt
> + - "pbx-dbch-xfer-ack-<N>": PBX Doorbell Channel <N> Transfer Ack interrupt
> + - "pbx-ffch-xfer-ack-<N>": PBX FIFO Channel <N> Transfer Ack interrupt
It would be better to not define these strings twice. You can do
something like this:
items:
oneOf:
- const: combined
description: ...
- pattern: '^ffch-low-tide-[0-9]+$'
description: ...
And so on.
> +
> + The only mandatory interrupts on the MHU are:
> + - combined
> + - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented.
> +
> + minItems: 1
> + maxItems: 38
Perhaps a comment on where 38 comes from. AIUI, this is a "should be
enough for now" value.
> + items:
> + enum:
> + - combined
> + - combined-ffch
> + - ffch-low-tide-0
> + - ffch-low-tide-1
> + - ffch-low-tide-2
> + - ffch-low-tide-3
> + - ffch-high-tide-0
> + - ffch-high-tide-1
> + - ffch-high-tide-2
> + - ffch-high-tide-3
> + - ffch-flush-0
> + - ffch-flush-1
> + - ffch-flush-2
> + - ffch-flush-3
> + - mbx-dbch-xfer-0
> + - mbx-dbch-xfer-1
> + - mbx-dbch-xfer-2
> + - mbx-dbch-xfer-3
> + - mbx-fch-xfer-0
> + - mbx-fch-xfer-1
> + - mbx-fch-xfer-2
> + - mbx-fch-xfer-3
> + - mbx-fchgrp-xfer-0
> + - mbx-fchgrp-xfer-1
> + - mbx-fchgrp-xfer-2
> + - mbx-fchgrp-xfer-3
> + - mbx-ffch-xfer-0
> + - mbx-ffch-xfer-1
> + - mbx-ffch-xfer-2
> + - mbx-ffch-xfer-3
> + - pbx-dbch-xfer-ack-0
> + - pbx-dbch-xfer-ack-1
> + - pbx-dbch-xfer-ack-2
> + - pbx-dbch-xfer-ack-3
> + - pbx-ffch-xfer-ack-0
> + - pbx-ffch-xfer-ack-1
> + - pbx-ffch-xfer-ack-2
> + - pbx-ffch-xfer-ack-3
> +
> + '#mbox-cells':
> + description: |
> + The first argument in the consumers 'mboxes' property represents the
> + extension type, the second is for the channel number while the third
> + depends on extension type.
> +
> + Extension type for DBE is 0 and the third parameter represents the
> + doorbell flag number to use.
> + Extension type for FCE is 1, third parameter unused.
> + Extension type for FE is 2, third parameter unused.
> +
> + mboxes = <&mhu 0 0 5>; // DBE, Doorbell Channel Window 0, doorbell flag 5.
> + mboxes = <&mhu 0 1 7>; // DBE, Doorbell Channel Window 1, doorbell flag 7.
> + mboxes = <&mhu 1 0 0>; // FCE, Fast Channel Window 0.
> + mboxes = <&mhu 1 3 0>; // FCE, Fast Channel Window 3.
> + mboxes = <&mhu 2 1 0>; // FE, FIFO Channel Window 1.
> + mboxes = <&mhu 2 7 0>; // FE, FIFO Channel Window 7.
> + const: 3
> +
> + clocks:
> + maxItems: 1
> +
> +required:
> + - compatible
> + - reg
> + - interrupts
> + - interrupt-names
> + - '#mbox-cells'
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + soc {
> + #address-cells = <2>;
> + #size-cells = <2>;
> +
> + mhu_tx: mailbox@2aaa0000 {
Drop unused labels.
> + compatible = "arm,mhuv3";
> + #mbox-cells = <3>;
> + reg = <0 0x2aaa0000 0 0x10000>;
> + clocks = <&clock 0>;
> + interrupt-names = "combined", "pbx-dbch-xfer-ack-1",
> + "ffch-high-tide-0";
> + interrupts = <0 36 4>, <0 37 4>;
> + };
> +
> + mhu_rx: mailbox@2ab00000 {
> + compatible = "arm,mhuv3";
> + #mbox-cells = <3>;
> + reg = <0 0x2aab0000 0 0x10000>;
> + clocks = <&clock 0>;
> + interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0";
> + interrupts = <0 35 4>, <0 38 4>, <0 39 4>;
> + };
> + };
> --
> 2.34.1
>
On Mon, Mar 25, 2024 at 08:44:24AM -0500, Rob Herring wrote:
> On Mon, Mar 25, 2024 at 4:28 AM Cristian Marussi
> <[email protected]> wrote:
> >
> > Add bindings for the ARM MHUv3 Mailbox controller.
> >
Hi Rob,
thanks for having a look.
> > Signed-off-by: Cristian Marussi <[email protected]>
> > ---
> > .../bindings/mailbox/arm,mhuv3.yaml | 239 ++++++++++++++++++
> > 1 file changed, 239 insertions(+)
> > create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
> > new file mode 100644
> > index 000000000000..bfb8ec341d26
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
> > @@ -0,0 +1,239 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: ARM MHUv3 Mailbox Controller
> > +
> > +maintainers:
> > + - Sudeep Holla <[email protected]>
> > + - Cristian Marussi <[email protected]>
> > +
> > +description: |
> > + The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that
> > + enables unidirectional communications with remote processors through various
> > + possible transport protocols.
> > + The controller can optionally support a varying number of extensions that, in
> > + turn, enable different kinds of transport to be used for communication.
> > + Number, type and characteristics of each supported extension can be discovered
> > + dynamically at runtime.
> > +
> > + Given the unidirectional nature of the controller, an MHUv3 mailbox controller
> > + is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU
> > + Receiver (MHUR) containing a MailBox (MBX) block, where
> > +
> > + PBX is used to
> > + - Configure the MHU
> > + - Send Transfers to the Receiver
> > + - Optionally receive acknowledgment of a Transfer from the Receiver
> > +
> > + MBX is used to
> > + - Configure the MHU
> > + - Receive Transfers from the Sender
> > + - Optionally acknowledge Transfers sent by the Sender
> > +
> > + Both PBX and MBX need to be present and defined in the DT description if you
> > + need to establish a bidirectional communication, since you will have to
> > + acquire two distinct unidirectional channels, one for each block.
> > +
> > + As a consequence both blocks needs to be represented separately and specified
> > + as distinct DT nodes in order to properly describe their resources.
> > +
> > + Note that, though, thanks to the runtime discoverability, there is no need to
> > + identify the type of blocks with distinct compatibles.
> > +
> > + Following are the MHUv3 possible extensions.
> > +
> > + - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell
> > + Channel (DBCH). DBCH enables a single bit Transfer to be sent from the
> > + Sender to Receiver. The Transfer indicates that an event has occurred.
> > + When DBE is implemented, the number of DBCHs implemented is between 1 and
> > + 128, numbered starting from 0 in ascending order.
> > + Each DBCH contains 32 individual fields, referred to as flags, each of which
> > + can be used independently. It is possible for the Sender to send multiple
> > + Transfers at once using a single DBCH, so long as each Transfer uses
> > + a different flag in the DBCH.
> > + Optionally, data may be transmitted through an out-of-band shared memory
> > + region, wherein the MHU Doorbell is used strictly as an interrupt generation
> > + mechanism, but this is out of the scope of these bindings.
> > +
> > + - FastChannel Extension (FCE): FCE defines a type of channel called a Fast
> > + Channel (FCH). FCH is intended for lower overhead communication between
> > + Sender and Receiver at the expense of determinism. An FCH allows the Sender
> > + to update the channel value at any time, regardless of whether the previous
> > + value has been seen by the Receiver. When the Receiver reads the channel's
> > + content it gets the last value written to the channel.
> > + FCH is considered lossy in nature, and means that the Sender has no way of
> > + knowing if, or when, the Receiver will act on the Transfer.
> > + FCHs are expected to behave as RAM which generates interrupts when writes
> > + occur to the locations within the RAM.
> > + When FCE is implemented, the number of FCH that an implementation of the MHU
> > + can support is between 1-1024, if the Fast Channel word-size is 32-bits, or
> > + between 1-512, when the Fast Channel word-size is 64-bits.
>
> Be consistent: FastChannel
>
I'll fix.
> > + FCHs are numbered from 0 in ascending order.
> > + Note that Fast Channel word-size is implementation defined, not configurable
> > + but discoverable at run-time.
> > + Optionally, data may be transmitted through an out-of-band shared memory
> > + region, wherein the MHU FastChannel is used as an interrupt generation
> > + mechanism which carries also a pointer to such out-of-band data, but this
> > + is out of the scope of these bindings.
> > +
> > + - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH).
> > + FFCH allows a Sender to send
> > + - Multiple Transfer to the Receiver without having to wait for a previous
> > + Transfer to be acknowledged by the Receiver, as long as the FIFO has
> > + room for the Transfer.
> > + - Transfers which require the Receiver to provide acknowledgment.
> > + - Transfers which have in-band payload.
> > + In all cases, the data is guaranteed to be observed by the Receiver in the
> > + same order which the Sender sent it.
> > + When FE is implemented, the number of FFCH an implementation of the MHU can
> > + support is between 1 and 64, numbered starting from the 0 in ascending
> > + order. The FIFO size is implementation defined and not configurable.
>
> Size is discoverable or opaque to s/w?
>
FIFOs depth is the same across all of the implemented FIFO channels (between 1 and
1024 bytes) AND it is actually discoverable at runtime...I forgot to mention that here,
I'll fix.
> > + Optionally, additional data may be transmitted through an out-of-band shared
> > + memory region, wherein the MHU FIFO is used to transmit, in order, a small
> > + part of the payload (like a header) and a reference to the shared memory
> > + area holding the remaining, bigger, chunk of the payload, but this is out of
> > + the scope of these bindings.
> > +
> > +properties:
> > + compatible:
> > + const: arm,mhuv3
> > +
> > + reg:
> > + maxItems: 1
> > +
> > + interrupts:
> > + minItems: 1
> > + maxItems: 38
> > +
> > + interrupt-names:
> > + description: |
> > + The MHUv3 controller generates a number of events some of which are used
> > + to generate interrupts; as a consequence it can expose a varying number of
> > + optional PBX/MBX interrupts, representing the events generated during the
> > + operation of the various transport protocols associated with different
> > + extensions. All interrupts of the MHU are level-sensitive.
> > + Some of these optional interrupts are defined per-channel, where the
> > + number of channels effectively available is implementation defined and
> > + run-time discoverable.
> > + In the following, for sake of simplicity, only a limited number of
> > + per-channel interrupt names are enumerated, out of all the possible
> > + channels allowed by the specification for each extension type.
> > +
> > + - "combined": PBX/MBX Combined interrupt
> > + - "combined-ffch": PBX/MBX FIFO Combined interrupt
> > + - "ffch-low-tide-<N>": PBX/MBX FIFO Channel <N> Low Tide interrupt
> > + - "ffch-high-tide-<N>": PBX/MBX FIFO Channel <N> High Tide interrupt
> > + - "ffch-flush-<N>": PBX/MBX FIFO Channel <N> Flush interrupt
> > + - "mbx-dbch-xfer-<N>": MBX Doorbell Channel <N> Transfer interrupt
> > + - "mbx-fch-xfer-<N>": MBX Fast Channel <N> Transfer interrupt
> > + - "mbx-fchgrp-xfer-<N>": MBX Fast Channel <N> Group Transfer interrupt
> > + - "mbx-ffch-xfer-<N>": MBX FIFO Channel <N> Transfer interrupt
> > + - "pbx-dbch-xfer-ack-<N>": PBX Doorbell Channel <N> Transfer Ack interrupt
> > + - "pbx-ffch-xfer-ack-<N>": PBX FIFO Channel <N> Transfer Ack interrupt
>
> It would be better to not define these strings twice. You can do
> something like this:
>
> items:
> oneOf:
> - const: combined
> description: ...
> - pattern: '^ffch-low-tide-[0-9]+$'
> description: ...
>
> And so on.
>
Thanks, I'll give it a go.
> > +
> > + The only mandatory interrupts on the MHU are:
> > + - combined
> > + - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented.
> > +
> > + minItems: 1
> > + maxItems: 38
>
> Perhaps a comment on where 38 comes from. AIUI, this is a "should be
> enough for now" value.
>
Yes, I'll add and explanation to justify this.
> > + items:
> > + enum:
> > + - combined
> > + - combined-ffch
> > + - ffch-low-tide-0
> > + - ffch-low-tide-1
> > + - ffch-low-tide-2
> > + - ffch-low-tide-3
> > + - ffch-high-tide-0
> > + - ffch-high-tide-1
> > + - ffch-high-tide-2
> > + - ffch-high-tide-3
> > + - ffch-flush-0
> > + - ffch-flush-1
> > + - ffch-flush-2
> > + - ffch-flush-3
> > + - mbx-dbch-xfer-0
> > + - mbx-dbch-xfer-1
> > + - mbx-dbch-xfer-2
> > + - mbx-dbch-xfer-3
> > + - mbx-fch-xfer-0
> > + - mbx-fch-xfer-1
> > + - mbx-fch-xfer-2
> > + - mbx-fch-xfer-3
> > + - mbx-fchgrp-xfer-0
> > + - mbx-fchgrp-xfer-1
> > + - mbx-fchgrp-xfer-2
> > + - mbx-fchgrp-xfer-3
> > + - mbx-ffch-xfer-0
> > + - mbx-ffch-xfer-1
> > + - mbx-ffch-xfer-2
> > + - mbx-ffch-xfer-3
> > + - pbx-dbch-xfer-ack-0
> > + - pbx-dbch-xfer-ack-1
> > + - pbx-dbch-xfer-ack-2
> > + - pbx-dbch-xfer-ack-3
> > + - pbx-ffch-xfer-ack-0
> > + - pbx-ffch-xfer-ack-1
> > + - pbx-ffch-xfer-ack-2
> > + - pbx-ffch-xfer-ack-3
> > +
> > + '#mbox-cells':
> > + description: |
> > + The first argument in the consumers 'mboxes' property represents the
> > + extension type, the second is for the channel number while the third
> > + depends on extension type.
> > +
> > + Extension type for DBE is 0 and the third parameter represents the
> > + doorbell flag number to use.
> > + Extension type for FCE is 1, third parameter unused.
> > + Extension type for FE is 2, third parameter unused.
> > +
> > + mboxes = <&mhu 0 0 5>; // DBE, Doorbell Channel Window 0, doorbell flag 5.
> > + mboxes = <&mhu 0 1 7>; // DBE, Doorbell Channel Window 1, doorbell flag 7.
> > + mboxes = <&mhu 1 0 0>; // FCE, Fast Channel Window 0.
> > + mboxes = <&mhu 1 3 0>; // FCE, Fast Channel Window 3.
> > + mboxes = <&mhu 2 1 0>; // FE, FIFO Channel Window 1.
> > + mboxes = <&mhu 2 7 0>; // FE, FIFO Channel Window 7.
> > + const: 3
> > +
> > + clocks:
> > + maxItems: 1
> > +
> > +required:
> > + - compatible
> > + - reg
> > + - interrupts
> > + - interrupt-names
> > + - '#mbox-cells'
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > + - |
> > + soc {
> > + #address-cells = <2>;
> > + #size-cells = <2>;
> > +
> > + mhu_tx: mailbox@2aaa0000 {
>
> Drop unused labels.
>
Ok.
Thanks,
Cristian