[v6,5/8] dt-bindings: media: add TI DS90UB960 FPD-Link III Deserializer

Message ID 20230105140307.272052-6-tomi.valkeinen@ideasonboard.com
State New
Headers
Series i2c-atr and FPDLink |

Commit Message

Tomi Valkeinen Jan. 5, 2023, 2:03 p.m. UTC
  Add DT bindings for TI DS90UB960 FPD-Link III Deserializer.

Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
Reviewed-by: Rob Herring <robh@kernel.org>
---
 .../bindings/media/i2c/ti,ds90ub960.yaml      | 402 ++++++++++++++++++
 1 file changed, 402 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
  

Comments

Laurent Pinchart Jan. 8, 2023, 3:23 a.m. UTC | #1
Hi Tomi,

Thank you for the patch.

On Thu, Jan 05, 2023 at 04:03:04PM +0200, Tomi Valkeinen wrote:
> Add DT bindings for TI DS90UB960 FPD-Link III Deserializer.
> 
> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> Reviewed-by: Rob Herring <robh@kernel.org>
> ---
>  .../bindings/media/i2c/ti,ds90ub960.yaml      | 402 ++++++++++++++++++
>  1 file changed, 402 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> 
> diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> new file mode 100644
> index 000000000000..664799ae55be
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> @@ -0,0 +1,402 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
> +
> +maintainers:
> +  - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> +
> +description:
> +  The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
> +  forwarding.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - ti,ds90ub960-q1
> +      - ti,ds90ub9702-q1
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +    description:
> +      Reference clock connected to the REFCLK pin.
> +
> +  clock-names:
> +    items:
> +      - const: refclk
> +
> +  powerdown-gpios:
> +    maxItems: 1
> +    description:
> +      Specifier for the GPIO connected to the PDB pin.
> +
> +  i2c-alias-pool:
> +    $ref: /schemas/types.yaml#/definitions/uint16-array
> +    description:
> +      I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
> +      used to access the remote peripherals on the serializer's I2C bus. The
> +      addresses must be available, not used by any other peripheral. Each
> +      remote peripheral is assigned an alias from the pool, and transactions to
> +      that address will be forwarded to the remote peripheral, with the address
> +      translated to the remote peripheral's real address. This property is not
> +      needed if there are no I2C addressable remote peripherals.
> +
> +  links:
> +    type: object
> +    additionalProperties: false
> +
> +    properties:
> +      '#address-cells':
> +        const: 1
> +
> +      '#size-cells':
> +        const: 0
> +
> +      ti,manual-strobe:
> +        type: boolean
> +        description:
> +          Enable manual strobe position and EQ level
> +
> +    patternProperties:
> +      '^link@[0-3]$':
> +        type: object
> +        additionalProperties: false
> +        properties:
> +          reg:
> +            description: The link number
> +            maxItems: 1
> +
> +          i2c-alias:
> +            description:
> +              The I2C address used for the serializer. Transactions to this
> +              address on the I2C bus where the deserializer resides are
> +              forwarded to the serializer.
> +
> +          ti,rx-mode:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            enum:
> +              - 0 # RAW10
> +              - 1 # RAW12 HF
> +              - 2 # RAW12 LF
> +              - 3 # CSI2 SYNC
> +              - 4 # CSI2 NON-SYNC
> +            description:
> +              FPD-Link Input Mode. This should reflect the hardware and the
> +              default mode of the connected camera module.

As the remote device may not be a camera, I'd write "of the connected
device" or "of the connected serializer".

> +
> +          ti,cdr-mode:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            enum:
> +              - 0 # FPD-Link III
> +              - 1 # FPD-Link IV
> +            description:
> +              FPD-Link CDR Mode. This should reflect the hardware and the
> +              default mode of the connected camera module.
> +
> +          ti,strobe-pos:
> +            $ref: /schemas/types.yaml#/definitions/int32
> +            minimum: -13
> +            maximum: 13
> +            description: Manual strobe position
> +
> +          ti,eq-level:
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +            maximum: 14
> +            description: Manual EQ level
> +
> +          serializer:
> +            type: object
> +            description: FPD-Link Serializer node
> +
> +        required:
> +          - reg
> +          - i2c-alias
> +          - ti,rx-mode
> +          - serializer
> +
> +  ports:
> +    $ref: /schemas/graph.yaml#/properties/ports
> +
> +    properties:
> +      port@0:
> +        $ref: /schemas/graph.yaml#/$defs/port-base
> +        unevaluatedProperties: false
> +        description: FPD-Link input 0
> +
> +        properties:
> +          endpoint:
> +            $ref: /schemas/media/video-interfaces.yaml#
> +            unevaluatedProperties: false
> +            description:
> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> +              hsync-active and vsync-active must be defined.
> +
> +      port@1:
> +        $ref: /schemas/graph.yaml#/$defs/port-base
> +        unevaluatedProperties: false
> +        description: FPD-Link input 1
> +
> +        properties:
> +          endpoint:
> +            $ref: /schemas/media/video-interfaces.yaml#
> +            unevaluatedProperties: false
> +            description:
> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> +              hsync-active and vsync-active must be defined.
> +
> +      port@2:
> +        $ref: /schemas/graph.yaml#/$defs/port-base
> +        unevaluatedProperties: false
> +        description: FPD-Link input 2
> +
> +        properties:
> +          endpoint:
> +            $ref: /schemas/media/video-interfaces.yaml#
> +            unevaluatedProperties: false
> +            description:
> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> +              hsync-active and vsync-active must be defined.
> +
> +      port@3:
> +        $ref: /schemas/graph.yaml#/$defs/port-base
> +        unevaluatedProperties: false
> +        description: FPD-Link input 3
> +
> +        properties:
> +          endpoint:
> +            $ref: /schemas/media/video-interfaces.yaml#
> +            unevaluatedProperties: false
> +            description:
> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> +              hsync-active and vsync-active must be defined.
> +
> +      port@4:
> +        $ref: /schemas/graph.yaml#/$defs/port-base
> +        unevaluatedProperties: false
> +        description: CSI-2 Output 0
> +
> +        properties:
> +          endpoint:
> +            $ref: /schemas/media/video-interfaces.yaml#
> +            unevaluatedProperties: false
> +
> +            properties:
> +              data-lanes:
> +                minItems: 1
> +                maxItems: 4
> +
> +            required:
> +              - data-lanes
> +
> +      port@5:
> +        $ref: /schemas/graph.yaml#/$defs/port-base
> +        unevaluatedProperties: false
> +        description: CSI-2 Output 1
> +
> +        properties:
> +          endpoint:
> +            $ref: /schemas/media/video-interfaces.yaml#
> +            unevaluatedProperties: false
> +
> +            properties:
> +              data-lanes:
> +                minItems: 1
> +                maxItems: 4
> +
> +            required:
> +              - data-lanes

I think you need

    required:
      - port@0
      - port@1
      - port@2
      - port@3
      - port@4
      - port@5

> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - clock-names
> +  - ports
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    i2c {
> +      clock-frequency = <400000>;
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      deser@3d {
> +        compatible = "ti,ds90ub960-q1";
> +        reg = <0x3d>;
> +
> +        clock-names = "refclk";
> +        clocks = <&fixed_clock>;
> +
> +        powerdown-gpios = <&pca9555 7 GPIO_ACTIVE_LOW>;
> +
> +        i2c-alias-pool = /bits/ 16 <0x4a 0x4b 0x4c 0x4d 0x4e 0x4f>;
> +
> +        ports {
> +          #address-cells = <1>;
> +          #size-cells = <0>;
> +
> +          /* Port 0, Camera 0 */
> +          port@0 {
> +            reg = <0>;
> +
> +            ub960_fpd3_1_in: endpoint {
> +              remote-endpoint = <&ub953_1_out>;
> +            };
> +          };
> +
> +          /* Port 1, Camera 1 */
> +          port@1 {
> +            reg = <1>;
> +
> +            ub960_fpd3_2_in: endpoint {
> +              remote-endpoint = <&ub913_2_out>;
> +              hsync-active = <0>;
> +              vsync-active = <1>;
> +            };
> +          };
> +
> +          /* Port 4, CSI-2 TX */
> +          port@4 {
> +            reg = <4>;
> +            ds90ub960_0_csi_out: endpoint {
> +              data-lanes = <1 2 3 4>;
> +              link-frequencies = /bits/ 64 <800000000>;
> +              remote-endpoint = <&csi2_phy0>;
> +            };
> +          };
> +        };
> +
> +        links {
> +          #address-cells = <1>;
> +          #size-cells = <0>;
> +
> +          /* Link 0 has DS90UB953 serializer and IMX274 sensor */
> +
> +          link@0 {
> +            reg = <0>;
> +            i2c-alias = <0x44>;
> +
> +            ti,rx-mode = <3>;
> +
> +            serializer1: serializer {
> +              compatible = "ti,ds90ub953-q1";
> +
> +              gpio-controller;
> +              #gpio-cells = <2>;
> +
> +              #clock-cells = <0>;
> +
> +              ports {
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                port@0 {
> +                  reg = <0>;
> +                  ub953_1_in: endpoint {
> +                    data-lanes = <1 2 3 4>;
> +                    remote-endpoint = <&sensor_1_out>;
> +                  };
> +                };
> +
> +                port@1 {
> +                  reg = <1>;
> +
> +                  ub953_1_out: endpoint {
> +                    remote-endpoint = <&ub960_fpd3_1_in>;
> +                  };
> +                };
> +              };
> +
> +              i2c {
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                sensor@1a {
> +                  compatible = "sony,imx274";
> +                  reg = <0x1a>;
> +
> +                  reset-gpios = <&serializer1 0 GPIO_ACTIVE_LOW>;
> +
> +                  port {
> +                    sensor_1_out: endpoint {
> +                      remote-endpoint = <&ub953_1_in>;
> +                    };
> +                  };
> +                };
> +              };
> +            };
> +          };  /* End of link@0 */
> +
> +          /* Link 1 has DS90UB913 serializer and MT9V111 sensor */
> +
> +          link@1 {
> +            reg = <1>;
> +            i2c-alias = <0x45>;
> +
> +            ti,rx-mode = <0>;
> +
> +            serializer2: serializer {
> +              compatible = "ti,ds90ub913a-q1";
> +
> +              gpio-controller;
> +              #gpio-cells = <2>;
> +
> +              clocks = <&clk_cam_48M>;
> +              clock-names = "clkin";
> +
> +              #clock-cells = <0>;
> +
> +              ports {
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                port@0 {
> +                  reg = <0>;
> +                  ub913_2_in: endpoint {
> +                    remote-endpoint = <&sensor_2_out>;
> +                    pclk-sample = <1>;
> +                  };
> +                };
> +
> +                port@1 {
> +                  reg = <1>;
> +
> +                  ub913_2_out: endpoint {
> +                    remote-endpoint = <&ub960_fpd3_2_in>;
> +                  };
> +                };
> +              };
> +
> +              i2c {
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                sensor@48 {
> +                  compatible = "aptina,mt9v111";
> +                  reg = <0x48>;
> +
> +                  clocks = <&serializer2>;
> +
> +                  port {
> +                    sensor_2_out: endpoint {
> +                      remote-endpoint = <&ub913_2_in>;
> +                    };
> +                  };
> +                };
> +              };
> +            };
> +          }; /* End of link@1 */
> +        };
> +      };
> +    };
> +...
  
Tomi Valkeinen Jan. 9, 2023, 8:30 a.m. UTC | #2
On 08/01/2023 05:23, Laurent Pinchart wrote:
> Hi Tomi,
> 
> Thank you for the patch.
> 
> On Thu, Jan 05, 2023 at 04:03:04PM +0200, Tomi Valkeinen wrote:
>> Add DT bindings for TI DS90UB960 FPD-Link III Deserializer.
>>
>> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
>> Reviewed-by: Rob Herring <robh@kernel.org>
>> ---
>>   .../bindings/media/i2c/ti,ds90ub960.yaml      | 402 ++++++++++++++++++
>>   1 file changed, 402 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
>> new file mode 100644
>> index 000000000000..664799ae55be
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
>> @@ -0,0 +1,402 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
>> +
>> +maintainers:
>> +  - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
>> +
>> +description:
>> +  The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
>> +  forwarding.
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - ti,ds90ub960-q1
>> +      - ti,ds90ub9702-q1
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  clocks:
>> +    maxItems: 1
>> +    description:
>> +      Reference clock connected to the REFCLK pin.
>> +
>> +  clock-names:
>> +    items:
>> +      - const: refclk
>> +
>> +  powerdown-gpios:
>> +    maxItems: 1
>> +    description:
>> +      Specifier for the GPIO connected to the PDB pin.
>> +
>> +  i2c-alias-pool:
>> +    $ref: /schemas/types.yaml#/definitions/uint16-array
>> +    description:
>> +      I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
>> +      used to access the remote peripherals on the serializer's I2C bus. The
>> +      addresses must be available, not used by any other peripheral. Each
>> +      remote peripheral is assigned an alias from the pool, and transactions to
>> +      that address will be forwarded to the remote peripheral, with the address
>> +      translated to the remote peripheral's real address. This property is not
>> +      needed if there are no I2C addressable remote peripherals.
>> +
>> +  links:
>> +    type: object
>> +    additionalProperties: false
>> +
>> +    properties:
>> +      '#address-cells':
>> +        const: 1
>> +
>> +      '#size-cells':
>> +        const: 0
>> +
>> +      ti,manual-strobe:
>> +        type: boolean
>> +        description:
>> +          Enable manual strobe position and EQ level
>> +
>> +    patternProperties:
>> +      '^link@[0-3]$':
>> +        type: object
>> +        additionalProperties: false
>> +        properties:
>> +          reg:
>> +            description: The link number
>> +            maxItems: 1
>> +
>> +          i2c-alias:
>> +            description:
>> +              The I2C address used for the serializer. Transactions to this
>> +              address on the I2C bus where the deserializer resides are
>> +              forwarded to the serializer.
>> +
>> +          ti,rx-mode:
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +            enum:
>> +              - 0 # RAW10
>> +              - 1 # RAW12 HF
>> +              - 2 # RAW12 LF
>> +              - 3 # CSI2 SYNC
>> +              - 4 # CSI2 NON-SYNC
>> +            description:
>> +              FPD-Link Input Mode. This should reflect the hardware and the
>> +              default mode of the connected camera module.
> 
> As the remote device may not be a camera, I'd write "of the connected
> device" or "of the connected serializer".

