[RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings

[Viresh Kumar]

On 08-10-20, 09:30, Rob Herring wrote:
> On Wed, Oct 7, 2020 at 10:28 AM Viresh Kumar <viresh.kumar at linaro.org> wrote:
> > +  clock-names:
> > +    items:
> > +      - const: apb_pclk
> 
> Just 'maxItems: 1' is fine here as the name is already defined.
> 
> > +
> > +  arm-mhuv2-mode:
> 
> arm,mhuv2-mode.

This is what I did initially but was getting errors with it...

> Needs a type reference.

And this fixed it.

> > +    description: |
> > +      The MHUv2 controller may contain up to 124 channel windows (each 32-bit
> > +      wide). The hardware and the DT bindings allows any combination of those to
> > +      be used for various transport protocols.
> > +
> > +      This property allows a platform to describe how these channel windows are
> > +      used in various transport protocols. The entries in this property shall be
> > +      present as an array of tuples, where each tuple describes details about
> > +      one of the transport protocol being implemented over some channel
> > +      window(s).
> > +
> > +      The first field of a tuple signifies the transfer protocol, 0 is reserved
> > +      for doorbell protocol, 1 is reserved for single-word protocol and 2 is
> > +      reserved for multi-word protocol. Using any other value in the first field
> > +      of a tuple makes it invalid.
> > +
> > +      The second field of a tuple signifies the number of channel windows where
> > +      the protocol would be used. For doorbell protocol this field signifies the
> > +      number of 32-bit channel windows that implement the doorbell protocol. For
> > +      single-word protocol this field signifies the number of 32-bit channel
> > +      windows that implement separate single-word protocol mailbox channels. For
> > +      multi-word protocol this field signifies the number of channel windows
> > +      used for a multi-word protocol, it should be 2 or more.
> 
> These are based on IP configuration or a software decision?

Software/firmware.

The platform only fixes the total number of 32-bit registers available
(channel windows) for use, how we use them is left to us. I tried to
make it as generic as possible so any combinations of protocols can be
used here.

> > +      The total number of channel windows specified here shouldn't be more than
> > +      the ones implemented by the platform.
> 
> But can be less? Then do you need this to be a mask or range?

Yes, we don't need to use all the windows that are available to us. I
am not sure why we would need a mask/range here.

Just to clarify a little, as it took me some time to come to this
understanding, the maximum number of channel windows (these aren't
necessarily mailbox channels) supported by the hardware is 124, i.e.
124 32-bit registers. Though a platform may implement only 8 of them,
for example and the OS may want to use only 4 of them.

If we use the entire thing in:

- multi-word mode, we can create a single mailbox channel which is
  capable of transferring 124 words in one go.

- single-word mode, we will end up having 124 mailbox channels, each
  32 bit wide.

- doorbell mode, we will end up having 124 * 32 mailbox channels.

-- 
viresh