Re: [PATCH 2/2] dt-bindings: misc: convert fsl,qoriq-mc from txt to YAML
From: Laurentiu Tudor
Date: Thu Nov 05 2020 - 14:26:20 EST
Hi Rob,
On 11/5/2020 9:17 PM, Rob Herring wrote:
> On Thu, Nov 05, 2020 at 04:11:14PM +0200, Laurentiu Tudor wrote:
>> From: Ionut-robert Aron <ionut-robert.aron@xxxxxxx>
>>
>> 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.
>>
>> Signed-off-by: Ionut-robert Aron <ionut-robert.aron@xxxxxxx>
>> [laurentiu.tudor@xxxxxxx: update MINTAINERS, updates & fixes in schema]
>> Signed-off-by: Laurentiu Tudor <laurentiu.tudor@xxxxxxx>
>> ---
>> .../devicetree/bindings/misc/fsl,qoriq-mc.txt | 196 ----------------
>> .../bindings/misc/fsl,qoriq-mc.yaml | 218 ++++++++++++++++++
>> .../ethernet/freescale/dpaa2/overview.rst | 5 +-
>> MAINTAINERS | 4 +-
>> 4 files changed, 225 insertions(+), 198 deletions(-)
>> delete mode 100644 Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt
>> create mode 100644 Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml
>
> [...]
>
>> diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml
>> new file mode 100644
>> index 000000000000..9e89fd8eb635
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.yaml
>> @@ -0,0 +1,218 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +# Copyright 2020 NXP
>> +%YAML 1.2
>> +---
>> +$id: https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdevicetree.org%2Fschemas%2Fmisc%2Ffsl%2Cqoriq-mc.yaml%23&data=04%7C01%7Claurentiu.tudor%40nxp.com%7C64a5aeb6fee5459041db08d881bf7bf2%7C686ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C0%7C637402006701140599%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=fkXEIYUqXK1Dn6AqZtYLzro8nwJNCPJFI1Q9F9fRYxE%3D&reserved=0
>> +$schema: https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23&data=04%7C01%7Claurentiu.tudor%40nxp.com%7C64a5aeb6fee5459041db08d881bf7bf2%7C686ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C0%7C637402006701140599%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=X7k0Sxh7uPo11GgkGCeaKKMzHdu0gtphKheyJeROZ9Q%3D&reserved=0
>> +
>> +maintainers:
>> + - Laurentiu Tudor <laurentiu.tudor@xxxxxxx>
>> +
>> +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 relationship
>> + 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://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FNXP%2Fqoriq-mc-binary&data=04%7C01%7Claurentiu.tudor%40nxp.com%7C64a5aeb6fee5459041db08d881bf7bf2%7C686ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C0%7C637402006701140599%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=QKyEydXdS2AzqS7BlXVXDXpdjHfGL1%2BEdx95F1j5OHM%3D&reserved=0
>> +
>> +properties:
>> + compatible:
>> + const: "fsl,qoriq-mc"
>
> Don't need quotes.
>
>> + description: "Must be 'fsl,qoriq-mc'. A Freescale Management Complex
>
> Drop ^^^^^^^^^^^^^^^^^^^^^^^^
>
> The schema says that.
>
>> + compatible with this binding must have Block Revision
>> + Registers BRR1 and BRR2 at offset 0x0BF8 and 0x0BFC in
>> + the MC control register region."
>> +
>> + reg:
>> + description: "A standard property. Specifies one or two regions defining
>
> Don't need quotes. You need '|' for a literal block to keep formatting.
>
> But all this should be expressed as schema...
>
>> + 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. This region
>> + may not be present in some scenarios, such as in the device
>> + tree presented to a virtual machine."
>
> reg:
> minItems: 1
> items:
> - description: the command portal for the 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 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':
>> + 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.
>> +
>> + The dpmac nodes must be under a node named 'dpmacs' which
>> + contains the following properties:
>> +
>> + - '#address-cells'
>> + const: 1
>> + description: Must be present if dpmac sub-nodes are defined
>> + and must have a value of 1.
>> +
>> + - '#size-cells'
>> + const: 0
>> + description: Must be present if dpmac sub-nodes are defined
>> + and must have a value of 0."
>
> Drop whatever description can be expressed in schemas.
>
>> +
>> + properties:
>> + '#address-cells':
>> + const: 1
>> +
>> + '#size-cells':
>> + const: 0
>> +
>> + patternProperties:
>> + "^dpmac@[0-9a-f]+$":
>> + type: object
>> +
>> + description: "dpmac sub-node that describes the relationship between the
>> + Ethernet MACs which belong to the MC and the Ethernet PHYs
>> + on the system board."
>> +
>> + properties:
>> + compatible:
>> + const: "fsl,qoriq-mc-dpmac"
>> +
>> + reg:
>> + description: Specifies the id of the dpmac
>
> Constraints on the value?
>
Thanks a lot for taking a look. Will take care in the next spin.
PS. Nice work on the validation tools. My ~1 month old version didn't
catch those errors.
---
Best Regards, Laurentiu