I was trying to include the sensor also in the "camera module", as the 
sensor's "normal" pixel cloud would affect RAW modes (HF/LF). Perhaps 
"connected device" covers this.

>> +
>> +          ti,cdr-mode:
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +            enum:
>> +              - 0 # FPD-Link III
>> +              - 1 # FPD-Link IV
>> +            description:
>> +              FPD-Link CDR Mode. This should reflect the hardware and the
>> +              default mode of the connected camera module.
>> +
>> +          ti,strobe-pos:
>> +            $ref: /schemas/types.yaml#/definitions/int32
>> +            minimum: -13
>> +            maximum: 13
>> +            description: Manual strobe position
>> +
>> +          ti,eq-level:
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +            maximum: 14
>> +            description: Manual EQ level
>> +
>> +          serializer:
>> +            type: object
>> +            description: FPD-Link Serializer node
>> +
>> +        required:
>> +          - reg
>> +          - i2c-alias
>> +          - ti,rx-mode
>> +          - serializer
>> +
>> +  ports:
>> +    $ref: /schemas/graph.yaml#/properties/ports
>> +
>> +    properties:
>> +      port@0:
>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>> +        unevaluatedProperties: false
>> +        description: FPD-Link input 0
>> +
>> +        properties:
>> +          endpoint:
>> +            $ref: /schemas/media/video-interfaces.yaml#
>> +            unevaluatedProperties: false
>> +            description:
>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>> +              hsync-active and vsync-active must be defined.
>> +
>> +      port@1:
>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>> +        unevaluatedProperties: false
>> +        description: FPD-Link input 1
>> +
>> +        properties:
>> +          endpoint:
>> +            $ref: /schemas/media/video-interfaces.yaml#
>> +            unevaluatedProperties: false
>> +            description:
>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>> +              hsync-active and vsync-active must be defined.
>> +
>> +      port@2:
>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>> +        unevaluatedProperties: false
>> +        description: FPD-Link input 2
>> +
>> +        properties:
>> +          endpoint:
>> +            $ref: /schemas/media/video-interfaces.yaml#
>> +            unevaluatedProperties: false
>> +            description:
>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>> +              hsync-active and vsync-active must be defined.
>> +
>> +      port@3:
>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>> +        unevaluatedProperties: false
>> +        description: FPD-Link input 3
>> +
>> +        properties:
>> +          endpoint:
>> +            $ref: /schemas/media/video-interfaces.yaml#
>> +            unevaluatedProperties: false
>> +            description:
>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>> +              hsync-active and vsync-active must be defined.
>> +
>> +      port@4:
>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>> +        unevaluatedProperties: false
>> +        description: CSI-2 Output 0
>> +
>> +        properties:
>> +          endpoint:
>> +            $ref: /schemas/media/video-interfaces.yaml#
>> +            unevaluatedProperties: false
>> +
>> +            properties:
>> +              data-lanes:
>> +                minItems: 1
>> +                maxItems: 4
>> +
>> +            required:
>> +              - data-lanes
>> +
>> +      port@5:
>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>> +        unevaluatedProperties: false
>> +        description: CSI-2 Output 1
>> +
>> +        properties:
>> +          endpoint:
>> +            $ref: /schemas/media/video-interfaces.yaml#
>> +            unevaluatedProperties: false
>> +
>> +            properties:
>> +              data-lanes:
>> +                minItems: 1
>> +                maxItems: 4
>> +
>> +            required:
>> +              - data-lanes
> 
> I think you need
> 
>      required:
>        - port@0
>        - port@1
>        - port@2
>        - port@3
>        - port@4
>        - port@5

Is that needed? I think often some of the ports are unused (e.g. the 
example in this yaml file). Is it customary to still require empty port 
nodes in the DT?

  Tomi
  
