Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Ioana Ciornei <ioana.ciornei@nxp.com>
To:     Laurentiu Tudor <laurentiu.tudor@nxp.com>
CC:     "robh+dt@kernel.org" <robh+dt@kernel.org>,
        Leo Li <leoyang.li@nxp.com>, "corbet@lwn.net" <corbet@lwn.net>,
        "linux-arm-kernel@lists.infradead.org" 
        <linux-arm-kernel@lists.infradead.org>,
        "devicetree@vger.kernel.org" <devicetree@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        "netdev@vger.kernel.org" <netdev@vger.kernel.org>,
        "linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
        "davem@davemloft.net" <davem@davemloft.net>,
        "kuba@kernel.org" <kuba@kernel.org>,
        "linuxppc-dev@lists.ozlabs.org" <linuxppc-dev@lists.ozlabs.org>,
        Ionut-robert Aron <ionut-robert.aron@nxp.com>
Subject: Re: [PATCH v4] dt-bindings: misc: convert fsl,qoriq-mc from txt to
 YAML
Thread-Topic: [PATCH v4] dt-bindings: misc: convert fsl,qoriq-mc from txt to
 YAML
Thread-Index: AQHWwXc4EjGvC2esXEeB1A2oO9x3vqnYczCA
Date:   Wed, 25 Nov 2020 07:17:49 +0000
Message-ID: <20201125071226.kcz6b6tkb2zgkg7z@skbuf>
References: <20201123090035.15734-1-laurentiu.tudor@nxp.com>
In-Reply-To: <20201123090035.15734-1-laurentiu.tudor@nxp.com>
Accept-Language: en-US
Content-Language: en-US
Content-Type: text/plain; charset="us-ascii"
Content-ID: <E4A644AF6AB4EF45A131FE4DE2433BAA@eurprd04.prod.outlook.com>
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-Network-Message-Id: 50aa1c5e-5e9f-4c50-8a64-08d891123731
X-MS-Exchange-CrossTenant-originalarrivaltime: 25 Nov 2020 07:17:49.3298
 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: KLt69tp3ZOatrk5hI6IRwBznQ1/b9FmSUWIuf/65BWVwnT+8tW9bs5No97psbgrHpsj051pGpTUVypkoFBt9jA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: VE1PR04MB6445
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Mon, Nov 23, 2020 at 11:00:35AM +0200, Laurentiu Tudor wrote:
> From: Ionut-robert Aron <ionut-robert.aron@nxp.com>
>=20
> Convert fsl,qoriq-mc to YAML in order to automate the verification
> process of dts files. In addition, update MAINTAINERS accordingly
> and, while at it, add some missing files.
>=20
> Signed-off-by: Ionut-robert Aron <ionut-robert.aron@nxp.com>
> [laurentiu.tudor@nxp.com: update MINTAINERS, updates & fixes in schema]
> Signed-off-by: Laurentiu Tudor <laurentiu.tudor@nxp.com>

Acked-by: Ioana Ciornei <ioana.ciornei@nxp.com>


