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;
Content-Type: text/plain;
        charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.21\))
Subject: Re: [PATCH v4 03/10] dt-bindings: display: Add ingenic,jz4780-dw-hdmi
 DT Schema
From:   "H. Nikolaus Schaller" <hns@goldelico.com>
In-Reply-To: <20210928091807.xgqxemjizlobpcxy@gilmour>
Date:   Tue, 28 Sep 2021 11:34:22 +0200
Cc:     Sam Ravnborg <sam@ravnborg.org>,
        Laurent Pinchart <Laurent.pinchart@ideasonboard.com>,
        Paul Cercueil <paul@crapouillou.net>,
        Rob Herring <robh+dt@kernel.org>,
        Mark Rutland <mark.rutland@arm.com>,
        Thomas Bogendoerfer <tsbogend@alpha.franken.de>,
        Geert Uytterhoeven <geert+renesas@glider.be>,
        Kees Cook <keescook@chromium.org>,
        "Eric W. Biederman" <ebiederm@xmission.com>,
        Miquel Raynal <miquel.raynal@bootlin.com>,
        David Airlie <airlied@linux.ie>,
        Daniel Vetter <daniel@ffwll.ch>,
        Andrzej Hajda <a.hajda@samsung.com>,
        Neil Armstrong <narmstrong@baylibre.com>,
        Robert Foss <robert.foss@linaro.org>,
        Jernej Skrabec <jernej.skrabec@gmail.com>,
        Ezequiel Garcia <ezequiel@collabora.com>,
        Harry Wentland <harry.wentland@amd.com>,
        Hans Verkuil <hverkuil-cisco@xs4all.nl>,
        Liam Girdwood <lgirdwood@gmail.com>,
        Mark Brown <broonie@kernel.org>,
        Paul Boddie <paul@boddie.org.uk>,
        "open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS" 
        <devicetree@vger.kernel.org>,
        linux-mips <linux-mips@vger.kernel.org>,
        linux-kernel <linux-kernel@vger.kernel.org>,
        Discussions about the Letux Kernel 
        <letux-kernel@openphoenux.org>, Jonas Karlman <jonas@kwiboo.se>,
        dri-devel <dri-devel@lists.freedesktop.org>,
        Rob Herring <robh@kernel.org>
Content-Transfer-Encoding: quoted-printable
Message-Id: <A17F7F48-5A3E-4F23-8C40-156275F5AEEE@goldelico.com>
References: <cover.1632761067.git.hns@goldelico.com>
 <6c8b72a03703de54fa02b29c1a53c84ca0889e50.1632761067.git.hns@goldelico.com>
 <20210927170702.on243lp24fcfdhbj@gilmour>
 <C529DB99-709A-4C24-B647-3A2004CBFE18@goldelico.com>
 <20210928091807.xgqxemjizlobpcxy@gilmour>
To:     Maxime Ripard <maxime@cerno.tech>
Precedence: bulk


> Am 28.09.2021 um 11:18 schrieb Maxime Ripard <maxime@cerno.tech>:
>=20
> On Tue, Sep 28, 2021 at 10:59:45AM +0200, H. Nikolaus Schaller wrote:
>>>> +properties:
>>>> +  compatible:
>>>> +    items:
>>>> +      - const: ingenic,jz4780-dw-hdmi
>>>=20
>>> This can just be a const, there's no need for the items
>>=20
>> Maybe starting with an enum is better if more compatible strings are =
to be added.
>=20
> it's still fairly easy to change if needed, there's no need to confuse
> anyone.
>=20
>>>=20
>>>> +  reg-io-width:
>>>> +    const: 4
>>>=20
>>> If it's fixed, why do you need it in the first place?
>>=20
>> There is a fixed default of 1 if not specified.
>=20
> My point was more about why do you need to have that property at all?
> Can't you just drop it and assume that the register width is 32 bits =
if
> it's all you will ever run on?