Laurent Pinchart Jan. 9, 2023, 9:09 a.m. UTC | #3
On Mon, Jan 09, 2023 at 10:30:13AM +0200, Tomi Valkeinen wrote:
> On 08/01/2023 05:23, Laurent Pinchart wrote:
> > Hi Tomi,
> > 
> > Thank you for the patch.
> > 
> > On Thu, Jan 05, 2023 at 04:03:04PM +0200, Tomi Valkeinen wrote:
> >> Add DT bindings for TI DS90UB960 FPD-Link III Deserializer.
> >>
> >> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> >> Reviewed-by: Rob Herring <robh@kernel.org>
> >> ---
> >>   .../bindings/media/i2c/ti,ds90ub960.yaml      | 402 ++++++++++++++++++
> >>   1 file changed, 402 insertions(+)
> >>   create mode 100644 Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> >>
> >> diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> >> new file mode 100644
> >> index 000000000000..664799ae55be
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> >> @@ -0,0 +1,402 @@
> >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
> >> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
> >> +
> >> +maintainers:
> >> +  - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> >> +
> >> +description:
> >> +  The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
> >> +  forwarding.
> >> +
> >> +properties:
> >> +  compatible:
> >> +    enum:
> >> +      - ti,ds90ub960-q1
> >> +      - ti,ds90ub9702-q1
> >> +
> >> +  reg:
> >> +    maxItems: 1
> >> +
> >> +  clocks:
> >> +    maxItems: 1
> >> +    description:
> >> +      Reference clock connected to the REFCLK pin.
> >> +
> >> +  clock-names:
> >> +    items:
> >> +      - const: refclk
> >> +
> >> +  powerdown-gpios:
> >> +    maxItems: 1
> >> +    description:
> >> +      Specifier for the GPIO connected to the PDB pin.
> >> +
> >> +  i2c-alias-pool:
> >> +    $ref: /schemas/types.yaml#/definitions/uint16-array
> >> +    description:
> >> +      I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
> >> +      used to access the remote peripherals on the serializer's I2C bus. The
> >> +      addresses must be available, not used by any other peripheral. Each
> >> +      remote peripheral is assigned an alias from the pool, and transactions to
> >> +      that address will be forwarded to the remote peripheral, with the address
> >> +      translated to the remote peripheral's real address. This property is not
> >> +      needed if there are no I2C addressable remote peripherals.
> >> +
> >> +  links:
> >> +    type: object
> >> +    additionalProperties: false
> >> +
> >> +    properties:
> >> +      '#address-cells':
> >> +        const: 1
> >> +
> >> +      '#size-cells':
> >> +        const: 0
> >> +
> >> +      ti,manual-strobe:
> >> +        type: boolean
> >> +        description:
> >> +          Enable manual strobe position and EQ level
> >> +
> >> +    patternProperties:
> >> +      '^link@[0-3]$':
> >> +        type: object
> >> +        additionalProperties: false
> >> +        properties:
> >> +          reg:
> >> +            description: The link number
> >> +            maxItems: 1
> >> +
> >> +          i2c-alias:
> >> +            description:
> >> +              The I2C address used for the serializer. Transactions to this
> >> +              address on the I2C bus where the deserializer resides are
> >> +              forwarded to the serializer.
> >> +
> >> +          ti,rx-mode:
> >> +            $ref: /schemas/types.yaml#/definitions/uint32
> >> +            enum:
> >> +              - 0 # RAW10
> >> +              - 1 # RAW12 HF
> >> +              - 2 # RAW12 LF
> >> +              - 3 # CSI2 SYNC
> >> +              - 4 # CSI2 NON-SYNC
> >> +            description:
> >> +              FPD-Link Input Mode. This should reflect the hardware and the
> >> +              default mode of the connected camera module.
> > 
> > As the remote device may not be a camera, I'd write "of the connected
> > device" or "of the connected serializer".
> 
> I was trying to include the sensor also in the "camera module", as the 
> sensor's "normal" pixel cloud would affect RAW modes (HF/LF). Perhaps 
> "connected device" covers this.
> 
> >> +
> >> +          ti,cdr-mode:
> >> +            $ref: /schemas/types.yaml#/definitions/uint32
> >> +            enum:
> >> +              - 0 # FPD-Link III
> >> +              - 1 # FPD-Link IV
> >> +            description:
> >> +              FPD-Link CDR Mode. This should reflect the hardware and the
> >> +              default mode of the connected camera module.
> >> +
> >> +          ti,strobe-pos:
> >> +            $ref: /schemas/types.yaml#/definitions/int32
> >> +            minimum: -13
> >> +            maximum: 13
> >> +            description: Manual strobe position
> >> +
> >> +          ti,eq-level:
> >> +            $ref: /schemas/types.yaml#/definitions/uint32
> >> +            maximum: 14
> >> +            description: Manual EQ level
> >> +
> >> +          serializer:
> >> +            type: object
> >> +            description: FPD-Link Serializer node
> >> +
> >> +        required:
> >> +          - reg
> >> +          - i2c-alias
> >> +          - ti,rx-mode
> >> +          - serializer
> >> +
> >> +  ports:
> >> +    $ref: /schemas/graph.yaml#/properties/ports
> >> +
> >> +    properties:
> >> +      port@0:
> >> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >> +        unevaluatedProperties: false
> >> +        description: FPD-Link input 0
> >> +
> >> +        properties:
> >> +          endpoint:
> >> +            $ref: /schemas/media/video-interfaces.yaml#
> >> +            unevaluatedProperties: false
> >> +            description:
> >> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >> +              hsync-active and vsync-active must be defined.
> >> +
> >> +      port@1:
> >> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >> +        unevaluatedProperties: false
> >> +        description: FPD-Link input 1
> >> +
> >> +        properties:
> >> +          endpoint:
> >> +            $ref: /schemas/media/video-interfaces.yaml#
> >> +            unevaluatedProperties: false
> >> +            description:
> >> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >> +              hsync-active and vsync-active must be defined.
> >> +
> >> +      port@2:
> >> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >> +        unevaluatedProperties: false
> >> +        description: FPD-Link input 2
> >> +
> >> +        properties:
> >> +          endpoint:
> >> +            $ref: /schemas/media/video-interfaces.yaml#
> >> +            unevaluatedProperties: false
> >> +            description:
> >> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >> +              hsync-active and vsync-active must be defined.
> >> +
> >> +      port@3:
> >> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >> +        unevaluatedProperties: false
> >> +        description: FPD-Link input 3
> >> +
> >> +        properties:
> >> +          endpoint:
> >> +            $ref: /schemas/media/video-interfaces.yaml#
> >> +            unevaluatedProperties: false
> >> +            description:
> >> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >> +              hsync-active and vsync-active must be defined.
> >> +
> >> +      port@4:
> >> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >> +        unevaluatedProperties: false
> >> +        description: CSI-2 Output 0
> >> +
> >> +        properties:
> >> +          endpoint:
> >> +            $ref: /schemas/media/video-interfaces.yaml#
> >> +            unevaluatedProperties: false
> >> +
> >> +            properties:
> >> +              data-lanes:
> >> +                minItems: 1
> >> +                maxItems: 4
> >> +
> >> +            required:
> >> +              - data-lanes
> >> +
> >> +      port@5:
> >> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >> +        unevaluatedProperties: false
> >> +        description: CSI-2 Output 1
> >> +
> >> +        properties:
> >> +          endpoint:
> >> +            $ref: /schemas/media/video-interfaces.yaml#
> >> +            unevaluatedProperties: false
> >> +
> >> +            properties:
> >> +              data-lanes:
> >> +                minItems: 1
> >> +                maxItems: 4
> >> +
> >> +            required:
> >> +              - data-lanes
> > 
> > I think you need
> > 
> >      required:
> >        - port@0
> >        - port@1
> >        - port@2
> >        - port@3
> >        - port@4
> >        - port@5
> 
> Is that needed? I think often some of the ports are unused (e.g. the 
> example in this yaml file). Is it customary to still require empty port 
> nodes in the DT?

Ports are an intrinsic property of a device, they don't depend on the
device integration in the system. In this case, the UB960 has four
FPD-Link inputs and two CSI-2 outputs, that's a property of the chip.
They don't have to be connected to anything on the board, so endpooints
are optional.
  
