[PATCH] dt-bindings: Improve phandle-array schemas

[Rob Herring]

On Wed, Jan 19, 2022 at 9:22 AM Arnaud POULIQUEN
<arnaud.pouliquen at foss.st.com> wrote:
>
> Hello Rob,
>
> On 1/19/22 2:50 AM, Rob Herring wrote:
> > The 'phandle-array' type is a bit ambiguous. It can be either just an
> > array of phandles or an array of phandles plus args. Many schemas for
> > phandle-array properties aren't clear in the schema which case applies
> > though the description usually describes it.
> >
> > The array of phandles case boils down to needing:
> >
> > items:
> >   maxItems: 1
> >
> > The phandle plus args cases should typically take this form:
> >
> > items:
> >   - items:
> >       - description: A phandle
> >       - description: 1st arg cell
> >       - description: 2nd arg cell
> >
> > With this change, some examples need updating so that the bracketing of
> > property values matches the schema.
> >
> > Cc: Damien Le Moal <damien.lemoal at opensource.wdc.com>
> > Cc: Herbert Xu <herbert at gondor.apana.org.au>
> > Cc: "David S. Miller" <davem at davemloft.net>
> > Cc: Chun-Kuang Hu <chunkuang.hu at kernel.org>
> > Cc: Philipp Zabel <p.zabel at pengutronix.de>
> > Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > Cc: Kieran Bingham <kieran.bingham+renesas at ideasonboard.com>
> > Cc: Vinod Koul <vkoul at kernel.org>
> > Cc: Georgi Djakov <djakov at kernel.org>
> > Cc: Thomas Gleixner <tglx at linutronix.de>
> > Cc: Marc Zyngier <maz at kernel.org>
> > Cc: Joerg Roedel <joro at 8bytes.org>
> > Cc: Lee Jones <lee.jones at linaro.org>
> > Cc: Daniel Thompson <daniel.thompson at linaro.org>
> > Cc: Jingoo Han <jingoohan1 at gmail.com>
> > Cc: Pavel Machek <pavel at ucw.cz>
> > Cc: Mauro Carvalho Chehab <mchehab at kernel.org>
> > Cc: Krzysztof Kozlowski <krzysztof.kozlowski at canonical.com>
> > Cc: Jakub Kicinski <kuba at kernel.org>
> > Cc: Wolfgang Grandegger <wg at grandegger.com>
> > Cc: Marc Kleine-Budde <mkl at pengutronix.de>
> > Cc: Andrew Lunn <andrew at lunn.ch>
> > Cc: Vivien Didelot <vivien.didelot at gmail.com>
> > Cc: Florian Fainelli <f.fainelli at gmail.com>
> > Cc: Vladimir Oltean <olteanv at gmail.com>
> > Cc: Kalle Valo <kvalo at kernel.org>
> > Cc: Viresh Kumar <vireshk at kernel.org>
> > Cc: Stephen Boyd <sboyd at kernel.org>
> > Cc: Kishon Vijay Abraham I <kishon at ti.com>
> > Cc: Linus Walleij <linus.walleij at linaro.org>
> > Cc: "Rafael J. Wysocki" <rafael at kernel.org>
> > Cc: Kevin Hilman <khilman at kernel.org>
> > Cc: Ulf Hansson <ulf.hansson at linaro.org>
> > Cc: Sebastian Reichel <sre at kernel.org>
> > Cc: Mark Brown <broonie at kernel.org>
> > Cc: Mathieu Poirier <mathieu.poirier at linaro.org>
> > Cc: Daniel Lezcano <daniel.lezcano at linaro.org>
> > Cc: Zhang Rui <rui.zhang at intel.com>
> > Cc: Greg Kroah-Hartman <gregkh at linuxfoundation.org>
> > Cc: Thierry Reding <thierry.reding at gmail.com>
> > Cc: Jonathan Hunter <jonathanh at nvidia.com>
> > Cc: Sudeep Holla <sudeep.holla at arm.com>
> > Cc: Geert Uytterhoeven <geert+renesas at glider.be>
> > Cc: linux-ide at vger.kernel.org
> > Cc: linux-crypto at vger.kernel.org
> > Cc: dri-devel at lists.freedesktop.org
> > Cc: dmaengine at vger.kernel.org
> > Cc: linux-pm at vger.kernel.org
> > Cc: iommu at lists.linux-foundation.org
> > Cc: linux-leds at vger.kernel.org
> > Cc: linux-media at vger.kernel.org
> > Cc: netdev at vger.kernel.org
> > Cc: linux-can at vger.kernel.org
> > Cc: linux-wireless at vger.kernel.org
> > Cc: linux-phy at lists.infradead.org
> > Cc: linux-gpio at vger.kernel.org
> > Cc: linux-riscv at lists.infradead.org
> > Cc: linux-remoteproc at vger.kernel.org
> > Cc: alsa-devel at alsa-project.org
> > Cc: linux-usb at vger.kernel.org
> > Signed-off-by: Rob Herring <robh at kernel.org>
> > ---
>
> [...]
>
> >  .../bindings/remoteproc/st,stm32-rproc.yaml   | 33 ++++++--
>
> [...]
>
> > diff --git a/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml
> > index b587c97c282b..be3d9b0e876b 100644
> > --- a/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml
> > +++ b/Documentation/devicetree/bindings/remoteproc/st,stm32-rproc.yaml
> > @@ -29,17 +29,22 @@ properties:
> >
> >    st,syscfg-holdboot:
> >      description: remote processor reset hold boot
> > -      - Phandle of syscon block.
> > -      - The offset of the hold boot setting register.
> > -      - The field mask of the hold boot.
> >      $ref: "/schemas/types.yaml#/definitions/phandle-array"
> > -    maxItems: 1
> > +    items:
> > +      - items:
> > +          - description: Phandle of syscon block
> > +          - description: The offset of the hold boot setting register
> > +          - description: The field mask of the hold boot
> >
> >    st,syscfg-tz:
> >      description:
> >        Reference to the system configuration which holds the RCC trust zone mode
> >      $ref: "/schemas/types.yaml#/definitions/phandle-array"
> > -    maxItems: 1
> > +    items:
> > +      - items:
> > +          - description: Phandle of syscon block
> > +          - description: FIXME
> > +          - description: FIXME
>
>          - description: The offset of the trust zone setting register
>          - description: The field mask of the trust zone state
>
> >
> >    interrupts:
> >      description: Should contain the WWDG1 watchdog reset interrupt
> > @@ -93,20 +98,32 @@ properties:
> >      $ref: "/schemas/types.yaml#/definitions/phandle-array"
> >      description: |
> >        Reference to the system configuration which holds the remote
> > -    maxItems: 1
> > +    items:
> > +      - items:
> > +          - description: Phandle of syscon block
> > +          - description: FIXME
> > +          - description: FIXME
>
>          - description: The offset of the power setting register
>          - description: The field mask of the PDDS selection
>
> >
> >    st,syscfg-m4-state:
> >      $ref: "/schemas/types.yaml#/definitions/phandle-array"
> >      description: |
> >        Reference to the tamp register which exposes the Cortex-M4 state.
> > -    maxItems: 1
> > +    items:
> > +      - items:
> > +          - description: Phandle of syscon block with the tamp register
> > +          - description: FIXME
> > +          - description: FIXME
>
>          - description: The offset of the tamp register
>          - description: The field mask of the Cortex-M4 state
>
> >
> >    st,syscfg-rsc-tbl:
> >      $ref: "/schemas/types.yaml#/definitions/phandle-array"
> >      description: |
> >        Reference to the tamp register which references the Cortex-M4
> >        resource table address.
> > -    maxItems: 1
> > +    items:
> > +      - items:
> > +          - description: Phandle of syscon block with the tamp register
> > +          - description: FIXME
> > +          - description: FIXME
>
>          - description: The offset of the tamp register
>          - description: The field mask of the Cortex-M4 resource table address
>
> Please tell me if you prefer that I fix this in a dedicated patch.

Thanks! I'll fold this into this patch.

Rob