> ---
> Changes in v4:
>  - use $ref to point to fsl,qoriq-mc-dpmac binding
>=20
> Changes in v3:
>  - dropped duplicated "fsl,qoriq-mc-dpmac" schema and replaced with
>    reference to it
>  - fixed a dt_binding_check warning
>=20
> Changes in v2:
>  - fixed errors reported by yamllint
>  - dropped multiple unnecessary quotes
>  - used schema instead of text in description
>  - added constraints on dpmac reg property
>=20
>  .../devicetree/bindings/misc/fsl,qoriq-mc.txt | 196 ------------------
>  .../bindings/misc/fsl,qoriq-mc.yaml           | 186 +++++++++++++++++
>  .../ethernet/freescale/dpaa2/overview.rst     |   5 +-
>  MAINTAINERS                                   |   4 +-
>  4 files changed, 193 insertions(+), 198 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/misc/fsl,qoriq-mc.t=
xt
>  create mode 100644 Documentation/devicetree/bindings/misc/fsl,qoriq-mc.y=
aml
>=20
> diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt b/Do=
cumentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
> deleted file mode 100644
> index 7b486d4985dc..000000000000
> --- a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
> +++ /dev/null
> @@ -1,196 +0,0 @@
> -* Freescale Management Complex
> -
> -The Freescale Management Complex (fsl-mc) is a hardware resource
> -manager that manages specialized hardware objects used in
> -network-oriented packet processing applications. After the fsl-mc
> -block is enabled, pools of hardware resources are available, such as
> -queues, buffer pools, I/O interfaces. These resources are building
> -blocks that can be used to create functional hardware objects/devices
> -such as network interfaces, crypto accelerator instances, L2 switches,
> -etc.
> -
> -For an overview of the DPAA2 architecture and fsl-mc bus see:
> -Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overvie=
w.rst
> -
> -As described in the above overview, all DPAA2 objects in a DPRC share th=
e
> -same hardware "isolation context" and a 10-bit value called an ICID
> -(isolation context id) is expressed by the hardware to identify
> -the requester.
> -
> -The generic 'iommus' property is insufficient to describe the relationsh=
ip
> -between ICIDs and IOMMUs, so an iommu-map property is used to define
> -the set of possible ICIDs under a root DPRC and how they map to
> -an IOMMU.
> -
> -For generic IOMMU bindings, see
> -Documentation/devicetree/bindings/iommu/iommu.txt.
> -
> -For arm-smmu binding, see:
> -Documentation/devicetree/bindings/iommu/arm,smmu.yaml.
> -
> -The MSI writes are accompanied by sideband data which is derived from th=
e ICID.
> -The msi-map property is used to associate the devices with both the ITS
> -controller and the sideband data which accompanies the writes.
> -
> -For generic MSI bindings, see
> -Documentation/devicetree/bindings/interrupt-controller/msi.txt.
> -
> -For GICv3 and GIC ITS bindings, see:
> -Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.yaml.
> -
> -Required properties:
> -
> -    - compatible
> -        Value type: <string>
> -        Definition: Must be "fsl,qoriq-mc".  A Freescale Management Comp=
lex
> -                    compatible with this binding must have Block Revisio=
n
> -                    Registers BRR1 and BRR2 at offset 0x0BF8 and 0x0BFC =
in
> -                    the MC control register region.
> -
> -    - reg
> -        Value type: <prop-encoded-array>
> -        Definition: A standard property.  Specifies one or two regions
> -                    defining the MC's registers:
> -
> -                       -the first region is the command portal for the
> -                        this machine and must always be present
> -
> -                       -the second region is the MC control registers. T=
his
> -                        region may not be present in some scenarios, suc=
h
> -                        as in the device tree presented to a virtual mac=
hine.
> -
> -    - ranges
> -        Value type: <prop-encoded-array>
> -        Definition: A standard property.  Defines the mapping between th=
e child
> -                    MC address space and the parent system address space=
.
> -
> -                    The MC address space is defined by 3 components:
> -                       <region type> <offset hi> <offset lo>
> -
> -                    Valid values for region type are
> -                       0x0 - MC portals
> -                       0x1 - QBMAN portals
> -
> -    - #address-cells
> -        Value type: <u32>
> -        Definition: Must be 3.  (see definition in 'ranges' property)
> -
> -    - #size-cells
> -        Value type: <u32>
> -        Definition: Must be 1.
> -
> -Sub-nodes:
> -
> -        The fsl-mc node may optionally have dpmac sub-nodes that describ=
e
> -        the relationship between the Ethernet MACs which belong to the M=
C
> -        and the Ethernet PHYs on the system board.
> -
> -        The dpmac nodes must be under a node named "dpmacs" which contai=
ns
> -        the following properties:
> -
> -            - #address-cells
> -              Value type: <u32>
> -              Definition: Must be present if dpmac sub-nodes are defined=
 and must
> -                          have a value of 1.
> -
> -            - #size-cells
> -              Value type: <u32>
> -              Definition: Must be present if dpmac sub-nodes are defined=
 and must