Tomi Valkeinen Jan. 9, 2023, 9:53 a.m. UTC | #4
On 09/01/2023 11:09, Laurent Pinchart wrote:
> On Mon, Jan 09, 2023 at 10:30:13AM +0200, Tomi Valkeinen wrote:
>> On 08/01/2023 05:23, Laurent Pinchart wrote:
>>> Hi Tomi,
>>>
>>> Thank you for the patch.
>>>
>>> On Thu, Jan 05, 2023 at 04:03:04PM +0200, Tomi Valkeinen wrote:
>>>> Add DT bindings for TI DS90UB960 FPD-Link III Deserializer.
>>>>
>>>> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
>>>> Reviewed-by: Rob Herring <robh@kernel.org>
>>>> ---
>>>>    .../bindings/media/i2c/ti,ds90ub960.yaml      | 402 ++++++++++++++++++
>>>>    1 file changed, 402 insertions(+)
>>>>    create mode 100644 Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
>>>> new file mode 100644
>>>> index 000000000000..664799ae55be
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
>>>> @@ -0,0 +1,402 @@
>>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>>>> +%YAML 1.2
>>>> +---
>>>> +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
>>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>>>> +
>>>> +title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
>>>> +
>>>> +maintainers:
>>>> +  - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
>>>> +
>>>> +description:
>>>> +  The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
>>>> +  forwarding.
>>>> +
>>>> +properties:
>>>> +  compatible:
>>>> +    enum:
>>>> +      - ti,ds90ub960-q1
>>>> +      - ti,ds90ub9702-q1
>>>> +
>>>> +  reg:
>>>> +    maxItems: 1
>>>> +
>>>> +  clocks:
>>>> +    maxItems: 1
>>>> +    description:
>>>> +      Reference clock connected to the REFCLK pin.
>>>> +
>>>> +  clock-names:
>>>> +    items:
>>>> +      - const: refclk
>>>> +
>>>> +  powerdown-gpios:
>>>> +    maxItems: 1
>>>> +    description:
>>>> +      Specifier for the GPIO connected to the PDB pin.
>>>> +
>>>> +  i2c-alias-pool:
>>>> +    $ref: /schemas/types.yaml#/definitions/uint16-array
>>>> +    description:
>>>> +      I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
>>>> +      used to access the remote peripherals on the serializer's I2C bus. The
>>>> +      addresses must be available, not used by any other peripheral. Each
>>>> +      remote peripheral is assigned an alias from the pool, and transactions to
>>>> +      that address will be forwarded to the remote peripheral, with the address
>>>> +      translated to the remote peripheral's real address. This property is not
>>>> +      needed if there are no I2C addressable remote peripherals.
>>>> +
>>>> +  links:
>>>> +    type: object
>>>> +    additionalProperties: false
>>>> +
>>>> +    properties:
>>>> +      '#address-cells':
>>>> +        const: 1
>>>> +
>>>> +      '#size-cells':
>>>> +        const: 0
>>>> +
>>>> +      ti,manual-strobe:
>>>> +        type: boolean
>>>> +        description:
>>>> +          Enable manual strobe position and EQ level
>>>> +
>>>> +    patternProperties:
>>>> +      '^link@[0-3]$':
>>>> +        type: object
>>>> +        additionalProperties: false
>>>> +        properties:
>>>> +          reg:
>>>> +            description: The link number
>>>> +            maxItems: 1
>>>> +
>>>> +          i2c-alias:
>>>> +            description:
>>>> +              The I2C address used for the serializer. Transactions to this
>>>> +              address on the I2C bus where the deserializer resides are
>>>> +              forwarded to the serializer.
>>>> +
>>>> +          ti,rx-mode:
>>>> +            $ref: /schemas/types.yaml#/definitions/uint32
>>>> +            enum:
>>>> +              - 0 # RAW10
>>>> +              - 1 # RAW12 HF
>>>> +              - 2 # RAW12 LF
>>>> +              - 3 # CSI2 SYNC
>>>> +              - 4 # CSI2 NON-SYNC
>>>> +            description:
>>>> +              FPD-Link Input Mode. This should reflect the hardware and the
>>>> +              default mode of the connected camera module.
>>>
>>> As the remote device may not be a camera, I'd write "of the connected
>>> device" or "of the connected serializer".
>>
>> I was trying to include the sensor also in the "camera module", as the
>> sensor's "normal" pixel cloud would affect RAW modes (HF/LF). Perhaps
>> "connected device" covers this.
>>
>>>> +
>>>> +          ti,cdr-mode:
>>>> +            $ref: /schemas/types.yaml#/definitions/uint32
>>>> +            enum:
>>>> +              - 0 # FPD-Link III
>>>> +              - 1 # FPD-Link IV
>>>> +            description:
>>>> +              FPD-Link CDR Mode. This should reflect the hardware and the
>>>> +              default mode of the connected camera module.
>>>> +
>>>> +          ti,strobe-pos:
>>>> +            $ref: /schemas/types.yaml#/definitions/int32
>>>> +            minimum: -13
>>>> +            maximum: 13
>>>> +            description: Manual strobe position
>>>> +
>>>> +          ti,eq-level:
>>>> +            $ref: /schemas/types.yaml#/definitions/uint32
>>>> +            maximum: 14
>>>> +            description: Manual EQ level
>>>> +
>>>> +          serializer:
>>>> +            type: object
>>>> +            description: FPD-Link Serializer node
>>>> +
>>>> +        required:
>>>> +          - reg
>>>> +          - i2c-alias
>>>> +          - ti,rx-mode
>>>> +          - serializer
>>>> +
>>>> +  ports:
>>>> +    $ref: /schemas/graph.yaml#/properties/ports
>>>> +
>>>> +    properties:
>>>> +      port@0:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: FPD-Link input 0
>>>> +
>>>> +        properties:
>>>> +          endpoint:
>>>> +            $ref: /schemas/media/video-interfaces.yaml#
>>>> +            unevaluatedProperties: false
>>>> +            description:
>>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>>>> +              hsync-active and vsync-active must be defined.
>>>> +
>>>> +      port@1:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: FPD-Link input 1
>>>> +
>>>> +        properties:
>>>> +          endpoint:
>>>> +            $ref: /schemas/media/video-interfaces.yaml#
>>>> +            unevaluatedProperties: false
>>>> +            description:
>>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>>>> +              hsync-active and vsync-active must be defined.
>>>> +
>>>> +      port@2:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: FPD-Link input 2
>>>> +
>>>> +        properties:
>>>> +          endpoint:
>>>> +            $ref: /schemas/media/video-interfaces.yaml#
>>>> +            unevaluatedProperties: false
>>>> +            description:
>>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>>>> +              hsync-active and vsync-active must be defined.
>>>> +
>>>> +      port@3:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: FPD-Link input 3
>>>> +
>>>> +        properties:
>>>> +          endpoint:
>>>> +            $ref: /schemas/media/video-interfaces.yaml#
>>>> +            unevaluatedProperties: false
>>>> +            description:
>>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
>>>> +              hsync-active and vsync-active must be defined.
>>>> +
>>>> +      port@4:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: CSI-2 Output 0
>>>> +
>>>> +        properties:
>>>> +          endpoint:
>>>> +            $ref: /schemas/media/video-interfaces.yaml#
>>>> +            unevaluatedProperties: false
>>>> +
>>>> +            properties:
>>>> +              data-lanes:
>>>> +                minItems: 1
>>>> +                maxItems: 4
>>>> +
>>>> +            required:
>>>> +              - data-lanes
>>>> +
>>>> +      port@5:
>>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
>>>> +        unevaluatedProperties: false
>>>> +        description: CSI-2 Output 1
>>>> +
>>>> +        properties:
>>>> +          endpoint:
>>>> +            $ref: /schemas/media/video-interfaces.yaml#
>>>> +            unevaluatedProperties: false
>>>> +
>>>> +            properties:
>>>> +              data-lanes:
>>>> +                minItems: 1
>>>> +                maxItems: 4
>>>> +
>>>> +            required:
>>>> +              - data-lanes
>>>
>>> I think you need
>>>
>>>       required:
>>>         - port@0
>>>         - port@1
>>>         - port@2
>>>         - port@3
>>>         - port@4
>>>         - port@5
>>
>> Is that needed? I think often some of the ports are unused (e.g. the
>> example in this yaml file). Is it customary to still require empty port
>> nodes in the DT?
> 
> Ports are an intrinsic property of a device, they don't depend on the
> device integration in the system. In this case, the UB960 has four
> FPD-Link inputs and two CSI-2 outputs, that's a property of the chip.
> They don't have to be connected to anything on the board, so endpooints
> are optional.

