Re: [PATCH 1/4] mailbox: arm_mhuv2: add device tree binding documentation

[Morten Borup Petersen]

On 8/7/19 1:17 PM, Tushar Khandelwal wrote:
> 
> 
> ïOn 02/08/2019, 11:59, "Sudeep Holla" <sudeep.holla@xxxxxxx> wrote:
> 
>     On Sun, Jul 21, 2019 at 04:58:04PM -0500, Jassi Brar wrote:
>     > On Wed, Jul 17, 2019 at 2:26 PM Tushar Khandelwal
>     > <tushar.khandelwal@xxxxxxx> wrote:
>     >
>     > > diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt
>     > > new file mode 100644
>     > > index 000000000000..3a05593414bc
>     > > --- /dev/null
>     > > +++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.txt
>     > > @@ -0,0 +1,108 @@
>     > > +Arm MHUv2 Mailbox Driver
>     > > +========================
>     > > +
>     > > +The Arm Message-Handling-Unit (MHU) Version 2 is a mailbox controller that has
>     > > +between 1 and 124 channel windows to provide unidirectional communication with
>     > > +remote processor(s).
>     > > +
>     > > +Given the unidirectional nature of the device, an MHUv2 mailbox may only be
>     > > +written to or read from. If a pair of MHU devices is implemented between two
>     > > +processing elements to provide bidirectional communication, these must be
>     > > +specified as two separate mailboxes.
>     > > +
>     > > +A device tree node for an Arm MHUv2 device must specify either a receiver frame
>     > > +or a sender frame, indicating which end of the unidirectional MHU device which
>     > > +the device node entry describes.
>     > > +
>     > > +An MHU device must be specified with a transport protocol. The transport
>     > > +protocol of an MHU device determines the method of data transmission as well as
>     > > +the number of provided mailboxes.
>     > > +Following are the possible transport protocol types:
>     > > +- Single-word: An MHU device implements as many mailboxes as it
>     > > +               provides channel windows. Data is transmitted through
>     > > +               the MHU registers.
>     > > +- Multi-word:  An MHU device implements a single mailbox. All channel windows
>     > > +               will be used during transmission. Data is transmitted through
>     > > +               the MHU registers.
>     > > +- Doorbell:    An MHU device implements as many mailboxes as there are flag
>     > > +               bits available in its channel windows. Optionally, data may
>     > > +               be transmitted through a shared memory region, wherein the MHU
>     > > +               is used strictly as an interrupt generation mechanism.
>     > > +
>     > > +Mailbox Device Node:
>     > > +====================
>     > > +
>     > > +Required properties:
>     > > +--------------------
>     > > +- compatible:  Shall be "arm,mhuv2" & "arm,primecell"
>     > > +- reg:         Contains the mailbox register address range (base
>     > > +               address and length)
>     > > +- #mbox-cells  Shall be 1 - the index of the channel needed.
>     > > +- mhu-frame    Frame type of the device.
>     > > +               Shall be either "sender" or "receiver"
>     > > +- mhu-protocol Transport protocol of the device. Shall be one of the
>     > > +               following: "single-word", "multi-word", "doorbell"
>     > > +
>     > > +Required properties (receiver frame):
>     > > +-------------------------------------
>     > > +- interrupts:  Contains the interrupt information corresponding to the
>     > > +               combined interrupt of the receiver frame
>     > > +
>     > > +Example:
>     > > +--------
>     > > +
>     > > +       mbox_mw_tx: mhu@10000000 {
>     > > +               compatible = "arm,mhuv2","arm,primecell";
>     > > +               reg = <0x10000000 0x1000>;
>     > > +               clocks = <&refclk100mhz>;
>     > > +               clock-names = "apb_pclk";
>     > > +               #mbox-cells = <1>;
>     > > +               mhu-protocol = "multi-word";
>     > > +               mhu-frame = "sender";
>     > > +       };
>     > > +
>     > > +       mbox_sw_tx: mhu@10000000 {
>     > > +               compatible = "arm,mhuv2","arm,primecell";
>     > > +               reg = <0x11000000 0x1000>;
>     > > +               clocks = <&refclk100mhz>;
>     > > +               clock-names = "apb_pclk";
>     > > +               #mbox-cells = <1>;
>     > > +               mhu-protocol = "single-word";
>     > > +               mhu-frame = "sender";
>     > > +       };
>     > > +
>     > > +       mbox_db_rx: mhu@10000000 {
>     > > +               compatible = "arm,mhuv2","arm,primecell";
>     > > +               reg = <0x12000000 0x1000>;
>     > > +               clocks = <&refclk100mhz>;
>     > > +               clock-names = "apb_pclk";
>     > > +               #mbox-cells = <1>;
>     > > +               interrupts = <0 45 4>;
>     > > +               interrupt-names = "mhu_rx";
>     > > +               mhu-protocol = "doorbell";
>     > > +               mhu-frame = "receiver";
>     > > +       };
>     > > +
>     > > +       mhu_client: scb@2e000000 {
>     > > +       compatible = "fujitsu,mb86s70-scb-1.0";
>     > > +       reg = <0 0x2e000000 0x4000>;
>     > > +       mboxes =
>     > > +               // For multi-word frames, client may only instantiate a single
>     > > +               // mailbox for a mailbox controller
>     > > +               <&mbox_mw_tx 0>,
>     > > +
>     > > +               // For single-word frames, client may instantiate as many
>     > > +               // mailboxes as there are channel windows in the MHU
>     > > +                <&mbox_sw_tx 0>,
>     > > +                <&mbox_sw_tx 1>,
>     > > +                <&mbox_sw_tx 2>,
>     > > +                <&mbox_sw_tx 3>,
>     > > +
>     > > +               // For doorbell frames, client may instantiate as many mailboxes
>     > > +               // as there are bits available in the combined number of channel
>     > > +               // windows ((channel windows * 32) mailboxes)
>     > > +                <mbox_db_rx 0>,
>     > > +                <mbox_db_rx 1>,
>     > > +                ...
>     > > +                <mbox_db_rx 17>;
>     > > +       };
>     >
>     > If the mhuv2 instance implements, say, 3 channel windows between
>     > sender (linux) and receiver (firmware), and Linux runs two protocols
>     > each requiring 1 and 2-word sized messages respectively. The hardware
>     > supports that by assigning windows [0] and [1,2] to each protocol.
>     > However, I don't think the driver can support that. Or does it?
>     >
> 
>     FWIW, the IP is designed to cover wide range of usecase from IoT to servers
>     with variable window length. I don't see the need to complicate the driver
>     supporting mix-n-match at the cost of latency. Each platform choose one
>     transport protocol for all it's use.
> 
> The driver design is to address the most probable scenarios and not all.
> Single-word : Client gets one 32-bit window
> Doorbell : Client gets 32 data pointers (arm_message)
> Multi-word: Client gets all channels available in the platform.
> 
> --Tushar
>