> -                          have a value of 0.
> -
> -        These nodes must have the following properties:
> -
> -            - compatible
> -              Value type: <string>
> -              Definition: Must be "fsl,qoriq-mc-dpmac".
> -
> -            - reg
> -              Value type: <prop-encoded-array>
> -              Definition: Specifies the id of the dpmac.
> -
> -            - phy-handle
> -              Value type: <phandle>
> -              Definition: Specifies the phandle to the PHY device node a=
ssociated
> -                          with the this dpmac.
> -Optional properties:
> -
> -- iommu-map: Maps an ICID to an IOMMU and associated iommu-specifier
> -  data.
> -
> -  The property is an arbitrary number of tuples of
> -  (icid-base,iommu,iommu-base,length).
> -
> -  Any ICID i in the interval [icid-base, icid-base + length) is
> -  associated with the listed IOMMU, with the iommu-specifier
> -  (i - icid-base + iommu-base).
> -
> -- msi-map: Maps an ICID to a GIC ITS and associated msi-specifier
> -  data.
> -
> -  The property is an arbitrary number of tuples of
> -  (icid-base,gic-its,msi-base,length).
> -
> -  Any ICID in the interval [icid-base, icid-base + length) is
> -  associated with the listed GIC ITS, with the msi-specifier
> -  (i - icid-base + msi-base).
> -
> -Deprecated properties:
> -
> -    - msi-parent
> -        Value type: <phandle>
> -        Definition: Describes the MSI controller node handling message
> -                    interrupts for the MC. When there is no translation
> -                    between the ICID and deviceID this property can be u=
sed
> -                    to describe the MSI controller used by the devices o=
n the
> -                    mc-bus.
> -                    The use of this property for mc-bus is deprecated. P=
lease
> -                    use msi-map.
> -
> -Example:
> -
> -        smmu: iommu@5000000 {
> -               compatible =3D "arm,mmu-500";
> -               #iommu-cells =3D <1>;
> -               stream-match-mask =3D <0x7C00>;
> -               ...
> -        };
> -
> -        gic: interrupt-controller@6000000 {
> -               compatible =3D "arm,gic-v3";
> -               ...
> -        }
> -        its: gic-its@6020000 {
> -               compatible =3D "arm,gic-v3-its";
> -               msi-controller;
> -               ...
> -        };
> -
> -        fsl_mc: fsl-mc@80c000000 {
> -                compatible =3D "fsl,qoriq-mc";
> -                reg =3D <0x00000008 0x0c000000 0 0x40>,    /* MC portal =
base */
> -                      <0x00000000 0x08340000 0 0x40000>; /* MC control r=
eg */
> -                /* define map for ICIDs 23-64 */
> -                iommu-map =3D <23 &smmu 23 41>;
> -                /* define msi map for ICIDs 23-64 */
> -                msi-map =3D <23 &its 23 41>;
> -                #address-cells =3D <3>;
> -                #size-cells =3D <1>;
> -
> -                /*
> -                 * Region type 0x0 - MC portals
> -                 * Region type 0x1 - QBMAN portals
> -                 */
> -                ranges =3D <0x0 0x0 0x0 0x8 0x0c000000 0x4000000
> -                          0x1 0x0 0x0 0x8 0x18000000 0x8000000>;
> -
> -                dpmacs {
> -                    #address-cells =3D <1>;
> -                    #size-cells =3D <0>;
> -
> -                    dpmac@1 {
> -                        compatible =3D "fsl,qoriq-mc-dpmac";
> -                        reg =3D <1>;
> -                        phy-handle =3D <&mdio0_phy0>;
> -                    }
> -                }
> -        };
> diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml b/D=
ocumentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml
> new file mode 100644
> index 000000000000..f45e21872e4f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml
> @@ -0,0 +1,186 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright 2020 NXP
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/misc/fsl,qoriq-mc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +maintainers:
> +  - Laurentiu Tudor <laurentiu.tudor@nxp.com>
> +
> +title: Freescale Management Complex
> +
> +description: |
> +  The Freescale Management Complex (fsl-mc) is a hardware resource
> +  manager that manages specialized hardware objects used in
> +  network-oriented packet processing applications. After the fsl-mc
> +  block is enabled, pools of hardware resources are available, such as
> +  queues, buffer pools, I/O interfaces. These resources are building
> +  blocks that can be used to create functional hardware objects/devices
> +  such as network interfaces, crypto accelerator instances, L2 switches,
> +  etc.
> +
> +  For an overview of the DPAA2 architecture and fsl-mc bus see:
> +  Documentation/networking/device_drivers/freescale/dpaa2/overview.rst
> +
> +  As described in the above overview, all DPAA2 objects in a DPRC share =
the
> +  same hardware "isolation context" and a 10-bit value called an ICID
> +  (isolation context id) is expressed by the hardware to identify
> +  the requester.
> +
> +  The generic 'iommus' property is insufficient to describe the relation=
ship
> +  between ICIDs and IOMMUs, so an iommu-map property is used to define
> +  the set of possible ICIDs under a root DPRC and how they map to
> +  an IOMMU.
> +
> +  For generic IOMMU bindings, see:
> +  Documentation/devicetree/bindings/iommu/iommu.txt.
> +
> +  For arm-smmu binding, see:
> +  Documentation/devicetree/bindings/iommu/arm,smmu.yaml.
> +
> +  MC firmware binary images can be found here:
> +  https://github.com/NXP/qoriq-mc-binary
> +
> +properties:
> +  compatible:
> +    const: fsl,qoriq-mc
> +    description:
> +      A Freescale Management Complex compatible with this binding must h=
ave
> +      Block Revision Registers BRR1 and BRR2 at offset 0x0BF8 and 0x0BFC=
 in