Yes, but why do they have to be required? A missing port node implies 
that it's not used, doesn't it? I don't mind much, it just feels a bit 
extra to add multiple almost empty "port@X { reg = <X>; };" style nodes 
to the dts file.

  Tomi
  
Laurent Pinchart Jan. 9, 2023, 10:07 a.m. UTC | #5
On Mon, Jan 09, 2023 at 11:53:22AM +0200, Tomi Valkeinen wrote:
> On 09/01/2023 11:09, Laurent Pinchart wrote:
> > On Mon, Jan 09, 2023 at 10:30:13AM +0200, Tomi Valkeinen wrote:
> >> On 08/01/2023 05:23, Laurent Pinchart wrote:
> >>> Hi Tomi,
> >>>
> >>> Thank you for the patch.
> >>>
> >>> On Thu, Jan 05, 2023 at 04:03:04PM +0200, Tomi Valkeinen wrote:
> >>>> Add DT bindings for TI DS90UB960 FPD-Link III Deserializer.
> >>>>
> >>>> Signed-off-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> >>>> Reviewed-by: Rob Herring <robh@kernel.org>
> >>>> ---
> >>>>    .../bindings/media/i2c/ti,ds90ub960.yaml      | 402 ++++++++++++++++++
> >>>>    1 file changed, 402 insertions(+)
> >>>>    create mode 100644 Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> >>>>
> >>>> diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> >>>> new file mode 100644
> >>>> index 000000000000..664799ae55be
> >>>> --- /dev/null
> >>>> +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
> >>>> @@ -0,0 +1,402 @@
> >>>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >>>> +%YAML 1.2
> >>>> +---
> >>>> +$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
> >>>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >>>> +
> >>>> +title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
> >>>> +
> >>>> +maintainers:
> >>>> +  - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
> >>>> +
> >>>> +description:
> >>>> +  The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
> >>>> +  forwarding.
> >>>> +
> >>>> +properties:
> >>>> +  compatible:
> >>>> +    enum:
> >>>> +      - ti,ds90ub960-q1
> >>>> +      - ti,ds90ub9702-q1
> >>>> +
> >>>> +  reg:
> >>>> +    maxItems: 1
> >>>> +
> >>>> +  clocks:
> >>>> +    maxItems: 1
> >>>> +    description:
> >>>> +      Reference clock connected to the REFCLK pin.
> >>>> +
> >>>> +  clock-names:
> >>>> +    items:
> >>>> +      - const: refclk
> >>>> +
> >>>> +  powerdown-gpios:
> >>>> +    maxItems: 1
> >>>> +    description:
> >>>> +      Specifier for the GPIO connected to the PDB pin.
> >>>> +
> >>>> +  i2c-alias-pool:
> >>>> +    $ref: /schemas/types.yaml#/definitions/uint16-array
> >>>> +    description:
> >>>> +      I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
> >>>> +      used to access the remote peripherals on the serializer's I2C bus. The
> >>>> +      addresses must be available, not used by any other peripheral. Each
> >>>> +      remote peripheral is assigned an alias from the pool, and transactions to
> >>>> +      that address will be forwarded to the remote peripheral, with the address
> >>>> +      translated to the remote peripheral's real address. This property is not
> >>>> +      needed if there are no I2C addressable remote peripherals.
> >>>> +
> >>>> +  links:
> >>>> +    type: object
> >>>> +    additionalProperties: false
> >>>> +
> >>>> +    properties:
> >>>> +      '#address-cells':
> >>>> +        const: 1
> >>>> +
> >>>> +      '#size-cells':
> >>>> +        const: 0
> >>>> +
> >>>> +      ti,manual-strobe:
> >>>> +        type: boolean
> >>>> +        description:
> >>>> +          Enable manual strobe position and EQ level
> >>>> +
> >>>> +    patternProperties:
> >>>> +      '^link@[0-3]$':
> >>>> +        type: object
> >>>> +        additionalProperties: false
> >>>> +        properties:
> >>>> +          reg:
> >>>> +            description: The link number
> >>>> +            maxItems: 1
> >>>> +
> >>>> +          i2c-alias:
> >>>> +            description:
> >>>> +              The I2C address used for the serializer. Transactions to this
> >>>> +              address on the I2C bus where the deserializer resides are
> >>>> +              forwarded to the serializer.
> >>>> +
> >>>> +          ti,rx-mode:
> >>>> +            $ref: /schemas/types.yaml#/definitions/uint32
> >>>> +            enum:
> >>>> +              - 0 # RAW10
> >>>> +              - 1 # RAW12 HF
> >>>> +              - 2 # RAW12 LF
> >>>> +              - 3 # CSI2 SYNC
> >>>> +              - 4 # CSI2 NON-SYNC
> >>>> +            description:
> >>>> +              FPD-Link Input Mode. This should reflect the hardware and the
> >>>> +              default mode of the connected camera module.
> >>>
> >>> As the remote device may not be a camera, I'd write "of the connected
> >>> device" or "of the connected serializer".
> >>
> >> I was trying to include the sensor also in the "camera module", as the
> >> sensor's "normal" pixel cloud would affect RAW modes (HF/LF). Perhaps
> >> "connected device" covers this.
> >>
> >>>> +
> >>>> +          ti,cdr-mode:
> >>>> +            $ref: /schemas/types.yaml#/definitions/uint32
> >>>> +            enum:
> >>>> +              - 0 # FPD-Link III
> >>>> +              - 1 # FPD-Link IV
> >>>> +            description:
> >>>> +              FPD-Link CDR Mode. This should reflect the hardware and the
> >>>> +              default mode of the connected camera module.
> >>>> +
> >>>> +          ti,strobe-pos:
> >>>> +            $ref: /schemas/types.yaml#/definitions/int32
> >>>> +            minimum: -13
> >>>> +            maximum: 13
> >>>> +            description: Manual strobe position
> >>>> +
> >>>> +          ti,eq-level:
> >>>> +            $ref: /schemas/types.yaml#/definitions/uint32
> >>>> +            maximum: 14
> >>>> +            description: Manual EQ level
> >>>> +
> >>>> +          serializer:
> >>>> +            type: object
> >>>> +            description: FPD-Link Serializer node
> >>>> +
> >>>> +        required:
> >>>> +          - reg
> >>>> +          - i2c-alias
> >>>> +          - ti,rx-mode
> >>>> +          - serializer
> >>>> +
> >>>> +  ports:
> >>>> +    $ref: /schemas/graph.yaml#/properties/ports
> >>>> +
> >>>> +    properties:
> >>>> +      port@0:
> >>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >>>> +        unevaluatedProperties: false
> >>>> +        description: FPD-Link input 0
> >>>> +
> >>>> +        properties:
> >>>> +          endpoint:
> >>>> +            $ref: /schemas/media/video-interfaces.yaml#
> >>>> +            unevaluatedProperties: false
> >>>> +            description:
> >>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >>>> +              hsync-active and vsync-active must be defined.
> >>>> +
> >>>> +      port@1:
> >>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >>>> +        unevaluatedProperties: false
> >>>> +        description: FPD-Link input 1
> >>>> +
> >>>> +        properties:
> >>>> +          endpoint:
> >>>> +            $ref: /schemas/media/video-interfaces.yaml#
> >>>> +            unevaluatedProperties: false
> >>>> +            description:
> >>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >>>> +              hsync-active and vsync-active must be defined.
> >>>> +
> >>>> +      port@2:
> >>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >>>> +        unevaluatedProperties: false
> >>>> +        description: FPD-Link input 2
> >>>> +
> >>>> +        properties:
> >>>> +          endpoint:
> >>>> +            $ref: /schemas/media/video-interfaces.yaml#
> >>>> +            unevaluatedProperties: false
> >>>> +            description:
> >>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >>>> +              hsync-active and vsync-active must be defined.
> >>>> +
> >>>> +      port@3:
> >>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >>>> +        unevaluatedProperties: false
> >>>> +        description: FPD-Link input 3
> >>>> +
> >>>> +        properties:
> >>>> +          endpoint:
> >>>> +            $ref: /schemas/media/video-interfaces.yaml#
> >>>> +            unevaluatedProperties: false
> >>>> +            description:
> >>>> +              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
> >>>> +              hsync-active and vsync-active must be defined.
> >>>> +
> >>>> +      port@4:
> >>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >>>> +        unevaluatedProperties: false
> >>>> +        description: CSI-2 Output 0
> >>>> +
> >>>> +        properties:
> >>>> +          endpoint:
> >>>> +            $ref: /schemas/media/video-interfaces.yaml#
> >>>> +            unevaluatedProperties: false
> >>>> +
> >>>> +            properties:
> >>>> +              data-lanes:
> >>>> +                minItems: 1
> >>>> +                maxItems: 4
> >>>> +
> >>>> +            required:
> >>>> +              - data-lanes
> >>>> +
> >>>> +      port@5:
> >>>> +        $ref: /schemas/graph.yaml#/$defs/port-base
> >>>> +        unevaluatedProperties: false
> >>>> +        description: CSI-2 Output 1
> >>>> +
> >>>> +        properties:
> >>>> +          endpoint:
> >>>> +            $ref: /schemas/media/video-interfaces.yaml#
> >>>> +            unevaluatedProperties: false
> >>>> +
> >>>> +            properties:
> >>>> +              data-lanes:
> >>>> +                minItems: 1
> >>>> +                maxItems: 4
> >>>> +
> >>>> +            required:
> >>>> +              - data-lanes
> >>>
> >>> I think you need
> >>>
> >>>       required:
> >>>         - port@0
> >>>         - port@1
> >>>         - port@2
> >>>         - port@3
> >>>         - port@4
> >>>         - port@5
> >>
> >> Is that needed? I think often some of the ports are unused (e.g. the
> >> example in this yaml file). Is it customary to still require empty port
> >> nodes in the DT?
> > 
> > Ports are an intrinsic property of a device, they don't depend on the
> > device integration in the system. In this case, the UB960 has four
> > FPD-Link inputs and two CSI-2 outputs, that's a property of the chip.
> > They don't have to be connected to anything on the board, so endpooints
> > are optional.
> 
> Yes, but why do they have to be required? A missing port node implies 
> that it's not used, doesn't it? I don't mind much, it just feels a bit 
> extra to add multiple almost empty "port@X { reg = <X>; };" style nodes 
> to the dts file.

