# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) 2024 Collabora Ltd.
%YAML 1.2
---
$id: http://devicetree.org/schemas/media/i2c/maxim,max96717.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: MAX96717 CSI-2 to GMSL2 Serializer

maintainers:
  - Julien Massot <julien.massot@collabora.com>

description:
  The MAX96717 serializer converts MIPI CSI-2 D-PHY formatted input
  into GMSL2 serial outputs. The device allows the GMSL2 link to
  simultaneously transmit bidirectional control-channel data while forward
  video transmissions are in progress. The MAX96717 can connect to one
  remotely located deserializer using industry-standard coax or STP
  interconnects. The device cans operate in pixel or tunnel mode. In pixel mode
  the MAX96717 can select the MIPI datatype, while the tunnel mode forward all the MIPI
  data received by the serializer.
  The MAX96717 supports Reference Over Reverse (channel),
  to generate a clock output for the sensor from the GMSL reverse channel.

  The GMSL2 serial link operates at a fixed rate of 3Gbps or 6Gbps in the
  forward direction and 187.5Mbps in the reverse direction.

  MAX96717F only supports a fixed rate of 3Gbps in the forward direction.

  MAX9295A only supports pixel mode.

  MAX96793 also supports GMSL3 mode.

properties:
  compatible:
    oneOf:
      - enum:
          - maxim,max9295a
          - maxim,max96717f
      - items:
          - enum:
              - maxim,max96717
              - maxim,max96793
          - const: maxim,max96717f

  '#gpio-cells':
    const: 2
    description:
      First cell is the GPIO pin number, second cell is the flags. The GPIO pin
      number must be in range of [0, 10].

  gpio-controller: true

  '#clock-cells':
    const: 0

  reg:
    maxItems: 1

  ports:
    $ref: /schemas/graph.yaml#/properties/ports

    properties:
      port@0:
        $ref: /schemas/graph.yaml#/$defs/port-base
        unevaluatedProperties: false
        description: CSI-2 Input port

        properties:
          endpoint:
            $ref: /schemas/media/video-interfaces.yaml#
            unevaluatedProperties: false

            properties:
              data-lanes:
                minItems: 1
                maxItems: 4

              lane-polarities:
                minItems: 1
                maxItems: 5

            required:
              - data-lanes

      port@1:
        $ref: /schemas/graph.yaml#/properties/port
        unevaluatedProperties: false
        description: GMSL Output port

    required:
      - port@1

  i2c-gate:
    $ref: /schemas/i2c/i2c-gate.yaml
    unevaluatedProperties: false
    description:
      The MAX96717 will forward the I2C requests from the
      incoming GMSL2 link. Therefore, it supports an i2c-gate
      subnode to configure a sensor.

  i2c-alias-pool:
    maxItems: 2

  i2c-atr:
    type: object
    additionalProperties: false

    properties:
      '#address-cells':
        const: 1

      '#size-cells':
        const: 0

    patternProperties:
      '^i2c@[01]$':
        $ref: /schemas/i2c/i2c-controller.yaml#
        unevaluatedProperties: false
        properties:
          reg:
            items:
              minimum: 0
              maximum: 1

required:
  - compatible
  - reg
  - ports

