linux-arm-kernel.lists.infradead.org archive mirror
 help / color / mirror / Atom feed
From: Rob Herring <robh@kernel.org>
To: Suman Anna <s-anna@ti.com>
Cc: Jassi Brar <jaswinder.singh@linaro.org>,
	Tony Lindgren <tony@atomide.com>, Nishanth Menon <nm@ti.com>,
	Jan Kiszka <jan.kiszka@siemens.com>,
	devicetree@vger.kernel.org, linux-omap@vger.kernel.org,
	linux-arm-kernel@lists.infradead.org
Subject: Re: [PATCH] dt-bindings: mailbox: Convert omap-mailbox.txt binding to YAML
Date: Wed, 19 May 2021 19:14:33 -0500	[thread overview]
Message-ID: <20210520001433.GB3927464@robh.at.kernel.org> (raw)
In-Reply-To: <20210518172022.10562-1-s-anna@ti.com>

On Tue, May 18, 2021 at 12:20:22PM -0500, Suman Anna wrote:
> Convert the current OMAP Mailbox binding from text format to YAML
> format/DT schema, and delete the legacy text binding file.
> 
> The new YAML binding conversion is an updated version compared to
> the original. The descriptions for certain properties have been
> improved to provide more clarity. Constraints are added to the
> properties 'ti,mbox-num-users', 'ti,mbox-num-fifos' and 'interrupts'.
> The 'ti,hwmods' is a legacy property and is retained only to reflect
> the existing usage on some older OMAP2 and OMAP3 platforms.
> 
> All the existing examples have also been updated to reflect the
> latest dts nodes (ti,hwmods removed from OMAP4 and AM33xx examples,
> and interrupts value updated for AM65x SoCs).
> 
> Signed-off-by: Suman Anna <s-anna@ti.com>
> ---
> Hi,
> 
> This patch does fix a number of dtbs_check warnings seen around OMAP Mailbox
> nodes with the latest kernel. There are few left-over warnings when just
> this patch is used on v5.13-rc1 or next-20210518. I have posted a separate
> fix for a warning on TI K3 SoCs [1], and will be posting a separate cleanup
> series for OMAP2+ SoCs. The dts patches can be picked up independently
> of this patch.
> 
> regards
> Suman
> 
> [1] https://patchwork.kernel.org/project/linux-arm-kernel/patch/20210514212016.3153-1-s-anna@ti.com/
> 
>  .../bindings/mailbox/omap-mailbox.txt         | 184 -----------
>  .../bindings/mailbox/ti,omap-mailbox.yaml     | 309 ++++++++++++++++++
>  2 files changed, 309 insertions(+), 184 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
>  create mode 100644 Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml


> +++ b/Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml
> @@ -0,0 +1,309 @@
> +# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mailbox/ti,omap-mailbox.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: TI OMAP2+ and K3 Mailbox devices
> +
> +maintainers:
> +  - Suman Anna <s-anna@ti.com>
> +
> +description: |
> +  The OMAP Mailbox hardware facilitates communication between different
> +  processors using a queued mailbox interrupt mechanism. The IP block is
> +  external to the various processor subsystems and is connected on an
> +  interconnect bus. The communication is achieved through a set of registers
> +  for message storage and interrupt configuration registers.
> +
> +  Each mailbox IP block/cluster has a certain number of h/w fifo queues and
> +  output interrupt lines. An output interrupt line is routed to an interrupt
> +  controller within a processor subsystem, and there can be more than one line
> +  going to a specific processor's interrupt controller. The interrupt line
> +  connections are fixed for an instance and are dictated by the IP integration
> +  into the SoC (excluding the SoCs that have an Interrupt Crossbar or an
> +  Interrupt Router IP). Each interrupt line is programmable through a set of
> +  interrupt configuration registers, and have a rx and tx interrupt source per
> +  h/w fifo. Communication between different processors is achieved through the
> +  appropriate programming of the rx and tx interrupt sources on the appropriate
> +  interrupt lines.
> +
> +  The number of h/w fifo queues and interrupt lines dictate the usable
> +  registers. All the current OMAP SoCs except for the newest DRA7xx SoC has a
> +  single IP instance. DRA7xx has multiple instances with different number of
> +  h/w fifo queues and interrupt lines between different instances. The interrupt
> +  lines can also be routed to different processor sub-systems on DRA7xx as they
> +  are routed through the Crossbar, a kind of interrupt router/multiplexer. The
> +  K3 AM65x, J721E and J7200 SoCs has each of these instances form a cluster and
> +  combine multiple clusters into a single IP block present within the Main
> +  NavSS. The interrupt lines from all these clusters are multiplexed and routed
> +  to different processor subsystems over a limited number of common interrupt
> +  output lines of an Interrupt Router. The AM64x SoCS also uses a single IP
> +  block comprising of multiple clusters, but the number of clusters are
> +  smaller, and the interrupt output lines are connected directly to various
> +  processors.
> +
> +  Mailbox Controller Nodes
> +  =========================
> +  A Mailbox device node is used to represent a Mailbox IP instance/cluster
> +  within a SoC. The sub-mailboxes (actual communication channels) are
> +  represented as child nodes of this parent node.
> +
> +  Mailbox Users
> +  ==============
> +  A device needing to communicate with a target processor device should specify
> +  them using the common mailbox binding properties, "mboxes" and the optional
> +  "mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
> +  for details). Each value of the mboxes property should contain a phandle to
> +  the mailbox controller device node and an args specifier that will be the
> +  phandle to the intended sub-mailbox child node to be used for communication.
> +  The equivalent "mbox-names" property value can be used to give a name to the
> +  communication channel to be used by the client user.
> +
> +definitions:

$defs is preferred (as that's what newer json-schema spec versions 
defined).

> +  omap-mbox-descriptor:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    description: |
> +      The omap-mbox-descriptor is made of up of 3 cells and represents a single
> +      uni-directional communication channel. A typical sub-mailbox device uses
> +      two such channels - one for transmitting (Tx) and one for receiving (Rx).
> +    items:
> +      - description: |
> +          mailbox fifo id used either for transmitting on ti,mbox-tx channel or
> +          for receiving on ti,mbox-rx channel (fifo_id). This is the hardware
> +          fifo number within a mailbox cluster.
> +      - description: |
> +          irq identifier index number to use from the parent's interrupts data.
> +          Should be 0 for most of the cases, a positive index value is seen only
> +          on mailboxes that have multiple interrupt lines connected to the MPU
> +          processor (irq_id). This is an index number in the listed interrupts
> +          property in the DT nodes.
> +      - description: |
> +          mailbox user id for identifying the interrupt line associated with
> +          generating a tx/rx fifo interrupt (usr_id). This is the hardware
> +          user id number within a mailbox cluster.
> +
> +  omap-sub-mailbox:
> +    type: object
> +    description: |
> +      The omap-sub-mailbox is a child node within a Mailbox controller device
> +      node and represents the actual communication channel used to send and
> +      receive messages between the host processor and a remote processor. Each
> +      child node should have a unique node name across all the different mailbox
> +      device nodes.
> +
> +    properties:
> +      ti,mbox-tx:
> +        $ref: "#/definitions/omap-mbox-descriptor"
> +        description: sub-mailbox descriptor property defining a Tx fifo.
> +
> +      ti,mbox-rx:
> +        $ref: "#/definitions/omap-mbox-descriptor"
> +        description: sub-mailbox descriptor property defining a Rx fifo.
> +
> +      ti,mbox-send-noirq:
> +        type: boolean
> +        description: |

Drop '|' if formatting is not important.

> +          Quirk flag to allow the client user of this sub-mailbox to send
> +          messages without triggering a Tx ready interrupt, and to control
> +          the Tx ticker. Should be used only on sub-mailboxes used to
> +          communicate with WkupM3 remote processor on AM33xx/AM43xx SoCs.
> +
> +    required:
> +      - ti,mbox-tx
> +      - ti,mbox-rx
> +
> +properties:
> +  compatible:
> +    enum:
> +      - ti,omap2-mailbox # for OMAP2420, OMAP2430 SoCs
> +      - ti,omap3-mailbox # for OMAP3430, OMAP3630 SoCs
> +      - ti,omap4-mailbox # for OMAP44xx, OMAP54xx, AM33xx, AM43xx and DRA7xx SoCs
> +      - ti,am654-mailbox # for K3 AM65x, J721E and J7200 SoCs
> +      - ti,am64-mailbox  # for K3 AM64x SoCs
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    description: |
> +      Contains the interrupt information for the mailbox device. The format is
> +      dependent on which interrupt controller the Mailbox device uses. The
> +      number of interrupts listed will at most be the value specified in
> +      ti,mbox-num-users property, but is usually limited by the number of
> +      interrupts reaching the main processor. An interrupt-parent property
> +      is required on SoCs where the interrupt lines are connected through a
> +      Interrupt Router before reaching the main processor's GIC.
> +
> +  "#mbox-cells":
> +    const: 1
> +    description: |
> +      Common mailbox binding property to identify the number of cells required
> +      for the mailbox specifier in a consumer node. The specifier is a phandle
> +      to a omap-sub-mailbox device.

Can drop the first sentence.

> +
> +  ti,mbox-num-users:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: |
> +      Number of targets (processor devices) that the mailbox device can
> +      interrupt.
> +
> +  ti,mbox-num-fifos:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: Number of h/w fifo queues within the mailbox IP block.
> +
> +  ti,hwmods:
> +    $ref: /schemas/types.yaml#/definitions/string
> +    description: |
> +      Name of the hwmod associated with the mailbox. This should be defined
> +      in the mailbox node only if the node is not defined as a child node of
> +      a corresponding sysc interconnect node.
> +
> +      This property is only needed on some legacy OMAP SoCs which have not
> +      yet been converted to the ti,sysc interconnect hierarachy, but is
> +      otherwise considered obsolete.

deprecated: true

