Re: [PATCH] dt-bindings: mailbox: Convert omap-mailbox.txt binding to YAML

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxx>
> ---
> 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@xxxxxx/
> 
>  .../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@xxxxxx>
> +
> +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
> 



[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]


  Powered by Linux