Lots of them are in .dtsi files, so it's not that bad. The main reasons I
push for making ports mandatory are uniformity (lots of bindings do so,
albeit some because I wrote them or asked for changes during review
:-)), and simplified port handling on the driver side.
  

Patch

diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
new file mode 100644
index 000000000000..664799ae55be
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml
@@ -0,0 +1,402 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/i2c/ti,ds90ub960.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Texas Instruments DS90UB9XX Family FPD-Link Deserializer Hubs
+
+maintainers:
+  - Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
+
+description:
+  The TI DS90UB9XX devices are FPD-Link video deserializers with I2C and GPIO
+  forwarding.
+
+properties:
+  compatible:
+    enum:
+      - ti,ds90ub960-q1
+      - ti,ds90ub9702-q1
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+    description:
+      Reference clock connected to the REFCLK pin.
+
+  clock-names:
+    items:
+      - const: refclk
+
+  powerdown-gpios:
+    maxItems: 1
+    description:
+      Specifier for the GPIO connected to the PDB pin.
+
+  i2c-alias-pool:
+    $ref: /schemas/types.yaml#/definitions/uint16-array
+    description:
+      I2C alias pool is a pool of I2C addresses on the main I2C bus that can be
+      used to access the remote peripherals on the serializer's I2C bus. The
+      addresses must be available, not used by any other peripheral. Each
+      remote peripheral is assigned an alias from the pool, and transactions to
+      that address will be forwarded to the remote peripheral, with the address
+      translated to the remote peripheral's real address. This property is not
+      needed if there are no I2C addressable remote peripherals.
+
+  links:
+    type: object
+    additionalProperties: false
+
+    properties:
+      '#address-cells':
+        const: 1
+
+      '#size-cells':
+        const: 0
+
+      ti,manual-strobe:
+        type: boolean
+        description:
+          Enable manual strobe position and EQ level
+
+    patternProperties:
+      '^link@[0-3]$':
+        type: object
+        additionalProperties: false
+        properties:
+          reg:
+            description: The link number
+            maxItems: 1
+
+          i2c-alias:
+            description:
+              The I2C address used for the serializer. Transactions to this
+              address on the I2C bus where the deserializer resides are
+              forwarded to the serializer.
+
+          ti,rx-mode:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            enum:
+              - 0 # RAW10
+              - 1 # RAW12 HF
+              - 2 # RAW12 LF
+              - 3 # CSI2 SYNC
+              - 4 # CSI2 NON-SYNC
+            description:
+              FPD-Link Input Mode. This should reflect the hardware and the
+              default mode of the connected camera module.
+
+          ti,cdr-mode:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            enum:
+              - 0 # FPD-Link III
+              - 1 # FPD-Link IV
+            description:
+              FPD-Link CDR Mode. This should reflect the hardware and the
+              default mode of the connected camera module.
+
+          ti,strobe-pos:
+            $ref: /schemas/types.yaml#/definitions/int32
+            minimum: -13
+            maximum: 13
+            description: Manual strobe position
+
+          ti,eq-level:
+            $ref: /schemas/types.yaml#/definitions/uint32
+            maximum: 14
+            description: Manual EQ level
+
+          serializer:
+            type: object
+            description: FPD-Link Serializer node
+
+        required:
+          - reg
+          - i2c-alias
+          - ti,rx-mode
+          - serializer
+
+  ports:
+    $ref: /schemas/graph.yaml#/properties/ports
+
+    properties:
+      port@0:
+        $ref: /schemas/graph.yaml#/$defs/port-base
+        unevaluatedProperties: false
+        description: FPD-Link input 0
+
+        properties:
+          endpoint:
+            $ref: /schemas/media/video-interfaces.yaml#
+            unevaluatedProperties: false
+            description:
+              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+              hsync-active and vsync-active must be defined.
+
+      port@1:
+        $ref: /schemas/graph.yaml#/$defs/port-base
+        unevaluatedProperties: false
+        description: FPD-Link input 1
+
+        properties:
+          endpoint:
+            $ref: /schemas/media/video-interfaces.yaml#
+            unevaluatedProperties: false
+            description:
+              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+              hsync-active and vsync-active must be defined.
+
+      port@2:
+        $ref: /schemas/graph.yaml#/$defs/port-base
+        unevaluatedProperties: false
+        description: FPD-Link input 2
+
+        properties:
+          endpoint:
+            $ref: /schemas/media/video-interfaces.yaml#
+            unevaluatedProperties: false
+            description:
+              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+              hsync-active and vsync-active must be defined.
+
+      port@3:
+        $ref: /schemas/graph.yaml#/$defs/port-base
+        unevaluatedProperties: false
+        description: FPD-Link input 3
+
+        properties:
+          endpoint:
+            $ref: /schemas/media/video-interfaces.yaml#
+            unevaluatedProperties: false
+            description:
+              Endpoint for FPD-Link port. If the RX mode for this port is RAW,
+              hsync-active and vsync-active must be defined.
+
+      port@4:
+        $ref: /schemas/graph.yaml#/$defs/port-base
+        unevaluatedProperties: false
+        description: CSI-2 Output 0
+
+        properties:
+          endpoint:
+            $ref: /schemas/media/video-interfaces.yaml#
+            unevaluatedProperties: false
+
+            properties:
+              data-lanes:
+                minItems: 1
+                maxItems: 4
+
+            required:
+              - data-lanes
+
+      port@5:
+        $ref: /schemas/graph.yaml#/$defs/port-base
+        unevaluatedProperties: false
+        description: CSI-2 Output 1
+
+        properties:
+          endpoint:
+            $ref: /schemas/media/video-interfaces.yaml#
+            unevaluatedProperties: false
+
+            properties:
+              data-lanes:
+                minItems: 1
+                maxItems: 4
+
+            required:
+              - data-lanes
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - ports
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    i2c {
+      clock-frequency = <400000>;
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      deser@3d {
+        compatible = "ti,ds90ub960-q1";
+        reg = <0x3d>;
+
+        clock-names = "refclk";
+        clocks = <&fixed_clock>;
+
+        powerdown-gpios = <&pca9555 7 GPIO_ACTIVE_LOW>;
+
+        i2c-alias-pool = /bits/ 16 <0x4a 0x4b 0x4c 0x4d 0x4e 0x4f>;
+
+        ports {
+          #address-cells = <1>;
+          #size-cells = <0>;
+
+          /* Port 0, Camera 0 */
+          port@0 {
+            reg = <0>;
+
+            ub960_fpd3_1_in: endpoint {
+              remote-endpoint = <&ub953_1_out>;
+            };
+          };
+
+          /* Port 1, Camera 1 */
+          port@1 {
+            reg = <1>;
+
+            ub960_fpd3_2_in: endpoint {
+              remote-endpoint = <&ub913_2_out>;
+              hsync-active = <0>;
+              vsync-active = <1>;
+            };
+          };
+
+          /* Port 4, CSI-2 TX */
+          port@4 {
+            reg = <4>;
+            ds90ub960_0_csi_out: endpoint {
+              data-lanes = <1 2 3 4>;
+              link-frequencies = /bits/ 64 <800000000>;
+              remote-endpoint = <&csi2_phy0>;
+            };
+          };
+        };
+
+        links {
+          #address-cells = <1>;
+          #size-cells = <0>;
+
+          /* Link 0 has DS90UB953 serializer and IMX274 sensor */
+
+          link@0 {
+            reg = <0>;
+            i2c-alias = <0x44>;
+
+            ti,rx-mode = <3>;
+
+            serializer1: serializer {
+              compatible = "ti,ds90ub953-q1";
+
+              gpio-controller;
+              #gpio-cells = <2>;
+
+              #clock-cells = <0>;
+
+              ports {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                port@0 {
+                  reg = <0>;
+                  ub953_1_in: endpoint {
+                    data-lanes = <1 2 3 4>;
+                    remote-endpoint = <&sensor_1_out>;
+                  };
+                };
+
+                port@1 {
+                  reg = <1>;
+
+                  ub953_1_out: endpoint {
+                    remote-endpoint = <&ub960_fpd3_1_in>;
+                  };
+                };
+              };
+
+              i2c {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                sensor@1a {
+                  compatible = "sony,imx274";
+                  reg = <0x1a>;
+
+                  reset-gpios = <&serializer1 0 GPIO_ACTIVE_LOW>;
+
+                  port {
+                    sensor_1_out: endpoint {
+                      remote-endpoint = <&ub953_1_in>;
+                    };
+                  };
+                };
+              };
+            };
+          };  /* End of link@0 */
+
+          /* Link 1 has DS90UB913 serializer and MT9V111 sensor */
+
+          link@1 {
+            reg = <1>;
+            i2c-alias = <0x45>;
+
+            ti,rx-mode = <0>;
+
+            serializer2: serializer {
+              compatible = "ti,ds90ub913a-q1";
+
+              gpio-controller;
+              #gpio-cells = <2>;
+
+              clocks = <&clk_cam_48M>;
+              clock-names = "clkin";
+
+              #clock-cells = <0>;
+
+              ports {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                port@0 {
+                  reg = <0>;
+                  ub913_2_in: endpoint {
+                    remote-endpoint = <&sensor_2_out>;
+                    pclk-sample = <1>;
+                  };
+                };
+
+                port@1 {
+                  reg = <1>;
+
+                  ub913_2_out: endpoint {
+                    remote-endpoint = <&ub960_fpd3_2_in>;
+                  };
+                };
+              };
+
+              i2c {
+                #address-cells = <1>;
+                #size-cells = <0>;
+
+                sensor@48 {
+                  compatible = "aptina,mt9v111";
+                  reg = <0x48>;
+
+                  clocks = <&serializer2>;
+
+                  port {
+                    sensor_2_out: endpoint {
+                      remote-endpoint = <&ub913_2_in>;
+                    };
+                  };
+                };
+              };
+            };
+          }; /* End of link@1 */
+        };
+      };
+    };
+...