> +
> +patternProperties:
> +  "^mbox-[a-z0-9-]+$":
> +    $ref: "#/definitions/omap-sub-mailbox"
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - "#mbox-cells"
> +  - ti,mbox-num-users
> +  - ti,mbox-num-fifos
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          enum:
> +            - ti,am654-mailbox
> +    then:
> +      required:
> +        - interrupt-parent
> +
> +  - if:
> +      properties:
> +        compatible:
> +          enum:
> +            - ti,am654-mailbox
> +            - ti,am64-mailbox
> +    then:
> +      properties:
> +        ti,mbox-num-users:
> +          const: 4
> +        ti,mbox-num-fifos:
> +          const: 16
> +        interrupts:
> +          minItems: 1
> +          maxItems: 4
> +
> +  - if:
> +      properties:
> +        compatible:
> +          enum:
> +            - ti,omap4-mailbox
> +    then:
> +      properties:
> +        ti,mbox-num-users:
> +          enum: [3, 4]
> +        ti,mbox-num-fifos:
> +          enum: [8, 12]
> +        interrupts:
> +          minItems: 1
> +          maxItems: 4
> +
> +  - if:
> +      properties:
> +        compatible:
> +          enum:
> +            - ti,omap3-mailbox
> +    then:
> +      properties:
> +        ti,mbox-num-users:
> +          const: 2
> +        ti,mbox-num-fifos:
> +          const: 2
> +        interrupts:
> +          minItems: 1
> +          maxItems: 1
> +
> +  - if:
> +      properties:
> +        compatible:
> +          enum:
> +            - ti,omap2-mailbox
> +    then:
> +      properties:
> +        ti,mbox-num-users:
> +          const: 4
> +        ti,mbox-num-fifos:
> +          const: 6
> +        interrupts:
> +          minItems: 1
> +          maxItems: 2
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    /* OMAP4 */
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +    mailbox: mailbox@4a0f4000 {
> +        compatible = "ti,omap4-mailbox";
> +        reg = <0x4a0f4000 0x200>;
> +        interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
> +        #mbox-cells = <1>;
> +        ti,mbox-num-users = <3>;
> +        ti,mbox-num-fifos = <8>;
> +
> +        mbox_ipu: mbox-ipu {
> +            ti,mbox-tx = <0 0 0>;
> +            ti,mbox-rx = <1 0 0>;
> +        };
> +        mbox_dsp: mbox-dsp {
> +            ti,mbox-tx = <3 0 0>;
> +            ti,mbox-rx = <2 0 0>;
> +        };
> +    };
> +
> +    dsp {
> +        mboxes = <&mailbox &mbox_dsp>;
> +    };
> +
> +  - |
> +    /* AM33xx */
> +    mailbox1: mailbox@480c8000 {
> +        compatible = "ti,omap4-mailbox";
> +        reg = <0x480c8000 0x200>;
> +        interrupts = <77>;
> +        #mbox-cells = <1>;
> +        ti,mbox-num-users = <4>;
> +        ti,mbox-num-fifos = <8>;
> +
> +        mbox_wkupm3: mbox-wkup-m3 {
> +            ti,mbox-tx = <0 0 0>;
> +            ti,mbox-rx = <0 0 3>;
> +            ti,mbox-send-noirq;
> +        };
> +    };
> +
> +  - |
> +    /* AM65x */
> +    mailbox0_cluster0: mailbox@31f80000 {
> +        compatible = "ti,am654-mailbox";
> +        reg = <0x31f80000 0x200>;
> +        #mbox-cells = <1>;
> +        ti,mbox-num-users = <4>;
> +        ti,mbox-num-fifos = <16>;
> +        interrupt-parent = <&intr_main_navss>;
> +        interrupts = <436>;
> +
> +        mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
> +            ti,mbox-tx = <1 0 0>;
> +            ti,mbox-rx = <0 0 0>;
> +        };
> +    };
> -- 
> 2.30.1
> 

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

      parent reply	other threads:[~2021-05-20  0:17 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-18 17:20 Suman Anna
2021-05-19 15:14 ` Suman Anna
2021-05-20  0:08   ` Rob Herring
2021-05-20 16:45     ` Suman Anna
2021-05-20 19:21       ` Rob Herring
2021-05-20 20:07         ` Suman Anna
2021-05-25  6:44           ` Tony Lindgren
2021-05-21  9:21       ` Tony Lindgren
2021-05-20  0:14 ` Rob Herring [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210520001433.GB3927464@robh.at.kernel.org \
    --to=robh@kernel.org \
    --cc=devicetree@vger.kernel.org \
    --cc=jan.kiszka@siemens.com \
    --cc=jaswinder.singh@linaro.org \
    --cc=linux-arm-kernel@lists.infradead.org \
    --cc=linux-omap@vger.kernel.org \
    --cc=nm@ti.com \
    --cc=s-anna@ti.com \
    --cc=tony@atomide.com \
    --subject='Re: [PATCH] dt-bindings: mailbox: Convert omap-mailbox.txt binding to YAML' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).