Re: [PATCH v2 1/2] dt-bindings: firmware: arm,scmi: Support mailboxes unidirectional channels

[Rob Herring <robh@kernel.org>]

On Mon, Mar 27, 2023 at 04:45:27PM +0100, Cristian Marussi wrote:
> SCMI defines two kinds of communication channels between the agent and the
> platform: one bidirectional 'a2p' channel used by the agent to send SCMI
> commands and synchronously receive the related replies, and an optional
> 'p2a' unidirectional channel used to asynchronously receive delayed
> responses and notifications emitted from the platform.
> 
> When configuring an SCMI transport based on mailboxes, the current binding
> supports only mailboxes providing bidirectional channels: in such a case
> one mailbox channel can be easily assigned to each SCMI channel as above
> described.
> 
> In case, instead, to have to deal with mailboxes providing only distinct
> unidirectional channels, it becomes necessary to extend the binding in
> order to be able to bind 2 distinct unidirectional mailbox channels to the
> same SCMI 'a2p' channel.
> 
> Bidirectional and unidirectional channels support for the SCMI mailbox
> transport can coexist by carefully considering the effective combination
> of defined 'mboxes' and 'shmem' descriptors.
> 
> Signed-off-by: Cristian Marussi <cristian.marussi@arm.com>
> ---
> v1 --> v2
> - added mbox-names unidirectional definitions and example
> ---
>  .../bindings/firmware/arm,scmi.yaml           | 76 ++++++++++++++++---
>  1 file changed, 66 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml
> index 2f7c51c75e85..0204b102b47f 100644
> --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml
> +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml
> @@ -56,17 +56,41 @@ properties:
>      description:
>        Specifies the mailboxes used to communicate with SCMI compliant
>        firmware.
> -    items:
> -      - const: tx
> -      - const: rx
> +    oneOf:
> +      - items:
> +          - const: tx
> +      - items:
> +          - const: tx
> +          - const: rx

These 2 'items' can be collapsed to 1 with 'minItems: 1' added.

> +      - items:
> +          - const: tx
> +          - const: tx_reply
> +      - items:
> +          - const: tx
> +          - const: tx_reply
> +          - const: rx

Same on these 2 with 'minItems: 2' added.

>  
>    mboxes:
>      description:
>        List of phandle and mailbox channel specifiers. It should contain
> -      exactly one or two mailboxes, one for transmitting messages("tx")
> -      and another optional for receiving the notifications("rx") if supported.
> +      exactly one, two or three mailboxes; the first one or two for transmitting
> +      messages ("tx") and another optional ("rx") for receiving notifications
> +      and delayed responses, if supported by the platform.
> +      The number of mailboxes needed for transmitting messages depends on the
> +      type of channels exposed by the specific underlying mailbox controller;
> +      one single channel descriptor is enough if such channel is bidirectional,
> +      while two channel descriptors are needed to represent the SCMI ("tx")
> +      channel if the underlying mailbox channels are of unidirectional type.
> +      The effective combination in numbers of mboxes and shmem descriptors let
> +      the SCMI subsystem determine unambiguosly which type of SCMI channels are
> +      made available by the underlying mailbox controller and how to use them.
> +       1 mbox / 1 shmem => SCMI TX over 1 mailbox bidirectional channel
> +       2 mbox / 2 shmem => SCMI TX and RX over 2 mailbox bidirectional channels
> +       2 mbox / 1 shmem => SCMI TX over 2 mailbox unidirectional channels
> +       3 mbox / 2 shmem => SCMI TX and RX over 3 mailbox unidirectional channels
> +      Any other combination of mboxes and shmem is invalid.
>      minItems: 1
> -    maxItems: 2
> +    maxItems: 3
>  
>    shmem:
>      description:
> @@ -228,13 +252,23 @@ $defs:
>          maxItems: 1
>  
>        mbox-names:
> -        items:
> -          - const: tx
> -          - const: rx
> +        oneOf:
> +          - items:
> +              - const: tx
> +          - items:
> +              - const: tx
> +              - const: rx
> +          - items:
> +              - const: tx
> +              - const: tx_reply
> +          - items:
> +              - const: tx
> +              - const: tx_reply
> +              - const: rx
>  
>        mboxes:
>          minItems: 1
> -        maxItems: 2
> +        maxItems: 3
>  
>        shmem:
>          minItems: 1
> @@ -393,6 +427,28 @@ examples:
>          };
>      };
>  
> +  - |
> +    firmware {
> +        scmi {
> +            compatible = "arm,scmi";
> +            mboxes = <&mhu_U_tx 0 0>, <&mhu_U_rx 0 0>;
> +            mbox-names = "tx", "tx_reply";
> +            shmem = <&cpu_scp_lpri0>;
> +
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            scmi_dvfs_2: protocol@13 {
> +                reg = <0x13>;
> +                #clock-cells = <1>;
> +
> +                mboxes = <&mhu_U_tx 1 0>, <&mhu_U_rx 1 0>, <&mhu_U_rx 1 1>;
> +                mbox-names = "tx", "tx_reply", "rx";
> +                shmem = <&cpu_scp_hpri0>, <&cpu_scp_hpri1>;
> +            };
> +        };
> +    };
> +
>    - |
>      firmware {
>          scmi {
> -- 
> 2.34.1
>