To elaborate for better understanding;
arm_message is used when a mailbox client is to transmit data through an
MHUv2 mailbox (ie. in-band transmission), wherein the MHUv2 is in a
single-word or multi-word protocol mode.
arm_message allows for a mailbox client to transmit data with arbitrary
length, without having to know the technicalities of underlying
transport protocol, number of MHU channels etc. As such, the mailbox
client driver code may remain unchanged, if the underlying transport
protocol is changed from ie. single-word to multi-word, or if more
channel-windows are added to an MHUv2 device in multi-word mode.
Transmission of data as well as maximum utilization of the available
channel windows (in multi-word mode) is solely job for the MHUv2 driver.

Given the differences between using an MHUv2 mailbox in single- and
multi-word mode compared to doorbell mode, it is however expected that
mailbox client driver code must be changed if switching from single- or
multi-word to doorbell.
As per the MHUv2 spec, when in doorbell mode, it is expected that the
receiver and transmitter has decided beforehand both where data is
placed in shared memory, as well as the format of this data. Here we do
not require that arm_message is used, given that all data is transmitted
out-of-band, and the MHUv2 is only used as an interrupt generating
mechanism.

To give an example of how arm_message may be used;
Say, a client-driver protocol has been written as follows:

> struct {
>     int cmd;
>     int[4] args;
> } foo_t;

Now, a client driver may transmit this through a mailbox which has an
MHUv2 as the controller - we do not need to know the underlying
transport protocol, just that it has to be either single- or multi word.

> // Create user-specific protocol struct
> foo_t foo;
>
> /* Modify foo with the data to be transmitted... */
>
> /* Wrap message into arm_message format, so the MHUv2 driver knows how
> much data to send*/
>
> arm_message msg;
> msg.data = &foo;
> msg.len = sizeof(foo);
>
> /* Transmit the arm_message */
> mbox_send_message(mbox, &msg);
>

On the receiver side, there should be some accompanying logic in the
client driver which is aware of foo_t and from this may reconstruct the
received message. Reconstruction of a received message is a task for the
mailbox client driver.

- Morten