[PATCH v4 08/13] dt-bindings: display: Document dual-link LVDS display common properties

[Liu Ying]

On 10/29/2024, Biju Das wrote:
> Hi Liu Ying,

Hi Biju,

> 
>> -----Original Message-----
>> From: dri-devel <dri-devel-bounces at lists.freedesktop.org> On Behalf Of Liu Ying
>> Sent: 29 October 2024 08:02
>> Subject: Re: [PATCH v4 08/13] dt-bindings: display: Document dual-link LVDS display common properties
>>
>> On 10/29/2024, Biju Das wrote:
>>> Hi Liu Ying,
>>
>> Hi Biju,
>>
>>>
>>>> -----Original Message-----
>>>> From: Liu Ying <victor.liu at nxp.com>
>>>> Sent: 28 October 2024 02:38
>>>> Subject: [PATCH v4 08/13] dt-bindings: display: Document dual-link
>>>> LVDS display common properties
>>>>
>>>> Dual-link LVDS displays receive odd pixels and even pixels separately
>>>> from dual LVDS links.  One link receives odd pixels and the other
>>>> receives even pixels.  Some of those displays may also use only one
>>>> LVDS link to receive all pixels, being odd and even agnostic.  Document common properties for those
>> displays by extending LVDS display common properties defined in lvds.yaml.
>>>>
>>>> Suggested-by: Dmitry Baryshkov <dmitry.baryshkov at linaro.org>
>>>> Signed-off-by: Liu Ying <victor.liu at nxp.com>
>>>> ---
>>>> v4:
>>>> * Squash change for advantech,idk-2121wr.yaml and
>>>>   panel-simple-lvds-dual-ports.yaml with lvds-dual-ports.yaml.  (Rob)
>>>> * Improve description in lvds-dual-ports.yaml.  (Krzysztof)
>>>>
>>>> v3:
>>>> * New patch.  (Dmitry)
>>>>
>>>>  .../bindings/display/lvds-dual-ports.yaml     | 76 +++++++++++++++++++
>>>>  .../display/panel/advantech,idk-2121wr.yaml   | 14 +---
>>>>  .../panel/panel-simple-lvds-dual-ports.yaml   | 20 +----
>>>>  3 files changed, 78 insertions(+), 32 deletions(-)  create mode
>>>> 100644 Documentation/devicetree/bindings/display/lvds-dual-ports.yaml
>>>>
>>>> diff --git
>>>> a/Documentation/devicetree/bindings/display/lvds-dual-ports.yaml
>>>> b/Documentation/devicetree/bindings/display/lvds-dual-ports.yaml
>>>> new file mode 100644
>>>> index 000000000000..5f7a30640404
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/display/lvds-dual-ports.yaml
>>>> @@ -0,0 +1,76 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
>>>> +---
>>>> +$id: http://devicetree.org/schemas/display/lvds-dual-ports.yaml#
>>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>>> +
>>>> +title: Dual-link LVDS Display Common Properties
>>>> +
>>>> +maintainers:
>>>> +  - Liu Ying <victor.liu at nxp.com>
>>>> +
>>>> +description: |
>>>> +  Common properties for LVDS displays with dual LVDS links. Extend
>>>> +LVDS display
>>>> +  common properties defined in lvds.yaml.
>>>> +
>>>> +  Dual-link LVDS displays receive odd pixels and even pixels
>>>> + separately from  the dual LVDS links. One link receives odd pixels
>>>> + and the other receives  even pixels. Some of those displays may
>>>> + also use only one LVDS link to  receive all pixels, being odd and even agnostic.
>>>> +
>>>> +allOf:
>>>> +  - $ref: lvds.yaml#
>>>> +
>>>> +properties:
>>>> +  ports:
>>>> +    $ref: /schemas/graph.yaml#/properties/ports
>>>> +
>>>> +    properties:
>>>> +      port at 0:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: the first LVDS input link
>>>> +
>>>> +        properties:
>>>> +          dual-lvds-odd-pixels:
>>>> +            type: boolean
>>>> +            description: the first LVDS input link for odd pixels
>>>> +
>>>> +          dual-lvds-even-pixels:
>>>> +            type: boolean
>>>> +            description: the first LVDS input link for even pixels
>>>
>>>
>>> port at 0 we know it is first link
>>> port at 1 we know it is second link.
>>> dual-lvds-odd-pixels: We know it is for odd pixels.
>>> dual-lvds-even-pixels: We know it is for odd pixels.
>>>
>>> Not sure, whether we can give common description and avoid the
>>> duplicate from port at 1 ??
>>
>> Yes, it'd better to use patternProperties. Thanks.
>>
>> --8<--
>>     patternProperties:
>>       '^port@[01]$':
>>         $ref: /schemas/graph.yaml#/$defs/port-base
>>         unevaluatedProperties: false
>>         description: |
>>           port at 0 is for the first LVDS input link.
>>           port at 1 is for the second LVDS input link.
>>
>>         properties:
>>           dual-lvds-odd-pixels:
>>             type: boolean
>>             description: LVDS input link for odd pixels
>>
>>           dual-lvds-even-pixels:
>>             type: boolean
>>             description: LVDS input link for even pixels
>>
>>         oneOf:
>>           - required: [dual-lvds-odd-pixels]
>>           - required: [dual-lvds-even-pixels]
>>           - properties:
>>               dual-lvds-odd-pixels: false
>>               dual-lvds-even-pixels: false
>>
>>     anyOf:
>>       - required:
>>           - port at 0
>>       - required:
>>           - port at 1
>> --8<--
>>
>>>
>>>
>>>> +
>>>> +        oneOf:
>>>> +          - required: [dual-lvds-odd-pixels]
>>>> +          - required: [dual-lvds-even-pixels]
>>>> +          - properties:
>>>> +              dual-lvds-odd-pixels: false
>>>> +              dual-lvds-even-pixels: false
>>>
>>> Why this is false here? oneOf is not sufficient?
>>
>> The 'false' is used when this LVDS link works alone as a single LVDS link, being odd and even
>> agnostic.
>>
>> The 'oneOf' allows a LVDS link to be defined as a single LVDS link or one link of dual LVDS links.
> 
> Ok, it makes sense for single LVDS link. Maybe rename the file to lvds-dual-ports.yaml->lvds-ports.yaml
> to make it clear, it is for all LVDS ports, if it is going to address single link case aswell??

Single-link LVDS displays are supposed to be documented
without referencing this schema, i.e., they may reference
lvds.yaml and define the single LVDS sink link with port
property(for panels) or port at 0 property(for bridges).
port at 1 would be defined as output port for bridges, not
input port.  Maybe, we'll have something like
lvds-single-port.yaml in the future.

> 
> Cheers,
> Biju
> 

-- 
Regards,
Liu Ying