patternProperties:
  '-pins$':
    type: object
    additionalProperties: false

    properties:
      function:
        enum: [gpio, rclkout]

      pins: true
      drive-open-drain: true
      drive-push-pull: true
      bias-disable: true
      output-disable: true
      output-enable: true
      output-low: true
      output-high: true
      input-enable: true

      slew-rate:
        description: |
          Slew rate.
          Rise and fall times represent the time needed for a GPIO to go
          from 20% to 80% of VDDIO.
          0 - Fastest
              rise:  1.0ns @ 1.8V,  0.6ns @ 3.3V,
              fall:  0.8ns @ 1.8V,  0.5ns @ 3.3V
          1 - Fast
              rise:  2.1ns @ 1.8V,  1.1ns @ 3.3V,
              fall:  2.0ns @ 1.8V,  1.1ns @ 3.3V
          2 - Slow
              rise:  4.0ns @ 1.8V, 2.3ns @3.3V,
              fall: 10.0ns @ 1.8V, 5.0ns @3.3V
          3 - Slowest
              rise:  9.0ns @ 1.8V, 5.0ns @3.3V,
              fall: 10.0ns @ 1.8V, 5.0ns @3.3V
        maximum: 3

      bias-pull-up:
        oneOf:
          - type: boolean
            description: Enable regular 40kOhm pull-up
          - enum: [ 40000, 1000000 ]
            description: Enable either the 40kOhm or the 1MOhm pull-up

      bias-pull-down:
        oneOf:
          - type: boolean
            description: Enable regular 40kOhm pull-down
          - enum: [ 40000, 1000000 ]
            description: Enable either the 40kOhm or the 1MOhm pull-down

      maxim,jitter-compensation:
        type: boolean
        description: |
          Enables jitter compensation.
          Jitter compensation is used to minimize the jitter of the
          signals transmitted from the deserializer to the serializer
          by adding a fixed delay to every transition on the serializer
          side. This can be used for pulse generation where timing is
          critical.

      maxim,tx-id:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          Enable transmission of the pin state from the serializer to
          the deserializer using the specified identifier.
        maximum: 31

      maxim,rx-id:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          Enable transmission of the pin state from the deserializer to
          the serializer using the specified identifier.
        maximum: 31

    required:
      - pins
      - function

    allOf:
      - $ref: /schemas/pinctrl/pincfg-node.yaml#
      - $ref: /schemas/pinctrl/pinmux-node.yaml#

      - if:
          properties:
            function:
              const: gpio
        then:
          properties:
            pins:
              items:
                enum: [mfp0, mfp1, mfp2, mfp3, mfp4, mfp5, mfp6, mfp7,
                       mfp8, mfp9, mfp10]

      - if:
          properties:
            function:
              const: rclkout
        then:
          properties:
            pins:
              items:
                enum: [mfp2, mfp4]

      - if:
          required:
            - slew-rate
        then:
          properties:
            pins:
              items:
                enum: [mfp0, mfp1, mfp2, mfp3, mfp4, mfp7, mfp8]

additionalProperties: false

allOf:
  - $ref: /schemas/i2c/i2c-atr.yaml#

  - anyOf:
      - oneOf:
          - required: [i2c-atr]
          - required: [i2c-gate]

      - not:
          required: [i2c-atr, i2c-gate]

dependentRequired:
  i2c-atr: [i2c-alias-pool]
  i2c-alias-pool: [i2c-atr]

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/media/video-interfaces.h>

    i2c {
        #address-cells = <1>;
        #size-cells = <0>;
        serializer: serializer@40 {
            compatible = "maxim,max96717f";
            reg = <0x40>;
            gpio-controller;
            #gpio-cells = <2>;
            #clock-cells = <0>;

            ports {
                #address-cells = <1>;
                #size-cells = <0>;

                port@0 {
                    reg = <0>;
                    max96717f_csi_in: endpoint {
                        data-lanes = <1 2 3 4>;
                        remote-endpoint = <&sensor_out>;
                    };
                };

                port@1 {
                    reg = <1>;
                    max96917f_gmsl_out: endpoint {
                        remote-endpoint = <&deser_gmsl_in>;
                    };
                };
            };

            i2c-gate {
                #address-cells = <1>;
                #size-cells = <0>;
                sensor@10 {
                    compatible = "st,st-vgxy61";
                    reg = <0x10>;
                    reset-gpios = <&serializer 0 GPIO_ACTIVE_LOW>;
                    clocks = <&serializer>;
                    VCORE-supply = <&v1v2>;
                    VDDIO-supply = <&v1v8>;
                    VANA-supply = <&v2v8>;
                    port {
                        sensor_out: endpoint {
                            data-lanes = <1 2 3 4>;
                            remote-endpoint = <&max96717f_csi_in>;
                        };
                    };
                };
            };
        };
    };
...