> +      the MC control register region.
> +
> +  reg:
> +    minItems: 1
> +    items:
> +      - description: the command portal for this machine
> +      - description:
> +          MC control registers. This region may not be present in some
> +          scenarios, such as in the device tree presented to a virtual
> +          machine.
> +
> +  ranges:
> +    description: |
> +      A standard property. Defines the mapping between the child MC addr=
ess
> +      space and the parent system address space.
> +
> +      The MC address space is defined by 3 components:
> +                <region type> <offset hi> <offset lo>
> +
> +      Valid values for region type are:
> +                  0x0 - MC portals
> +                  0x1 - QBMAN portals
> +
> +  '#address-cells':
> +    const: 3
> +
> +  '#size-cells':
> +    const: 1
> +
> +  dpmacs:
> +    type: object
> +    description:
> +      The fsl-mc node may optionally have dpmac sub-nodes that describe =
the
> +      relationship between the Ethernet MACs which belong to the MC and =
the
> +      Ethernet PHYs on the system board.
> +
> +    properties:
> +      '#address-cells':
> +        const: 1
> +
> +      '#size-cells':
> +        const: 0
> +
> +    patternProperties:
> +      "^(dpmac@[0-9a-f]+)|(ethernet@[0-9a-f]+)$":
> +        type: object
> +
> +        $ref: /schemas/net/fsl,qoriq-mc-dpmac.yaml#
> +
> +  iommu-map:
> +    description: |
> +      Maps an ICID to an IOMMU and associated iommu-specifier data.
> +
> +      The property is an arbitrary number of tuples of
> +      (icid-base, iommu, iommu-base, length).
> +
> +      Any ICID i in the interval [icid-base, icid-base + length) is
> +      associated with the listed IOMMU, with the iommu-specifier
> +      (i - icid-base + iommu-base).
> +
> +  msi-map:
> +    description: |
> +      Maps an ICID to a GIC ITS and associated msi-specifier data.
> +
> +      The property is an arbitrary number of tuples of
> +      (icid-base, gic-its, msi-base, length).
> +
> +      Any ICID in the interval [icid-base, icid-base + length) is
> +      associated with the listed GIC ITS, with the msi-specifier
> +      (i - icid-base + msi-base).
> +
> +  msi-parent:
> +    deprecated: true
> +    description:
> +      Points to the MSI controller node handling message interrupts for =
the MC.
> +
> +required:
> +  - compatible
> +  - reg
> +  - iommu-map
> +  - msi-map
> +  - ranges
> +  - '#address-cells'
> +  - '#size-cells'
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    soc {
> +      #address-cells =3D <2>;
> +      #size-cells =3D <2>;
> +
> +      smmu: iommu@5000000 {
> +        compatible =3D "arm,mmu-500";
> +        #global-interrupts =3D <1>;
> +        #iommu-cells =3D <1>;
> +        reg =3D <0 0x5000000 0 0x800000>;
> +        stream-match-mask =3D <0x7c00>;
> +        interrupts =3D <0 13 4>,
> +                     <0 146 4>, <0 147 4>,
> +                     <0 148 4>, <0 149 4>,
> +                     <0 150 4>, <0 151 4>,
> +                     <0 152 4>, <0 153 4>;
> +      };
> +
> +      fsl_mc: fsl-mc@80c000000 {
> +        compatible =3D "fsl,qoriq-mc";
> +        reg =3D <0x00000008 0x0c000000 0 0x40>,    /* MC portal base */
> +        <0x00000000 0x08340000 0 0x40000>; /* MC control reg */
> +        /* define map for ICIDs 23-64 */
> +        iommu-map =3D <23 &smmu 23 41>;
> +        /* define msi map for ICIDs 23-64 */
> +        msi-map =3D <23 &its 23 41>;
> +        #address-cells =3D <3>;
> +        #size-cells =3D <1>;
> +
> +        /*
> +        * Region type 0x0 - MC portals
> +        * Region type 0x1 - QBMAN portals
> +        */
> +        ranges =3D <0x0 0x0 0x0 0x8 0x0c000000 0x4000000
> +                  0x1 0x0 0x0 0x8 0x18000000 0x8000000>;
> +
> +        dpmacs {
> +          #address-cells =3D <1>;
> +          #size-cells =3D <0>;
> +
> +          ethernet@1 {
> +            compatible =3D "fsl,qoriq-mc-dpmac";
> +            reg =3D <1>;
> +            phy-handle =3D <&mdio0_phy0>;
> +          };
> +        };
> +      };
> +    };
> diff --git a/Documentation/networking/device_drivers/ethernet/freescale/d=
paa2/overview.rst b/Documentation/networking/device_drivers/ethernet/freesc=
ale/dpaa2/overview.rst
> index d638b5a8aadd..b3261c5871cc 100644
> --- a/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ov=
erview.rst
> +++ b/Documentation/networking/device_drivers/ethernet/freescale/dpaa2/ov=
erview.rst
> @@ -28,6 +28,9 @@ interfaces, an L2 switch, or accelerator instances.
>  The MC provides memory-mapped I/O command interfaces (MC portals)
>  which DPAA2 software drivers use to operate on DPAA2 objects.
> =20
> +MC firmware binary images can be found here:
> +https://github.com/NXP/qoriq-mc-binary
> +
>  The diagram below shows an overview of the DPAA2 resource management
>  architecture::
> =20
> @@ -338,7 +341,7 @@ Key functions include:
>    a bind of the root DPRC to the DPRC driver
> =20
>  The binding for the MC-bus device-tree node can be consulted at
> -*Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt*.
> +*Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml*.
>  The sysfs bind/unbind interfaces for the MC-bus can be consulted at
>  *Documentation/ABI/testing/sysfs-bus-fsl-mc*.
> =20
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b516bb34a8d5..e0ce6e2b663c 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14409,9 +14409,11 @@ M:	Stuart Yoder <stuyoder@gmail.com>
>  M:	Laurentiu Tudor <laurentiu.tudor@nxp.com>
>  L:	linux-kernel@vger.kernel.org
>  S:	Maintained
> -F:	Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
> +F:	Documentation/devicetree/bindings/misc/fsl,dpaa2-console.yaml
> +F:	Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml
>  F:	Documentation/networking/device_drivers/ethernet/freescale/dpaa2/over=
view.rst
>  F:	drivers/bus/fsl-mc/
> +F:	include/linux/fsl/mc.h
> =20
>  QT1010 MEDIA DRIVER
>  M:	Antti Palosaari <crope@iki.fi>
> --=20
> 2.17.1
> =