No, please see bridge/synopsys,dw-hdmi.yaml where it is derived from:

  reg-io-width:
    description:
      Width (in bytes) of the registers specified by the reg property.
    allOf:
      - $ref: /schemas/types.yaml#/definitions/uint32
      - enum: [1, 4]
    default: 1

Other bindings define it explicitly to be 4, e.g.

Documentation//devicetree/bindings/display/intel,keembay-msscam.yaml:  =
reg-io-width:
=
Documentation//devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml:=
  reg-io-width:

Therefore I'd assume that a regmap is not properly set up
if we don't require the DTS to include it with const: 4.

>=20
>>>> +  clocks:
>>>> +    maxItems: 2
>>>> +    description: Clock specifiers for isrf and iahb clocks
>>>=20
>>> This can be defined as
>>>=20
>>> clocks:
>>> items:
>>>   - description: isrf
>>>   - description: iahb
>>>=20
>>> A better description about what these clocks are would be nice as =
well
>>=20
>> Generally I see that this all is nowadays not independent of
>>=20
>> =
Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml
>>=20
>> where there is already a description.
>=20
> Ok, good then
>=20
>> On the other hand every SoC specialization runs its own copy. e.g.
>>=20
>> Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml
>> =
Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yam
>>=20
>>>=20
>>>> +  clock-names:
>>>> +    items:
>>>> +      - const: isfr
>>>=20
>>> Is it isfr or isrf?
>>=20
>> isfr. Seems to be a typo in the description. See
>> bridge/synopsys,dw-hdmi.yaml#
>>=20
>> One question to the yaml specialists:
>>=20
>> since ../bridge/synopsys,dw-hdmi.yaml# already defines this, do we
>> have to repeat? Or can we reduce to just the changes?
>=20
> If you add the ref you mentionned above, you don't have to repeat

Nice. It defines:

  clocks:
    minItems: 2
    maxItems: 5
    items:
      - description: The bus clock for either AHB and APB
      - description: The internal register configuration clock
    additionalItems: true

> yourself indeed. You can just put clock-names: true

Or should we do

  clocks:
    maxItems: 2
    additionalItems: false

>=20
>> [I am still not familiar enough with the yaml stuff to understand if
>> it has sort of inheritance like device tree include files, so that =
you
>> just have to change relevant properties]
>=20
> Kind of, but not entirely. schemas are all applied separately, unlike =
DT
> includes that will just expand to one big DT. In practice, it means =
that
> your device must validate against all the schemas, not just the sum of
> them.
>=20
> For example, if you have a generic schema that has:
>=20
> properties:
>  compatible:
>    const: vendor,my-generic-compatible
>=20
>=20
> and your schema that extends the generic binding, with a ref to the
> generic one that has:
>=20
> properties:
>  compatible:
>    items:
>      - const: other-vendor,my-device-compatible
>      - const: vendor,my-generic-compatible
>=20
>=20
> It will still fail since the generic schema expects only a single
> compatible, whereas your device would have two.

Ok, I see. it is not a simple "overwrite" rule.

>=20
>>>=20
>>>> +      - const: iahb
>>=20
>> would it make sense to add additionalItems: false here?
>>=20
>> In the jz4780 case there are just two clocks while other =
specializations
>> use more and synopsys,dw-hdmi.yaml# defines additionalItems: true.
>=20
> If you want to refine the generic one, and it's all the clocks you =
ever
> expect then there's no need for additionalItems

Ok.

>=20
>>>=20
>>>> +    description: An I2C interface if the internal DDC I2C driver =
is not to be used
>>>> +  ports: true
>>>=20
>>> If there's a single port, you don't need ports
>>=20
>> There can be two ports - one for input from LCDC and one
>> for output (HDMI connector). But explicitly defining an output
>> port is optional to some extent (depending on driver structure).
>=20
> This needs to be defined then (and port@0 made mandatory)

Ok. I'll try to make the best out of it for v5 series. Maybe
it is still not perfect by then, but close...

>=20
> Maxime

BR and thanks,
Nikolaus