Re: [PATCH 2/8] media: dt-bindings: renesas,rzg2l-csi2: Document Renesas RZ/V2H(P) SoC

[Rob Herring <robh@kernel.org>]

On Wed, Feb 19, 2025 at 05:12:37PM +0200, Laurent Pinchart wrote:
> On Wed, Feb 19, 2025 at 08:51:39AM -0600, Rob Herring wrote:
> > On Fri, Feb 14, 2025 at 02:29:51AM +0200, Laurent Pinchart wrote:
> > > Hi Tommaso, Prabhakar,
> > > 
> > > Thank you for the patch.
> > > 
> > > On Mon, Feb 10, 2025 at 12:45:34PM +0100, Tommaso Merciai wrote:
> > > > From: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> > > > 
> > > > The MIPI CSI-2 block on the Renesas RZ/V2H(P) SoC is similar to the one
> > > > found on the Renesas RZ/G2L SoC, with the following differences:
> > > > - A different D-PHY
> > > > - Additional registers for the MIPI CSI-2 link
> > > > - Only two clocks
> > > > 
> > > > Add a new compatible string, `renesas,r9a09g057-csi2`, for the RZ/V2H(P)
> > > > SoC.
> > > > 
> > > > Signed-off-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com>
> > > > Signed-off-by: Tommaso Merciai <tommaso.merciai.xr@bp.renesas.com>
> > > > ---
> > > >  .../bindings/media/renesas,rzg2l-csi2.yaml    | 63 ++++++++++++++-----
> > > >  1 file changed, 48 insertions(+), 15 deletions(-)
> > > > 
> > > > diff --git a/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml b/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml
> > > > index 7faa12fecd5b..0d07c55a3f35 100644
> > > > --- a/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml
> > > > +++ b/Documentation/devicetree/bindings/media/renesas,rzg2l-csi2.yaml
> > > > @@ -17,12 +17,15 @@ description:
> > > >  
> > > >  properties:
> > > >    compatible:
> > > > -    items:
> > > > -      - enum:
> > > > -          - renesas,r9a07g043-csi2       # RZ/G2UL
> > > > -          - renesas,r9a07g044-csi2       # RZ/G2{L,LC}
> > > > -          - renesas,r9a07g054-csi2       # RZ/V2L
> > > > -      - const: renesas,rzg2l-csi2
> > > > +    oneOf:
> > > > +      - items:
> > > > +          - enum:
> > > > +              - renesas,r9a07g043-csi2 # RZ/G2UL
> > > > +              - renesas,r9a07g044-csi2 # RZ/G2{L,LC}
> > > > +              - renesas,r9a07g054-csi2 # RZ/V2L
> > > > +          - const: renesas,rzg2l-csi2
> > > > +
> > > 
> > > I'd drop the empty line.
> > > 
> > > > +      - const: renesas,r9a09g057-csi2 # RZ/V2H(P)
> > > >  
> > > >    reg:
> > > >      maxItems: 1
> > > > @@ -31,16 +34,24 @@ properties:
> > > >      maxItems: 1
> > > >  
> > > >    clocks:
> > > > -    items:
> > > > -      - description: Internal clock for connecting CRU and MIPI
> > > > -      - description: CRU Main clock
> > > > -      - description: CRU Register access clock
> > > > +    oneOf:
> > > > +      - items:
> > > > +          - description: Internal clock for connecting CRU and MIPI
> > > > +          - description: CRU Main clock
> > > > +          - description: CRU Register access clock
> > > > +      - items:
> > > > +          - description: CRU Main clock
> > > > +          - description: CRU Register access clock
> > > >  
> > > >    clock-names:
> > > > -    items:
> > > > -      - const: system
> > > > -      - const: video
> > > > -      - const: apb
> > > > +    oneOf:
> > > > +      - items:
> > > > +          - const: system
> > > > +          - const: video
> > > > +          - const: apb
> > > > +      - items:
> > > > +          - const: video
> > > > +          - const: apb
> > > 
> > > I would move the clocks and clock-names definitions to the conditional
> > > below. Otherwise I think a device tree that has two clocks only but
> > > incorrectly uses "system" and "video" instead of "video" and "apb" will
> > > validate.
> > 
> > No, that wouldn't be allowed. The preference is to have it like this 
> > because it discourages creating more variations. If the names are all 
> > defined in if/then schema, then you can just add a new one with any 
> > names you want. Though if the variations become such a mess, then 
> > defining them in the if/then schemas would probably be better.
> > 
> > It would be better if 'clocks' could be reworked to avoid the 'oneOf' 
> > though (oneOf == poor error messages). It just needs a 'minItems: 2' 
> > added and the descriptions reworded for both cases.
> 
> Don't the items in clocks need to match the items in clock-names ? We
> can't reorder clock-names items as that would be an ABI breakage, so we
> can't reorder clocks items either.

Validation wise, the only thing we check is is it 2 or 3 entries. No way 
to enforce it's the right clock. The description is just for humans. So 
you could just put "(optional)" on the first entry though there is no 
way in json-schema to really do that. If you prefer as-is with the 
oneOf, that's fine too.

Rob