diff mbox series

[v4,1/2] media: dt-bindings: Convert video-interfaces.txt properties to schemas

Message ID 20210104165808.2166686-2-robh@kernel.org
State Accepted
Commit 41f42b6e693dc9822f83bc832de508600b00535f
Headers show
Series dt-bindings: media: Convert video-interfaces.txt to schemas | expand

Commit Message

Rob Herring Jan. 4, 2021, 4:58 p.m. UTC
Convert video-interfaces.txt to DT schema. As it contains a mixture of
device level and endpoint properties, split it up into 2 schemas.

Binding schemas will need to reference both the graph.yaml and
video-interfaces.yaml schemas. The exact schema depends on how many
ports and endpoints for the binding. A single port with a single
endpoint looks similar to this:

  port:
    $ref: /schemas/graph.yaml#/$defs/port-base

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

        properties:
          bus-width:
            enum: [ 8, 10, 12, 16 ]

          pclk-sample: true
          hsync-active: true
          vsync-active: true

        required:
          - bus-width

    additionalProperties: false

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

Acked-by: Jacopo Mondi <jacopo@jmondi.org>

Acked-by: Guennadi Liakhovetski <g.liakhovetski@gmx.de>

Acked-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Signed-off-by: Rob Herring <robh@kernel.org>

---

v4:
- drop graph.txt ref
- s/Bt.656/BT.656/
- Replace Guennadi with Laurent as maintainer

v3:
- Support up to 9 physical lanes
- Set lane-polarities array bounds
---
 .../media/video-interface-devices.yaml        | 406 +++++++++++
 .../bindings/media/video-interfaces.txt       | 640 +-----------------
 .../bindings/media/video-interfaces.yaml      | 344 ++++++++++
 3 files changed, 751 insertions(+), 639 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/media/video-interface-devices.yaml
 create mode 100644 Documentation/devicetree/bindings/media/video-interfaces.yaml

-- 
2.27.0

Comments

Rob Herring Jan. 22, 2021, 4:23 p.m. UTC | #1
On Mon, Jan 4, 2021 at 10:58 AM Rob Herring <robh@kernel.org> wrote:
>
> Convert video-interfaces.txt to DT schema. As it contains a mixture of
> device level and endpoint properties, split it up into 2 schemas.

Ping!

Can this please be applied to the media tree so I can tell folks to
use it in reviews of media bindings.

> Binding schemas will need to reference both the graph.yaml and
> video-interfaces.yaml schemas. The exact schema depends on how many
> ports and endpoints for the binding. A single port with a single
> endpoint looks similar to this:
>
>   port:
>     $ref: /schemas/graph.yaml#/$defs/port-base
>
>     properties:
>       endpoint:
>         $ref: video-interfaces.yaml#
>         unevaluatedProperties: false
>
>         properties:
>           bus-width:
>             enum: [ 8, 10, 12, 16 ]
>
>           pclk-sample: true
>           hsync-active: true
>           vsync-active: true
>
>         required:
>           - bus-width
>
>     additionalProperties: false
>
> Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
> Acked-by: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
> Acked-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
>
> v4:
> - drop graph.txt ref
> - s/Bt.656/BT.656/
> - Replace Guennadi with Laurent as maintainer
>
> v3:
> - Support up to 9 physical lanes
> - Set lane-polarities array bounds
> ---
>  .../media/video-interface-devices.yaml        | 406 +++++++++++
>  .../bindings/media/video-interfaces.txt       | 640 +-----------------
>  .../bindings/media/video-interfaces.yaml      | 344 ++++++++++
>  3 files changed, 751 insertions(+), 639 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/media/video-interface-devices.yaml
>  create mode 100644 Documentation/devicetree/bindings/media/video-interfaces.yaml
>
> diff --git a/Documentation/devicetree/bindings/media/video-interface-devices.yaml b/Documentation/devicetree/bindings/media/video-interface-devices.yaml
> new file mode 100644
> index 000000000000..4527f56a5a6e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/video-interface-devices.yaml
> @@ -0,0 +1,406 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/video-interface-devices.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Common bindings for video receiver and transmitter devices
> +
> +maintainers:
> +  - Jacopo Mondi <jacopo@jmondi.org>
> +  - Sakari Ailus <sakari.ailus@linux.intel.com>
> +
> +properties:
> +  flash-leds:
> +    $ref: /schemas/types.yaml#/definitions/phandle-array
> +    description:
> +      An array of phandles, each referring to a flash LED, a sub-node of the LED
> +      driver device node.
> +
> +  lens-focus:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description:
> +      A phandle to the node of the focus lens controller.
> +
> +  rotation:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 90, 180, 270 ]
> +    description: |
> +      The camera rotation is expressed as the angular difference in degrees
> +      between two reference systems, one relative to the camera module, and one
> +      defined on the external world scene to be captured when projected on the
> +      image sensor pixel array.
> +
> +      A camera sensor has a 2-dimensional reference system 'Rc' defined by its
> +      pixel array read-out order. The origin is set to the first pixel being
> +      read out, the X-axis points along the column read-out direction towards
> +      the last columns, and the Y-axis along the row read-out direction towards
> +      the last row.
> +
> +      A typical example for a sensor with a 2592x1944 pixel array matrix
> +      observed from the front is:
> +
> +              2591       X-axis          0
> +                <------------------------+ 0
> +                .......... ... ..........!
> +                .......... ... ..........! Y-axis
> +                           ...           !
> +                .......... ... ..........!
> +                .......... ... ..........! 1943
> +                                         V
> +
> +      The external world scene reference system 'Rs' is a 2-dimensional
> +      reference system on the focal plane of the camera module. The origin is
> +      placed on the top-left corner of the visible scene, the X-axis points
> +      towards the right, and the Y-axis points towards the bottom of the scene.
> +      The top, bottom, left and right directions are intentionally not defined
> +      and depend on the environment in which the camera is used.
> +
> +      A typical example of a (very common) picture of a shark swimming from left
> +      to right, as seen from the camera, is:
> +
> +               0               X-axis
> +             0 +------------------------------------->
> +               !
> +               !
> +               !
> +               !           |\____)\___
> +               !           ) _____  __`<
> +               !           |/     )/
> +               !
> +               !
> +               !
> +               V
> +             Y-axis
> +
> +      with the reference system 'Rs' placed on the camera focal plane:
> +
> +                                  ¸.·˙!
> +                              ¸.·˙    !
> +                  _       ¸.·˙        !
> +               +-/ \-+¸.·˙            !
> +               | (o) |                ! Camera focal plane
> +               +-----+˙·.¸            !
> +                          ˙·.¸        !
> +                              ˙·.¸    !
> +                                  ˙·.¸!
> +
> +      When projected on the sensor's pixel array, the image and the associated
> +      reference system 'Rs' are typically (but not always) inverted, due to the
> +      camera module's lens optical inversion effect.
> +
> +      Assuming the above represented scene of the swimming shark, the lens
> +      inversion projects the scene and its reference system onto the sensor
> +      pixel array, seen from the front of the camera sensor, as follows:
> +
> +            Y-axis
> +               ^
> +               !
> +               !
> +               !
> +               !            |\_____)\__
> +               !            ) ____  ___.<
> +               !            |/    )/
> +               !
> +               !
> +               !
> +             0 +------------------------------------->
> +               0               X-axis
> +
> +      Note the shark being upside-down.
> +
> +      The resulting projected reference system is named 'Rp'.
> +
> +      The camera rotation property is then defined as the angular difference in
> +      the counter-clockwise direction between the camera reference system 'Rc'
> +      and the projected scene reference system 'Rp'. It is expressed in degrees
> +      as a number in the range [0, 360[.
> +
> +      Examples
> +
> +      0 degrees camera rotation:
> +
> +
> +                    Y-Rp
> +                     ^
> +              Y-Rc   !
> +               ^     !
> +               !     !
> +               !     !
> +               !     !
> +               !     !
> +               !     !
> +               !     !
> +               !     !
> +               !   0 +------------------------------------->
> +               !     0               X-Rp
> +             0 +------------------------------------->
> +               0               X-Rc
> +
> +
> +                                X-Rc                0
> +               <------------------------------------+ 0
> +                           X-Rp                 0   !
> +           <------------------------------------+ 0 !
> +                                                !   !
> +                                                !   !
> +                                                !   !
> +                                                !   !
> +                                                !   !
> +                                                !   !
> +                                                !   !
> +                                                !   V
> +                                                !  Y-Rc
> +                                                V
> +                                               Y-Rp
> +
> +      90 degrees camera rotation:
> +
> +               0        Y-Rc
> +             0 +-------------------->
> +               !   Y-Rp
> +               !    ^
> +               !    !
> +               !    !
> +               !    !
> +               !    !
> +               !    !
> +               !    !
> +               !    !
> +               !    !
> +               !    !
> +               !  0 +------------------------------------->
> +               !    0              X-Rp
> +               !
> +               !
> +               !
> +               !
> +               V
> +              X-Rc
> +
> +      180 degrees camera rotation:
> +
> +                                            0
> +       <------------------------------------+ 0
> +                        X-Rc                !
> +              Y-Rp                          !
> +               ^                            !
> +               !                            !
> +               !                            !
> +               !                            !
> +               !                            !
> +               !                            !
> +               !                            !
> +               !                            V
> +               !                           Y-Rc
> +             0 +------------------------------------->
> +               0              X-Rp
> +
> +      270 degrees camera rotation:
> +
> +               0        Y-Rc
> +             0 +-------------------->
> +               !                                        0
> +               !    <-----------------------------------+ 0
> +               !                    X-Rp                !
> +               !                                        !
> +               !                                        !
> +               !                                        !
> +               !                                        !
> +               !                                        !
> +               !                                        !
> +               !                                        !
> +               !                                        !
> +               !                                        V
> +               !                                       Y-Rp
> +               !
> +               !
> +               !
> +               !
> +               V
> +              X-Rc
> +
> +
> +      Example one - Webcam
> +
> +      A camera module installed on the user facing part of a laptop screen
> +      casing used for video calls. The captured images are meant to be displayed
> +      in landscape mode (width > height) on the laptop screen.
> +
> +      The camera is typically mounted upside-down to compensate the lens optical
> +      inversion effect:
> +
> +                    Y-Rp
> +              Y-Rc   ^
> +               ^     !
> +               !     !
> +               !     !       |\_____)\__
> +               !     !       ) ____  ___.<
> +               !     !       |/    )/
> +               !     !
> +               !     !
> +               !     !
> +               !   0 +------------------------------------->
> +               !     0           X-Rp
> +             0 +------------------------------------->
> +               0            X-Rc
> +
> +      The two reference systems are aligned, the resulting camera rotation is
> +      0 degrees, no rotation correction needs to be applied to the resulting
> +      image once captured to memory buffers to correctly display it to users:
> +
> +               +--------------------------------------+
> +               !                                      !
> +               !                                      !
> +               !                                      !
> +               !             |\____)\___              !
> +               !             ) _____  __`<            !
> +               !             |/     )/                !
> +               !                                      !
> +               !                                      !
> +               !                                      !
> +               +--------------------------------------+
> +
> +      If the camera sensor is not mounted upside-down to compensate for the lens
> +      optical inversion, the two reference systems will not be aligned, with
> +      'Rp' being rotated 180 degrees relatively to 'Rc':
> +
> +
> +                        X-Rc                0
> +       <------------------------------------+ 0
> +                                            !
> +              Y-Rp                          !
> +               ^                            !
> +               !                            !
> +               !       |\_____)\__          !
> +               !       ) ____  ___.<        !
> +               !       |/    )/             !
> +               !                            !
> +               !                            !
> +               !                            V
> +               !                           Y-Rc
> +             0 +------------------------------------->
> +               0            X-Rp
> +
> +      The image once captured to memory will then be rotated by 180 degrees:
> +
> +               +--------------------------------------+
> +               !                                      !
> +               !                                      !
> +               !                                      !
> +               !              __/(_____/|             !
> +               !            >.___  ____ (             !
> +               !                 \(    \|             !
> +               !                                      !
> +               !                                      !
> +               !                                      !
> +               +--------------------------------------+
> +
> +      A software rotation correction of 180 degrees should be applied to
> +      correctly display the image:
> +
> +               +--------------------------------------+
> +               !                                      !
> +               !                                      !
> +               !                                      !
> +               !             |\____)\___              !
> +               !             ) _____  __`<            !
> +               !             |/     )/                !
> +               !                                      !
> +               !                                      !
> +               !                                      !
> +               +--------------------------------------+
> +
> +      Example two - Phone camera
> +
> +      A camera installed on the back side of a mobile device facing away from
> +      the user. The captured images are meant to be displayed in portrait mode
> +      (height > width) to match the device screen orientation and the device
> +      usage orientation used when taking the picture.
> +
> +      The camera sensor is typically mounted with its pixel array longer side
> +      aligned to the device longer side, upside-down mounted to compensate for
> +      the lens optical inversion effect:
> +
> +               0        Y-Rc
> +             0 +-------------------->
> +               !   Y-Rp
> +               !    ^
> +               !    !
> +               !    !
> +               !    !
> +               !    !            |\_____)\__
> +               !    !            ) ____  ___.<
> +               !    !            |/    )/
> +               !    !
> +               !    !
> +               !    !
> +               !  0 +------------------------------------->
> +               !    0                X-Rp
> +               !
> +               !
> +               !
> +               !
> +               V
> +              X-Rc
> +
> +      The two reference systems are not aligned and the 'Rp' reference system is
> +      rotated by 90 degrees in the counter-clockwise direction relatively to the
> +      'Rc' reference system.
> +
> +      The image once captured to memory will be rotated:
> +
> +               +-------------------------------------+
> +               |                 _ _                 |
> +               |                \   /                |
> +               |                 | |                 |
> +               |                 | |                 |
> +               |                 |  >                |
> +               |                <  |                 |
> +               |                 | |                 |
> +               |                   .                 |
> +               |                  V                  |
> +               +-------------------------------------+
> +
> +      A correction of 90 degrees in counter-clockwise direction has to be
> +      applied to correctly display the image in portrait mode on the device
> +      screen:
> +
> +                        +--------------------+
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        |   |\____)\___      |
> +                        |   ) _____  __`<    |
> +                        |   |/     )/        |
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        |                    |
> +                        +--------------------+
> +
> +  orientation:
> +    description:
> +      The orientation of a device (typically an image sensor or a flash LED)
> +      describing its mounting position relative to the usage orientation of the
> +      system where the device is installed on.
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum:
> +        # Front. The device is mounted on the front facing side of the system. For
> +        # mobile devices such as smartphones, tablets and laptops the front side
> +        # is the user facing side.
> +      - 0
> +        # Back. The device is mounted on the back side of the system, which is
> +        # defined as the opposite side of the front facing one.
> +      - 1
> +        # External. The device is not attached directly to the system but is
> +        # attached in a way that allows it to move freely.
> +      - 2
> +
> +additionalProperties: true
> +
> +...
> diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
> index 3920f25a9123..8fcf5f52bf5b 100644
> --- a/Documentation/devicetree/bindings/media/video-interfaces.txt
> +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
> @@ -1,639 +1 @@
> -Common bindings for video receiver and transmitter interfaces
> -
> -General concept
> ----------------
> -
> -Video data pipelines usually consist of external devices, e.g. camera sensors,
> -controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including
> -video DMA engines and video data processors.
> -
> -SoC internal blocks are described by DT nodes, placed similarly to other SoC
> -blocks.  External devices are represented as child nodes of their respective
> -bus controller nodes, e.g. I2C.
> -
> -Data interfaces on all video devices are described by their child 'port' nodes.
> -Configuration of a port depends on other devices participating in the data
> -transfer and is described by 'endpoint' subnodes.
> -
> -device {
> -       ...
> -       ports {
> -               #address-cells = <1>;
> -               #size-cells = <0>;
> -
> -               port@0 {
> -                       ...
> -                       endpoint@0 { ... };
> -                       endpoint@1 { ... };
> -               };
> -               port@1 { ... };
> -       };
> -};
> -
> -If a port can be configured to work with more than one remote device on the same
> -bus, an 'endpoint' child node must be provided for each of them.  If more than
> -one port is present in a device node or there is more than one endpoint at a
> -port, or port node needs to be associated with a selected hardware interface,
> -a common scheme using '#address-cells', '#size-cells' and 'reg' properties is
> -used.
> -
> -All 'port' nodes can be grouped under optional 'ports' node, which allows to
> -specify #address-cells, #size-cells properties independently for the 'port'
> -and 'endpoint' nodes and any child device nodes a device might have.
> -
> -Two 'endpoint' nodes are linked with each other through their 'remote-endpoint'
> -phandles.  An endpoint subnode of a device contains all properties needed for
> -configuration of this device for data exchange with other device.  In most
> -cases properties at the peer 'endpoint' nodes will be identical, however they
> -might need to be different when there is any signal modifications on the bus
> -between two devices, e.g. there are logic signal inverters on the lines.
> -
> -It is allowed for multiple endpoints at a port to be active simultaneously,
> -where supported by a device.  For example, in case where a data interface of
> -a device is partitioned into multiple data busses, e.g. 16-bit input port
> -divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
> -and data-shift properties can be used to assign physical data lines to each
> -endpoint node (logical bus).
> -
> -Documenting bindings for devices
> ---------------------------------
> -
> -All required and optional bindings the device supports shall be explicitly
> -documented in device DT binding documentation. This also includes port and
> -endpoint nodes for the device, including unit-addresses and reg properties where
> -relevant.
> -
> -Please also see Documentation/devicetree/bindings/graph.txt .
> -
> -Required properties
> --------------------
> -
> -If there is more than one 'port' or more than one 'endpoint' node or 'reg'
> -property is present in port and/or endpoint nodes the following properties
> -are required in a relevant parent node:
> -
> - - #address-cells : number of cells required to define port/endpoint
> -                   identifier, should be 1.
> - - #size-cells    : should be zero.
> -
> -
> -Optional properties
> --------------------
> -
> -- flash-leds: An array of phandles, each referring to a flash LED, a sub-node
> -  of the LED driver device node.
> -
> -- lens-focus: A phandle to the node of the focus lens controller.
> -
> -- rotation: The camera rotation is expressed as the angular difference in
> -  degrees between two reference systems, one relative to the camera module, and
> -  one defined on the external world scene to be captured when projected on the
> -  image sensor pixel array.
> -
> -  A camera sensor has a 2-dimensional reference system 'Rc' defined by
> -  its pixel array read-out order. The origin is set to the first pixel
> -  being read out, the X-axis points along the column read-out direction
> -  towards the last columns, and the Y-axis along the row read-out
> -  direction towards the last row.
> -
> -  A typical example for a sensor with a 2592x1944 pixel array matrix
> -  observed from the front is:
> -
> -              2591       X-axis          0
> -                <------------------------+ 0
> -                .......... ... ..........!
> -                .......... ... ..........! Y-axis
> -                           ...           !
> -                .......... ... ..........!
> -                .......... ... ..........! 1943
> -                                         V
> -
> -  The external world scene reference system 'Rs' is a 2-dimensional
> -  reference system on the focal plane of the camera module. The origin is
> -  placed on the top-left corner of the visible scene, the X-axis points
> -  towards the right, and the Y-axis points towards the bottom of the
> -  scene. The top, bottom, left and right directions are intentionally not
> -  defined and depend on the environment in which the camera is used.
> -
> -  A typical example of a (very common) picture of a shark swimming from
> -  left to right, as seen from the camera, is:
> -
> -               0               X-axis
> -             0 +------------------------------------->
> -               !
> -               !
> -               !
> -               !           |\____)\___
> -               !           ) _____  __`<
> -               !           |/     )/
> -               !
> -               !
> -               !
> -               V
> -             Y-axis
> -
> -  with the reference system 'Rs' placed on the camera focal plane:
> -
> -                                  ¸.·˙!
> -                              ¸.·˙    !
> -                  _       ¸.·˙        !
> -               +-/ \-+¸.·˙            !
> -               | (o) |                ! Camera focal plane
> -               +-----+˙·.¸            !
> -                          ˙·.¸        !
> -                              ˙·.¸    !
> -                                  ˙·.¸!
> -
> -  When projected on the sensor's pixel array, the image and the associated
> -  reference system 'Rs' are typically (but not always) inverted, due to
> -  the camera module's lens optical inversion effect.
> -
> -  Assuming the above represented scene of the swimming shark, the lens
> -  inversion projects the scene and its reference system onto the sensor
> -  pixel array, seen from the front of the camera sensor, as follows:
> -
> -            Y-axis
> -               ^
> -               !
> -               !
> -               !
> -               !            |\_____)\__
> -               !            ) ____  ___.<
> -               !            |/    )/
> -               !
> -               !
> -               !
> -             0 +------------------------------------->
> -               0               X-axis
> -
> -  Note the shark being upside-down.
> -
> -  The resulting projected reference system is named 'Rp'.
> -
> -  The camera rotation property is then defined as the angular difference
> -  in the counter-clockwise direction between the camera reference system
> -  'Rc' and the projected scene reference system 'Rp'. It is expressed in
> -  degrees as a number in the range [0, 360[.
> -
> -  Examples
> -
> -  0 degrees camera rotation:
> -
> -
> -                    Y-Rp
> -                     ^
> -              Y-Rc   !
> -               ^     !
> -               !     !
> -               !     !
> -               !     !
> -               !     !
> -               !     !
> -               !     !
> -               !     !
> -               !   0 +------------------------------------->
> -               !     0               X-Rp
> -             0 +------------------------------------->
> -               0               X-Rc
> -
> -
> -                                X-Rc                0
> -               <------------------------------------+ 0
> -                           X-Rp                 0   !
> -           <------------------------------------+ 0 !
> -                                                !   !
> -                                                !   !
> -                                                !   !
> -                                                !   !
> -                                                !   !
> -                                                !   !
> -                                                !   !
> -                                                !   V
> -                                                !  Y-Rc
> -                                                V
> -                                               Y-Rp
> -
> -  90 degrees camera rotation:
> -
> -               0        Y-Rc
> -             0 +-------------------->
> -               !   Y-Rp
> -               !    ^
> -               !    !
> -               !    !
> -               !    !
> -               !    !
> -               !    !
> -               !    !
> -               !    !
> -               !    !
> -               !    !
> -               !  0 +------------------------------------->
> -               !    0              X-Rp
> -               !
> -               !
> -               !
> -               !
> -               V
> -              X-Rc
> -
> -  180 degrees camera rotation:
> -
> -                                            0
> -       <------------------------------------+ 0
> -                        X-Rc                !
> -              Y-Rp                          !
> -               ^                            !
> -               !                            !
> -               !                            !
> -               !                            !
> -               !                            !
> -               !                            !
> -               !                            !
> -               !                            V
> -               !                           Y-Rc
> -             0 +------------------------------------->
> -               0              X-Rp
> -
> -  270 degrees camera rotation:
> -
> -               0        Y-Rc
> -             0 +-------------------->
> -               !                                        0
> -               !    <-----------------------------------+ 0
> -               !                    X-Rp                !
> -               !                                        !
> -               !                                        !
> -               !                                        !
> -               !                                        !
> -               !                                        !
> -               !                                        !
> -               !                                        !
> -               !                                        !
> -               !                                        V
> -               !                                       Y-Rp
> -               !
> -               !
> -               !
> -               !
> -               V
> -              X-Rc
> -
> -
> -  Example one - Webcam
> -
> -  A camera module installed on the user facing part of a laptop screen
> -  casing used for video calls. The captured images are meant to be
> -  displayed in landscape mode (width > height) on the laptop screen.
> -
> -  The camera is typically mounted upside-down to compensate the lens
> -  optical inversion effect:
> -
> -                    Y-Rp
> -              Y-Rc   ^
> -               ^     !
> -               !     !
> -               !     !       |\_____)\__
> -               !     !       ) ____  ___.<
> -               !     !       |/    )/
> -               !     !
> -               !     !
> -               !     !
> -               !   0 +------------------------------------->
> -               !     0           X-Rp
> -             0 +------------------------------------->
> -               0            X-Rc
> -
> -  The two reference systems are aligned, the resulting camera rotation is
> -  0 degrees, no rotation correction needs to be applied to the resulting
> -  image once captured to memory buffers to correctly display it to users:
> -
> -               +--------------------------------------+
> -               !                                      !
> -               !                                      !
> -               !                                      !
> -               !             |\____)\___              !
> -               !             ) _____  __`<            !
> -               !             |/     )/                !
> -               !                                      !
> -               !                                      !
> -               !                                      !
> -               +--------------------------------------+
> -
> -  If the camera sensor is not mounted upside-down to compensate for the
> -  lens optical inversion, the two reference systems will not be aligned,
> -  with 'Rp' being rotated 180 degrees relatively to 'Rc':
> -
> -
> -                        X-Rc                0
> -       <------------------------------------+ 0
> -                                            !
> -              Y-Rp                          !
> -               ^                            !
> -               !                            !
> -               !       |\_____)\__          !
> -               !       ) ____  ___.<        !
> -               !       |/    )/             !
> -               !                            !
> -               !                            !
> -               !                            V
> -               !                           Y-Rc
> -             0 +------------------------------------->
> -               0            X-Rp
> -
> -  The image once captured to memory will then be rotated by 180 degrees:
> -
> -               +--------------------------------------+
> -               !                                      !
> -               !                                      !
> -               !                                      !
> -               !              __/(_____/|             !
> -               !            >.___  ____ (             !
> -               !                 \(    \|             !
> -               !                                      !
> -               !                                      !
> -               !                                      !
> -               +--------------------------------------+
> -
> -  A software rotation correction of 180 degrees should be applied to
> -  correctly display the image:
> -
> -               +--------------------------------------+
> -               !                                      !
> -               !                                      !
> -               !                                      !
> -               !             |\____)\___              !
> -               !             ) _____  __`<            !
> -               !             |/     )/                !
> -               !                                      !
> -               !                                      !
> -               !                                      !
> -               +--------------------------------------+
> -
> -  Example two - Phone camera
> -
> -  A camera installed on the back side of a mobile device facing away from
> -  the user. The captured images are meant to be displayed in portrait mode
> -  (height > width) to match the device screen orientation and the device
> -  usage orientation used when taking the picture.
> -
> -  The camera sensor is typically mounted with its pixel array longer side
> -  aligned to the device longer side, upside-down mounted to compensate for
> -  the lens optical inversion effect:
> -
> -               0        Y-Rc
> -             0 +-------------------->
> -               !   Y-Rp
> -               !    ^
> -               !    !
> -               !    !
> -               !    !
> -               !    !            |\_____)\__
> -               !    !            ) ____  ___.<
> -               !    !            |/    )/
> -               !    !
> -               !    !
> -               !    !
> -               !  0 +------------------------------------->
> -               !    0                X-Rp
> -               !
> -               !
> -               !
> -               !
> -               V
> -              X-Rc
> -
> -  The two reference systems are not aligned and the 'Rp' reference
> -  system is rotated by 90 degrees in the counter-clockwise direction
> -  relatively to the 'Rc' reference system.
> -
> -  The image once captured to memory will be rotated:
> -
> -               +-------------------------------------+
> -               |                 _ _                 |
> -               |                \   /                |
> -               |                 | |                 |
> -               |                 | |                 |
> -               |                 |  >                |
> -               |                <  |                 |
> -               |                 | |                 |
> -               |                   .                 |
> -               |                  V                  |
> -               +-------------------------------------+
> -
> -  A correction of 90 degrees in counter-clockwise direction has to be
> -  applied to correctly display the image in portrait mode on the device
> -  screen:
> -
> -                        +--------------------+
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        |   |\____)\___      |
> -                        |   ) _____  __`<    |
> -                        |   |/     )/        |
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        |                    |
> -                        +--------------------+
> -
> -- orientation: The orientation of a device (typically an image sensor or a flash
> -  LED) describing its mounting position relative to the usage orientation of the
> -  system where the device is installed on.
> -  Possible values are:
> -  0 - Front. The device is mounted on the front facing side of the system.
> -  For mobile devices such as smartphones, tablets and laptops the front side is
> -  the user facing side.
> -  1 - Back. The device is mounted on the back side of the system, which is
> -  defined as the opposite side of the front facing one.
> -  2 - External. The device is not attached directly to the system but is
> -  attached in a way that allows it to move freely.
> -
> -Optional endpoint properties
> -----------------------------
> -
> -- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
> -- slave-mode: a boolean property indicating that the link is run in slave mode.
> -  The default when this property is not specified is master mode. In the slave
> -  mode horizontal and vertical synchronization signals are provided to the
> -  slave device (data source) by the master device (data sink). In the master
> -  mode the data source device is also the source of the synchronization signals.
> -- bus-type: data bus type. Possible values are:
> -  1 - MIPI CSI-2 C-PHY
> -  2 - MIPI CSI1
> -  3 - CCP2
> -  4 - MIPI CSI-2 D-PHY
> -  5 - Parallel
> -  6 - Bt.656
> -- bus-width: number of data lines actively used, valid for the parallel busses.
> -- data-shift: on the parallel data busses, if bus-width is used to specify the
> -  number of data lines, data-shift can be used to specify which data lines are
> -  used, e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
> -- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
> -- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively.
> -  Note, that if HSYNC and VSYNC polarities are not specified, embedded
> -  synchronization may be required, where supported.
> -- data-active: similar to HSYNC and VSYNC, specifies data line polarity.
> -- data-enable-active: similar to HSYNC and VSYNC, specifies the data enable
> -  signal polarity.
> -- field-even-active: field signal level during the even field data transmission.
> -- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock
> -  signal.
> -- sync-on-green-active: active state of Sync-on-green (SoG) signal, 0/1 for
> -  LOW/HIGH respectively.
> -- data-lanes: an array of physical data lane indexes. Position of an entry
> -  determines the logical lane number, while the value of an entry indicates
> -  physical lane, e.g. for 2-lane MIPI CSI-2 bus we could have
> -  "data-lanes = <1 2>;", assuming the clock lane is on hardware lane 0.
> -  If the hardware does not support lane reordering, monotonically
> -  incremented values shall be used from 0 or 1 onwards, depending on
> -  whether or not there is also a clock lane. This property is valid for
> -  serial busses only (e.g. MIPI CSI-2).
> -- clock-lanes: an array of physical clock lane indexes. Position of an entry
> -  determines the logical lane number, while the value of an entry indicates
> -  physical lane, e.g. for a MIPI CSI-2 bus we could have "clock-lanes = <0>;",
> -  which places the clock lane on hardware lane 0. This property is valid for
> -  serial busses only (e.g. MIPI CSI-2). Note that for the MIPI CSI-2 bus this
> -  array contains only one entry.
> -- clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous
> -  clock mode.
> -- link-frequencies: Allowed data bus frequencies. For MIPI CSI-2, for
> -  instance, this is the actual frequency of the bus, not bits per clock per
> -  lane value. An array of 64-bit unsigned integers.
> -- lane-polarities: an array of polarities of the lanes starting from the clock
> -  lane and followed by the data lanes in the same order as in data-lanes.
> -  Valid values are 0 (normal) and 1 (inverted). The length of the array
> -  should be the combined length of data-lanes and clock-lanes properties.
> -  If the lane-polarities property is omitted, the value must be interpreted
> -  as 0 (normal). This property is valid for serial busses only.
> -- strobe: Whether the clock signal is used as clock (0) or strobe (1). Used
> -  with CCP2, for instance.
> -
> -Example
> --------
> -
> -The example snippet below describes two data pipelines.  ov772x and imx074 are
> -camera sensors with a parallel and serial (MIPI CSI-2) video bus respectively.
> -Both sensors are on the I2C control bus corresponding to the i2c0 controller
> -node.  ov772x sensor is linked directly to the ceu0 video host interface.
> -imx074 is linked to ceu0 through the MIPI CSI-2 receiver (csi2). ceu0 has a
> -(single) DMA engine writing captured data to memory.  ceu0 node has a single
> -'port' node which may indicate that at any time only one of the following data
> -pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0.
> -
> -       ceu0: ceu@fe910000 {
> -               compatible = "renesas,sh-mobile-ceu";
> -               reg = <0xfe910000 0xa0>;
> -               interrupts = <0x880>;
> -
> -               mclk: master_clock {
> -                       compatible = "renesas,ceu-clock";
> -                       #clock-cells = <1>;
> -                       clock-frequency = <50000000>;   /* Max clock frequency */
> -                       clock-output-names = "mclk";
> -               };
> -
> -               port {
> -                       #address-cells = <1>;
> -                       #size-cells = <0>;
> -
> -                       /* Parallel bus endpoint */
> -                       ceu0_1: endpoint@1 {
> -                               reg = <1>;              /* Local endpoint # */
> -                               remote = <&ov772x_1_1>; /* Remote phandle */
> -                               bus-width = <8>;        /* Used data lines */
> -                               data-shift = <2>;       /* Lines 9:2 are used */
> -
> -                               /* If hsync-active/vsync-active are missing,
> -                                  embedded BT.656 sync is used */
> -                               hsync-active = <0>;     /* Active low */
> -                               vsync-active = <0>;     /* Active low */
> -                               data-active = <1>;      /* Active high */
> -                               pclk-sample = <1>;      /* Rising */
> -                       };
> -
> -                       /* MIPI CSI-2 bus endpoint */
> -                       ceu0_0: endpoint@0 {
> -                               reg = <0>;
> -                               remote = <&csi2_2>;
> -                       };
> -               };
> -       };
> -
> -       i2c0: i2c@fff20000 {
> -               ...
> -               ov772x_1: camera@21 {
> -                       compatible = "ovti,ov772x";
> -                       reg = <0x21>;
> -                       vddio-supply = <&regulator1>;
> -                       vddcore-supply = <&regulator2>;
> -
> -                       clock-frequency = <20000000>;
> -                       clocks = <&mclk 0>;
> -                       clock-names = "xclk";
> -
> -                       port {
> -                               /* With 1 endpoint per port no need for addresses. */
> -                               ov772x_1_1: endpoint {
> -                                       bus-width = <8>;
> -                                       remote-endpoint = <&ceu0_1>;
> -                                       hsync-active = <1>;
> -                                       vsync-active = <0>; /* Who came up with an
> -                                                              inverter here ?... */
> -                                       data-active = <1>;
> -                                       pclk-sample = <1>;
> -                               };
> -                       };
> -               };
> -
> -               imx074: camera@1a {
> -                       compatible = "sony,imx074";
> -                       reg = <0x1a>;
> -                       vddio-supply = <&regulator1>;
> -                       vddcore-supply = <&regulator2>;
> -
> -                       clock-frequency = <30000000>;   /* Shared clock with ov772x_1 */
> -                       clocks = <&mclk 0>;
> -                       clock-names = "sysclk";         /* Assuming this is the
> -                                                          name in the datasheet */
> -                       port {
> -                               imx074_1: endpoint {
> -                                       clock-lanes = <0>;
> -                                       data-lanes = <1 2>;
> -                                       remote-endpoint = <&csi2_1>;
> -                               };
> -                       };
> -               };
> -       };
> -
> -       csi2: csi2@ffc90000 {
> -               compatible = "renesas,sh-mobile-csi2";
> -               reg = <0xffc90000 0x1000>;
> -               interrupts = <0x17a0>;
> -               #address-cells = <1>;
> -               #size-cells = <0>;
> -
> -               port@1 {
> -                       compatible = "renesas,csi2c";   /* One of CSI2I and CSI2C. */
> -                       reg = <1>;                      /* CSI-2 PHY #1 of 2: PHY_S,
> -                                                          PHY_M has port address 0,
> -                                                          is unused. */
> -                       csi2_1: endpoint {
> -                               clock-lanes = <0>;
> -                               data-lanes = <2 1>;
> -                               remote-endpoint = <&imx074_1>;
> -                       };
> -               };
> -               port@2 {
> -                       reg = <2>;                      /* port 2: link to the CEU */
> -
> -                       csi2_2: endpoint {
> -                               remote-endpoint = <&ceu0_0>;
> -                       };
> -               };
> -       };
> +This file has moved to video-interfaces.yaml and video-interface-devices.yaml.
> diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml
> new file mode 100644
> index 000000000000..0a7a73fd59f2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml
> @@ -0,0 +1,344 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/media/video-interfaces.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Common bindings for video receiver and transmitter interface endpoints
> +
> +maintainers:
> +  - Sakari Ailus <sakari.ailus@linux.intel.com>
> +  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> +
> +description: |
> +  Video data pipelines usually consist of external devices, e.g. camera sensors,
> +  controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including
> +  video DMA engines and video data processors.
> +
> +  SoC internal blocks are described by DT nodes, placed similarly to other SoC
> +  blocks.  External devices are represented as child nodes of their respective
> +  bus controller nodes, e.g. I2C.
> +
> +  Data interfaces on all video devices are described by their child 'port' nodes.
> +  Configuration of a port depends on other devices participating in the data
> +  transfer and is described by 'endpoint' subnodes.
> +
> +  device {
> +      ...
> +      ports {
> +          #address-cells = <1>;
> +          #size-cells = <0>;
> +
> +          port@0 {
> +              ...
> +              endpoint@0 { ... };
> +              endpoint@1 { ... };
> +          };
> +          port@1 { ... };
> +      };
> +  };
> +
> +  If a port can be configured to work with more than one remote device on the same
> +  bus, an 'endpoint' child node must be provided for each of them.  If more than
> +  one port is present in a device node or there is more than one endpoint at a
> +  port, or port node needs to be associated with a selected hardware interface,
> +  a common scheme using '#address-cells', '#size-cells' and 'reg' properties is
> +  used.
> +
> +  All 'port' nodes can be grouped under optional 'ports' node, which allows to
> +  specify #address-cells, #size-cells properties independently for the 'port'
> +  and 'endpoint' nodes and any child device nodes a device might have.
> +
> +  Two 'endpoint' nodes are linked with each other through their 'remote-endpoint'
> +  phandles.  An endpoint subnode of a device contains all properties needed for
> +  configuration of this device for data exchange with other device.  In most
> +  cases properties at the peer 'endpoint' nodes will be identical, however they
> +  might need to be different when there is any signal modifications on the bus
> +  between two devices, e.g. there are logic signal inverters on the lines.
> +
> +  It is allowed for multiple endpoints at a port to be active simultaneously,
> +  where supported by a device.  For example, in case where a data interface of
> +  a device is partitioned into multiple data busses, e.g. 16-bit input port
> +  divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
> +  and data-shift properties can be used to assign physical data lines to each
> +  endpoint node (logical bus).
> +
> +  Documenting bindings for devices
> +  --------------------------------
> +
> +  All required and optional bindings the device supports shall be explicitly
> +  documented in device DT binding documentation. This also includes port and
> +  endpoint nodes for the device, including unit-addresses and reg properties
> +  where relevant.
> +
> +allOf:
> +  - $ref: /schemas/graph.yaml#/$defs/endpoint-base
> +
> +properties:
> +  slave-mode:
> +    type: boolean
> +    description:
> +      Indicates that the link is run in slave mode. The default when this
> +      property is not specified is master mode. In the slave mode horizontal and
> +      vertical synchronization signals are provided to the slave device (data
> +      source) by the master device (data sink). In the master mode the data
> +      source device is also the source of the synchronization signals.
> +
> +  bus-type:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum:
> +      - 1 # MIPI CSI-2 C-PHY
> +      - 2 # MIPI CSI1
> +      - 3 # CCP2
> +      - 4 # MIPI CSI-2 D-PHY
> +      - 5 # Parallel
> +      - 6 # BT.656
> +    description:
> +      Data bus type.
> +
> +  bus-width:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    maximum: 64
> +    description:
> +      Number of data lines actively used, valid for the parallel busses.
> +
> +  data-shift:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    maximum: 64
> +    description:
> +      On the parallel data busses, if bus-width is used to specify the number of
> +      data lines, data-shift can be used to specify which data lines are used,
> +      e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
> +
> +  hsync-active:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
> +
> +  vsync-active:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. Note,
> +      that if HSYNC and VSYNC polarities are not specified, embedded
> +      synchronization may be required, where supported.
> +
> +  data-active:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Similar to HSYNC and VSYNC, specifies data line polarity.
> +
> +  data-enable-active:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Similar to HSYNC and VSYNC, specifies the data enable signal polarity.
> +
> +  field-even-active:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Field signal level during the even field data transmission.
> +
> +  pclk-sample:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Sample data on rising (1) or falling (0) edge of the pixel clock signal.
> +
> +  sync-on-green-active:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively.
> +
> +  data-lanes:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 1
> +    maxItems: 8
> +    items:
> +      # Assume up to 9 physical lane indices
> +      maximum: 8
> +    description:
> +      An array of physical data lane indexes. Position of an entry determines
> +      the logical lane number, while the value of an entry indicates physical
> +      lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1 2>;",
> +      assuming the clock lane is on hardware lane 0. If the hardware does not
> +      support lane reordering, monotonically incremented values shall be used
> +      from 0 or 1 onwards, depending on whether or not there is also a clock
> +      lane. This property is valid for serial busses only (e.g. MIPI CSI-2).
> +
> +  clock-lanes:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    # Assume up to 9 physical lane indices
> +    maximum: 8
> +    description:
> +      Physical clock lane index. Position of an entry determines the logical
> +      lane number, while the value of an entry indicates physical lane, e.g. for
> +      a MIPI CSI-2 bus we could have "clock-lanes = <0>;", which places the
> +      clock lane on hardware lane 0. This property is valid for serial busses
> +      only (e.g. MIPI CSI-2).
> +
> +  clock-noncontinuous:
> +    type: boolean
> +    description:
> +      Allow MIPI CSI-2 non-continuous clock mode.
> +
> +  link-frequencies:
> +    $ref: /schemas/types.yaml#/definitions/uint64-array
> +    description:
> +      Allowed data bus frequencies. For MIPI CSI-2, for instance, this is the
> +      actual frequency of the bus, not bits per clock per lane value. An array
> +      of 64-bit unsigned integers.
> +
> +  lane-polarities:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 1
> +    maxItems: 9
> +    items:
> +      enum: [ 0, 1 ]
> +    description:
> +      An array of polarities of the lanes starting from the clock lane and
> +      followed by the data lanes in the same order as in data-lanes. Valid
> +      values are 0 (normal) and 1 (inverted). The length of the array should be
> +      the combined length of data-lanes and clock-lanes properties. If the
> +      lane-polarities property is omitted, the value must be interpreted as 0
> +      (normal). This property is valid for serial busses only.
> +
> +  strobe:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    enum: [ 0, 1 ]
> +    description:
> +      Whether the clock signal is used as clock (0) or strobe (1). Used with
> +      CCP2, for instance.
> +
> +additionalProperties: true
> +
> +examples:
> +  # The example snippet below describes two data pipelines.  ov772x and imx074
> +  # are camera sensors with a parallel and serial (MIPI CSI-2) video bus
> +  # respectively. Both sensors are on the I2C control bus corresponding to the
> +  # i2c0 controller node.  ov772x sensor is linked directly to the ceu0 video
> +  # host interface. imx074 is linked to ceu0 through the MIPI CSI-2 receiver
> +  # (csi2). ceu0 has a (single) DMA engine writing captured data to memory.
> +  # ceu0 node has a single 'port' node which may indicate that at any time
> +  # only one of the following data pipelines can be active:
> +  # ov772x -> ceu0 or imx074 -> csi2 -> ceu0.
> +  - |
> +    ceu@fe910000 {
> +        compatible = "renesas,sh-mobile-ceu";
> +        reg = <0xfe910000 0xa0>;
> +        interrupts = <0x880>;
> +
> +        mclk: master_clock {
> +            compatible = "renesas,ceu-clock";
> +            #clock-cells = <1>;
> +            clock-frequency = <50000000>;  /* Max clock frequency */
> +            clock-output-names = "mclk";
> +        };
> +
> +        port {
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            /* Parallel bus endpoint */
> +            ceu0_1: endpoint@1 {
> +                reg = <1>;    /* Local endpoint # */
> +                remote-endpoint = <&ov772x_1_1>;  /* Remote phandle */
> +                bus-width = <8>;  /* Used data lines */
> +                data-shift = <2>;  /* Lines 9:2 are used */
> +
> +                /* If hsync-active/vsync-active are missing,
> +                   embedded BT.656 sync is used */
> +                hsync-active = <0>;  /* Active low */
> +                vsync-active = <0>;  /* Active low */
> +                data-active = <1>;  /* Active high */
> +                pclk-sample = <1>;  /* Rising */
> +            };
> +
> +            /* MIPI CSI-2 bus endpoint */
> +            ceu0_0: endpoint@0 {
> +                reg = <0>;
> +                remote-endpoint = <&csi2_2>;
> +            };
> +        };
> +    };
> +
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        camera@21 {
> +            compatible = "ovti,ov772x";
> +            reg = <0x21>;
> +            vddio-supply = <&regulator1>;
> +            vddcore-supply = <&regulator2>;
> +
> +            clock-frequency = <20000000>;
> +            clocks = <&mclk 0>;
> +            clock-names = "xclk";
> +
> +            port {
> +                /* With 1 endpoint per port no need for addresses. */
> +                ov772x_1_1: endpoint {
> +                    bus-width = <8>;
> +                    remote-endpoint = <&ceu0_1>;
> +                    hsync-active = <1>;
> +                    vsync-active = <0>; /* Who came up with an
> +                               inverter here ?... */
> +                    data-active = <1>;
> +                    pclk-sample = <1>;
> +                };
> +            };
> +        };
> +
> +        camera@1a {
> +            compatible = "sony,imx074";
> +            reg = <0x1a>;
> +            vddio-supply = <&regulator1>;
> +            vddcore-supply = <&regulator2>;
> +
> +            clock-frequency = <30000000>;  /* Shared clock with ov772x_1 */
> +            clocks = <&mclk 0>;
> +            clock-names = "sysclk";    /* Assuming this is the
> +                       name in the datasheet */
> +            port {
> +                imx074_1: endpoint {
> +                    clock-lanes = <0>;
> +                    data-lanes = <1 2>;
> +                    remote-endpoint = <&csi2_1>;
> +                };
> +            };
> +        };
> +    };
> +
> +    csi2: csi2@ffc90000 {
> +        compatible = "renesas,sh-mobile-csi2";
> +        reg = <0xffc90000 0x1000>;
> +        interrupts = <0x17a0>;
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        port@1 {
> +            compatible = "renesas,csi2c";  /* One of CSI2I and CSI2C. */
> +            reg = <1>;      /* CSI-2 PHY #1 of 2: PHY_S,
> +                       PHY_M has port address 0,
> +                       is unused. */
> +            csi2_1: endpoint {
> +                clock-lanes = <0>;
> +                data-lanes = <2 1>;
> +                remote-endpoint = <&imx074_1>;
> +            };
> +        };
> +        port@2 {
> +            reg = <2>;      /* port 2: link to the CEU */
> +
> +            csi2_2: endpoint {
> +                remote-endpoint = <&ceu0_0>;
> +            };
> +        };
> +    };
> +
> +...
> --
> 2.27.0
>
Sakari Ailus Jan. 22, 2021, 5:01 p.m. UTC | #2
Hi Rob,

On Fri, Jan 22, 2021 at 10:23:44AM -0600, Rob Herring wrote:
> On Mon, Jan 4, 2021 at 10:58 AM Rob Herring <robh@kernel.org> wrote:

> >

> > Convert video-interfaces.txt to DT schema. As it contains a mixture of

> > device level and endpoint properties, split it up into 2 schemas.

> 

> Ping!

> 

> Can this please be applied to the media tree so I can tell folks to

> use it in reviews of media bindings.


Yes, it can. It's in my tree now.

-- 
Kind regards,

Sakari Ailus
Mauro Carvalho Chehab Jan. 22, 2021, 9:43 p.m. UTC | #3
Em Fri, 22 Jan 2021 19:01:44 +0200
Sakari Ailus <sakari.ailus@linux.intel.com> escreveu:

> Hi Rob,

> 

> On Fri, Jan 22, 2021 at 10:23:44AM -0600, Rob Herring wrote:

> > On Mon, Jan 4, 2021 at 10:58 AM Rob Herring <robh@kernel.org> wrote:  

> > >

> > > Convert video-interfaces.txt to DT schema. As it contains a mixture of

> > > device level and endpoint properties, split it up into 2 schemas.  

> > 

> > Ping!

> > 

> > Can this please be applied to the media tree so I can tell folks to

> > use it in reviews of media bindings.  


Just merged both patches.

> Yes, it can. It's in my tree now.




Thanks,
Mauro
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/media/video-interface-devices.yaml b/Documentation/devicetree/bindings/media/video-interface-devices.yaml
new file mode 100644
index 000000000000..4527f56a5a6e
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/video-interface-devices.yaml
@@ -0,0 +1,406 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/video-interface-devices.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for video receiver and transmitter devices
+
+maintainers:
+  - Jacopo Mondi <jacopo@jmondi.org>
+  - Sakari Ailus <sakari.ailus@linux.intel.com>
+
+properties:
+  flash-leds:
+    $ref: /schemas/types.yaml#/definitions/phandle-array
+    description:
+      An array of phandles, each referring to a flash LED, a sub-node of the LED
+      driver device node.
+
+  lens-focus:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description:
+      A phandle to the node of the focus lens controller.
+
+  rotation:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 90, 180, 270 ]
+    description: |
+      The camera rotation is expressed as the angular difference in degrees
+      between two reference systems, one relative to the camera module, and one
+      defined on the external world scene to be captured when projected on the
+      image sensor pixel array.
+
+      A camera sensor has a 2-dimensional reference system 'Rc' defined by its
+      pixel array read-out order. The origin is set to the first pixel being
+      read out, the X-axis points along the column read-out direction towards
+      the last columns, and the Y-axis along the row read-out direction towards
+      the last row.
+
+      A typical example for a sensor with a 2592x1944 pixel array matrix
+      observed from the front is:
+
+              2591       X-axis          0
+                <------------------------+ 0
+                .......... ... ..........!
+                .......... ... ..........! Y-axis
+                           ...           !
+                .......... ... ..........!
+                .......... ... ..........! 1943
+                                         V
+
+      The external world scene reference system 'Rs' is a 2-dimensional
+      reference system on the focal plane of the camera module. The origin is
+      placed on the top-left corner of the visible scene, the X-axis points
+      towards the right, and the Y-axis points towards the bottom of the scene.
+      The top, bottom, left and right directions are intentionally not defined
+      and depend on the environment in which the camera is used.
+
+      A typical example of a (very common) picture of a shark swimming from left
+      to right, as seen from the camera, is:
+
+               0               X-axis
+             0 +------------------------------------->
+               !
+               !
+               !
+               !           |\____)\___
+               !           ) _____  __`<
+               !           |/     )/
+               !
+               !
+               !
+               V
+             Y-axis
+
+      with the reference system 'Rs' placed on the camera focal plane:
+
+                                  ¸.·˙!
+                              ¸.·˙    !
+                  _       ¸.·˙        !
+               +-/ \-+¸.·˙            !
+               | (o) |                ! Camera focal plane
+               +-----+˙·.¸            !
+                          ˙·.¸        !
+                              ˙·.¸    !
+                                  ˙·.¸!
+
+      When projected on the sensor's pixel array, the image and the associated
+      reference system 'Rs' are typically (but not always) inverted, due to the
+      camera module's lens optical inversion effect.
+
+      Assuming the above represented scene of the swimming shark, the lens
+      inversion projects the scene and its reference system onto the sensor
+      pixel array, seen from the front of the camera sensor, as follows:
+
+            Y-axis
+               ^
+               !
+               !
+               !
+               !            |\_____)\__
+               !            ) ____  ___.<
+               !            |/    )/
+               !
+               !
+               !
+             0 +------------------------------------->
+               0               X-axis
+
+      Note the shark being upside-down.
+
+      The resulting projected reference system is named 'Rp'.
+
+      The camera rotation property is then defined as the angular difference in
+      the counter-clockwise direction between the camera reference system 'Rc'
+      and the projected scene reference system 'Rp'. It is expressed in degrees
+      as a number in the range [0, 360[.
+
+      Examples
+
+      0 degrees camera rotation:
+
+
+                    Y-Rp
+                     ^
+              Y-Rc   !
+               ^     !
+               !     !
+               !     !
+               !     !
+               !     !
+               !     !
+               !     !
+               !     !
+               !   0 +------------------------------------->
+               !     0               X-Rp
+             0 +------------------------------------->
+               0               X-Rc
+
+
+                                X-Rc                0
+               <------------------------------------+ 0
+                           X-Rp                 0   !
+           <------------------------------------+ 0 !
+                                                !   !
+                                                !   !
+                                                !   !
+                                                !   !
+                                                !   !
+                                                !   !
+                                                !   !
+                                                !   V
+                                                !  Y-Rc
+                                                V
+                                               Y-Rp
+
+      90 degrees camera rotation:
+
+               0        Y-Rc
+             0 +-------------------->
+               !   Y-Rp
+               !    ^
+               !    !
+               !    !
+               !    !
+               !    !
+               !    !
+               !    !
+               !    !
+               !    !
+               !    !
+               !  0 +------------------------------------->
+               !    0              X-Rp
+               !
+               !
+               !
+               !
+               V
+              X-Rc
+
+      180 degrees camera rotation:
+
+                                            0
+       <------------------------------------+ 0
+                        X-Rc                !
+              Y-Rp                          !
+               ^                            !
+               !                            !
+               !                            !
+               !                            !
+               !                            !
+               !                            !
+               !                            !
+               !                            V
+               !                           Y-Rc
+             0 +------------------------------------->
+               0              X-Rp
+
+      270 degrees camera rotation:
+
+               0        Y-Rc
+             0 +-------------------->
+               !                                        0
+               !    <-----------------------------------+ 0
+               !                    X-Rp                !
+               !                                        !
+               !                                        !
+               !                                        !
+               !                                        !
+               !                                        !
+               !                                        !
+               !                                        !
+               !                                        !
+               !                                        V
+               !                                       Y-Rp
+               !
+               !
+               !
+               !
+               V
+              X-Rc
+
+
+      Example one - Webcam
+
+      A camera module installed on the user facing part of a laptop screen
+      casing used for video calls. The captured images are meant to be displayed
+      in landscape mode (width > height) on the laptop screen.
+
+      The camera is typically mounted upside-down to compensate the lens optical
+      inversion effect:
+
+                    Y-Rp
+              Y-Rc   ^
+               ^     !
+               !     !
+               !     !       |\_____)\__
+               !     !       ) ____  ___.<
+               !     !       |/    )/
+               !     !
+               !     !
+               !     !
+               !   0 +------------------------------------->
+               !     0           X-Rp
+             0 +------------------------------------->
+               0            X-Rc
+
+      The two reference systems are aligned, the resulting camera rotation is
+      0 degrees, no rotation correction needs to be applied to the resulting
+      image once captured to memory buffers to correctly display it to users:
+
+               +--------------------------------------+
+               !                                      !
+               !                                      !
+               !                                      !
+               !             |\____)\___              !
+               !             ) _____  __`<            !
+               !             |/     )/                !
+               !                                      !
+               !                                      !
+               !                                      !
+               +--------------------------------------+
+
+      If the camera sensor is not mounted upside-down to compensate for the lens
+      optical inversion, the two reference systems will not be aligned, with
+      'Rp' being rotated 180 degrees relatively to 'Rc':
+
+
+                        X-Rc                0
+       <------------------------------------+ 0
+                                            !
+              Y-Rp                          !
+               ^                            !
+               !                            !
+               !       |\_____)\__          !
+               !       ) ____  ___.<        !
+               !       |/    )/             !
+               !                            !
+               !                            !
+               !                            V
+               !                           Y-Rc
+             0 +------------------------------------->
+               0            X-Rp
+
+      The image once captured to memory will then be rotated by 180 degrees:
+
+               +--------------------------------------+
+               !                                      !
+               !                                      !
+               !                                      !
+               !              __/(_____/|             !
+               !            >.___  ____ (             !
+               !                 \(    \|             !
+               !                                      !
+               !                                      !
+               !                                      !
+               +--------------------------------------+
+
+      A software rotation correction of 180 degrees should be applied to
+      correctly display the image:
+
+               +--------------------------------------+
+               !                                      !
+               !                                      !
+               !                                      !
+               !             |\____)\___              !
+               !             ) _____  __`<            !
+               !             |/     )/                !
+               !                                      !
+               !                                      !
+               !                                      !
+               +--------------------------------------+
+
+      Example two - Phone camera
+
+      A camera installed on the back side of a mobile device facing away from
+      the user. The captured images are meant to be displayed in portrait mode
+      (height > width) to match the device screen orientation and the device
+      usage orientation used when taking the picture.
+
+      The camera sensor is typically mounted with its pixel array longer side
+      aligned to the device longer side, upside-down mounted to compensate for
+      the lens optical inversion effect:
+
+               0        Y-Rc
+             0 +-------------------->
+               !   Y-Rp
+               !    ^
+               !    !
+               !    !
+               !    !
+               !    !            |\_____)\__
+               !    !            ) ____  ___.<
+               !    !            |/    )/
+               !    !
+               !    !
+               !    !
+               !  0 +------------------------------------->
+               !    0                X-Rp
+               !
+               !
+               !
+               !
+               V
+              X-Rc
+
+      The two reference systems are not aligned and the 'Rp' reference system is
+      rotated by 90 degrees in the counter-clockwise direction relatively to the
+      'Rc' reference system.
+
+      The image once captured to memory will be rotated:
+
+               +-------------------------------------+
+               |                 _ _                 |
+               |                \   /                |
+               |                 | |                 |
+               |                 | |                 |
+               |                 |  >                |
+               |                <  |                 |
+               |                 | |                 |
+               |                   .                 |
+               |                  V                  |
+               +-------------------------------------+
+
+      A correction of 90 degrees in counter-clockwise direction has to be
+      applied to correctly display the image in portrait mode on the device
+      screen:
+
+                        +--------------------+
+                        |                    |
+                        |                    |
+                        |                    |
+                        |                    |
+                        |                    |
+                        |                    |
+                        |   |\____)\___      |
+                        |   ) _____  __`<    |
+                        |   |/     )/        |
+                        |                    |
+                        |                    |
+                        |                    |
+                        |                    |
+                        |                    |
+                        +--------------------+
+
+  orientation:
+    description:
+      The orientation of a device (typically an image sensor or a flash LED)
+      describing its mounting position relative to the usage orientation of the
+      system where the device is installed on.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum:
+        # Front. The device is mounted on the front facing side of the system. For
+        # mobile devices such as smartphones, tablets and laptops the front side
+        # is the user facing side.
+      - 0
+        # Back. The device is mounted on the back side of the system, which is
+        # defined as the opposite side of the front facing one.
+      - 1
+        # External. The device is not attached directly to the system but is
+        # attached in a way that allows it to move freely.
+      - 2
+
+additionalProperties: true
+
+...
diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
index 3920f25a9123..8fcf5f52bf5b 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.txt
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -1,639 +1 @@ 
-Common bindings for video receiver and transmitter interfaces
-
-General concept
----------------
-
-Video data pipelines usually consist of external devices, e.g. camera sensors,
-controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including
-video DMA engines and video data processors.
-
-SoC internal blocks are described by DT nodes, placed similarly to other SoC
-blocks.  External devices are represented as child nodes of their respective
-bus controller nodes, e.g. I2C.
-
-Data interfaces on all video devices are described by their child 'port' nodes.
-Configuration of a port depends on other devices participating in the data
-transfer and is described by 'endpoint' subnodes.
-
-device {
-	...
-	ports {
-		#address-cells = <1>;
-		#size-cells = <0>;
-
-		port@0 {
-			...
-			endpoint@0 { ... };
-			endpoint@1 { ... };
-		};
-		port@1 { ... };
-	};
-};
-
-If a port can be configured to work with more than one remote device on the same
-bus, an 'endpoint' child node must be provided for each of them.  If more than
-one port is present in a device node or there is more than one endpoint at a
-port, or port node needs to be associated with a selected hardware interface,
-a common scheme using '#address-cells', '#size-cells' and 'reg' properties is
-used.
-
-All 'port' nodes can be grouped under optional 'ports' node, which allows to
-specify #address-cells, #size-cells properties independently for the 'port'
-and 'endpoint' nodes and any child device nodes a device might have.
-
-Two 'endpoint' nodes are linked with each other through their 'remote-endpoint'
-phandles.  An endpoint subnode of a device contains all properties needed for
-configuration of this device for data exchange with other device.  In most
-cases properties at the peer 'endpoint' nodes will be identical, however they
-might need to be different when there is any signal modifications on the bus
-between two devices, e.g. there are logic signal inverters on the lines.
-
-It is allowed for multiple endpoints at a port to be active simultaneously,
-where supported by a device.  For example, in case where a data interface of
-a device is partitioned into multiple data busses, e.g. 16-bit input port
-divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
-and data-shift properties can be used to assign physical data lines to each
-endpoint node (logical bus).
-
-Documenting bindings for devices
---------------------------------
-
-All required and optional bindings the device supports shall be explicitly
-documented in device DT binding documentation. This also includes port and
-endpoint nodes for the device, including unit-addresses and reg properties where
-relevant.
-
-Please also see Documentation/devicetree/bindings/graph.txt .
-
-Required properties
--------------------
-
-If there is more than one 'port' or more than one 'endpoint' node or 'reg'
-property is present in port and/or endpoint nodes the following properties
-are required in a relevant parent node:
-
- - #address-cells : number of cells required to define port/endpoint
-		    identifier, should be 1.
- - #size-cells    : should be zero.
-
-
-Optional properties
--------------------
-
-- flash-leds: An array of phandles, each referring to a flash LED, a sub-node
-  of the LED driver device node.
-
-- lens-focus: A phandle to the node of the focus lens controller.
-
-- rotation: The camera rotation is expressed as the angular difference in
-  degrees between two reference systems, one relative to the camera module, and
-  one defined on the external world scene to be captured when projected on the
-  image sensor pixel array.
-
-  A camera sensor has a 2-dimensional reference system 'Rc' defined by
-  its pixel array read-out order. The origin is set to the first pixel
-  being read out, the X-axis points along the column read-out direction
-  towards the last columns, and the Y-axis along the row read-out
-  direction towards the last row.
-
-  A typical example for a sensor with a 2592x1944 pixel array matrix
-  observed from the front is:
-
-              2591       X-axis          0
-                <------------------------+ 0
-                .......... ... ..........!
-                .......... ... ..........! Y-axis
-                           ...           !
-                .......... ... ..........!
-                .......... ... ..........! 1943
-                                         V
-
-  The external world scene reference system 'Rs' is a 2-dimensional
-  reference system on the focal plane of the camera module. The origin is
-  placed on the top-left corner of the visible scene, the X-axis points
-  towards the right, and the Y-axis points towards the bottom of the
-  scene. The top, bottom, left and right directions are intentionally not
-  defined and depend on the environment in which the camera is used.
-
-  A typical example of a (very common) picture of a shark swimming from
-  left to right, as seen from the camera, is:
-
-               0               X-axis
-             0 +------------------------------------->
-               !
-               !
-               !
-               !           |\____)\___
-               !           ) _____  __`<
-               !           |/     )/
-               !
-               !
-               !
-               V
-             Y-axis
-
-  with the reference system 'Rs' placed on the camera focal plane:
-
-                                  ¸.·˙!
-                              ¸.·˙    !
-                  _       ¸.·˙        !
-               +-/ \-+¸.·˙            !
-               | (o) |                ! Camera focal plane
-               +-----+˙·.¸            !
-                          ˙·.¸        !
-                              ˙·.¸    !
-                                  ˙·.¸!
-
-  When projected on the sensor's pixel array, the image and the associated
-  reference system 'Rs' are typically (but not always) inverted, due to
-  the camera module's lens optical inversion effect.
-
-  Assuming the above represented scene of the swimming shark, the lens
-  inversion projects the scene and its reference system onto the sensor
-  pixel array, seen from the front of the camera sensor, as follows:
-
-            Y-axis
-               ^
-               !
-               !
-               !
-               !            |\_____)\__
-               !            ) ____  ___.<
-               !            |/    )/
-               !
-               !
-               !
-             0 +------------------------------------->
-               0               X-axis
-
-  Note the shark being upside-down.
-
-  The resulting projected reference system is named 'Rp'.
-
-  The camera rotation property is then defined as the angular difference
-  in the counter-clockwise direction between the camera reference system
-  'Rc' and the projected scene reference system 'Rp'. It is expressed in
-  degrees as a number in the range [0, 360[.
-
-  Examples
-
-  0 degrees camera rotation:
-
-
-                    Y-Rp
-                     ^
-              Y-Rc   !
-               ^     !
-               !     !
-               !     !
-               !     !
-               !     !
-               !     !
-               !     !
-               !     !
-               !   0 +------------------------------------->
-               !     0               X-Rp
-             0 +------------------------------------->
-               0               X-Rc
-
-
-                                X-Rc                0
-               <------------------------------------+ 0
-                           X-Rp                 0   !
-           <------------------------------------+ 0 !
-                                                !   !
-                                                !   !
-                                                !   !
-                                                !   !
-                                                !   !
-                                                !   !
-                                                !   !
-                                                !   V
-                                                !  Y-Rc
-                                                V
-                                               Y-Rp
-
-  90 degrees camera rotation:
-
-               0        Y-Rc
-             0 +-------------------->
-               !   Y-Rp
-               !    ^
-               !    !
-               !    !
-               !    !
-               !    !
-               !    !
-               !    !
-               !    !
-               !    !
-               !    !
-               !  0 +------------------------------------->
-               !    0              X-Rp
-               !
-               !
-               !
-               !
-               V
-              X-Rc
-
-  180 degrees camera rotation:
-
-                                            0
-       <------------------------------------+ 0
-                        X-Rc                !
-              Y-Rp                          !
-               ^                            !
-               !                            !
-               !                            !
-               !                            !
-               !                            !
-               !                            !
-               !                            !
-               !                            V
-               !                           Y-Rc
-             0 +------------------------------------->
-               0              X-Rp
-
-  270 degrees camera rotation:
-
-               0        Y-Rc
-             0 +-------------------->
-               !                                        0
-               !    <-----------------------------------+ 0
-               !                    X-Rp                !
-               !                                        !
-               !                                        !
-               !                                        !
-               !                                        !
-               !                                        !
-               !                                        !
-               !                                        !
-               !                                        !
-               !                                        V
-               !                                       Y-Rp
-               !
-               !
-               !
-               !
-               V
-              X-Rc
-
-
-  Example one - Webcam
-
-  A camera module installed on the user facing part of a laptop screen
-  casing used for video calls. The captured images are meant to be
-  displayed in landscape mode (width > height) on the laptop screen.
-
-  The camera is typically mounted upside-down to compensate the lens
-  optical inversion effect:
-
-                    Y-Rp
-              Y-Rc   ^
-               ^     !
-               !     !
-               !     !       |\_____)\__
-               !     !       ) ____  ___.<
-               !     !       |/    )/
-               !     !
-               !     !
-               !     !
-               !   0 +------------------------------------->
-               !     0           X-Rp
-             0 +------------------------------------->
-               0            X-Rc
-
-  The two reference systems are aligned, the resulting camera rotation is
-  0 degrees, no rotation correction needs to be applied to the resulting
-  image once captured to memory buffers to correctly display it to users:
-
-               +--------------------------------------+
-               !                                      !
-               !                                      !
-               !                                      !
-               !             |\____)\___              !
-               !             ) _____  __`<            !
-               !             |/     )/                !
-               !                                      !
-               !                                      !
-               !                                      !
-               +--------------------------------------+
-
-  If the camera sensor is not mounted upside-down to compensate for the
-  lens optical inversion, the two reference systems will not be aligned,
-  with 'Rp' being rotated 180 degrees relatively to 'Rc':
-
-
-                        X-Rc                0
-       <------------------------------------+ 0
-                                            !
-              Y-Rp                          !
-               ^                            !
-               !                            !
-               !       |\_____)\__          !
-               !       ) ____  ___.<        !
-               !       |/    )/             !
-               !                            !
-               !                            !
-               !                            V
-               !                           Y-Rc
-             0 +------------------------------------->
-               0            X-Rp
-
-  The image once captured to memory will then be rotated by 180 degrees:
-
-               +--------------------------------------+
-               !                                      !
-               !                                      !
-               !                                      !
-               !              __/(_____/|             !
-               !            >.___  ____ (             !
-               !                 \(    \|             !
-               !                                      !
-               !                                      !
-               !                                      !
-               +--------------------------------------+
-
-  A software rotation correction of 180 degrees should be applied to
-  correctly display the image:
-
-               +--------------------------------------+
-               !                                      !
-               !                                      !
-               !                                      !
-               !             |\____)\___              !
-               !             ) _____  __`<            !
-               !             |/     )/                !
-               !                                      !
-               !                                      !
-               !                                      !
-               +--------------------------------------+
-
-  Example two - Phone camera
-
-  A camera installed on the back side of a mobile device facing away from
-  the user. The captured images are meant to be displayed in portrait mode
-  (height > width) to match the device screen orientation and the device
-  usage orientation used when taking the picture.
-
-  The camera sensor is typically mounted with its pixel array longer side
-  aligned to the device longer side, upside-down mounted to compensate for
-  the lens optical inversion effect:
-
-               0        Y-Rc
-             0 +-------------------->
-               !   Y-Rp
-               !    ^
-               !    !
-               !    !
-               !    !
-               !    !            |\_____)\__
-               !    !            ) ____  ___.<
-               !    !            |/    )/
-               !    !
-               !    !
-               !    !
-               !  0 +------------------------------------->
-               !    0                X-Rp
-               !
-               !
-               !
-               !
-               V
-              X-Rc
-
-  The two reference systems are not aligned and the 'Rp' reference
-  system is rotated by 90 degrees in the counter-clockwise direction
-  relatively to the 'Rc' reference system.
-
-  The image once captured to memory will be rotated:
-
-               +-------------------------------------+
-               |                 _ _                 |
-               |                \   /                |
-               |                 | |                 |
-               |                 | |                 |
-               |                 |  >                |
-               |                <  |                 |
-               |                 | |                 |
-               |                   .                 |
-               |                  V                  |
-               +-------------------------------------+
-
-  A correction of 90 degrees in counter-clockwise direction has to be
-  applied to correctly display the image in portrait mode on the device
-  screen:
-
-                        +--------------------+
-                        |                    |
-                        |                    |
-                        |                    |
-                        |                    |
-                        |                    |
-                        |                    |
-                        |   |\____)\___      |
-                        |   ) _____  __`<    |
-                        |   |/     )/        |
-                        |                    |
-                        |                    |
-                        |                    |
-                        |                    |
-                        |                    |
-                        +--------------------+
-
-- orientation: The orientation of a device (typically an image sensor or a flash
-  LED) describing its mounting position relative to the usage orientation of the
-  system where the device is installed on.
-  Possible values are:
-  0 - Front. The device is mounted on the front facing side of the system.
-  For mobile devices such as smartphones, tablets and laptops the front side is
-  the user facing side.
-  1 - Back. The device is mounted on the back side of the system, which is
-  defined as the opposite side of the front facing one.
-  2 - External. The device is not attached directly to the system but is
-  attached in a way that allows it to move freely.
-
-Optional endpoint properties
-----------------------------
-
-- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
-- slave-mode: a boolean property indicating that the link is run in slave mode.
-  The default when this property is not specified is master mode. In the slave
-  mode horizontal and vertical synchronization signals are provided to the
-  slave device (data source) by the master device (data sink). In the master
-  mode the data source device is also the source of the synchronization signals.
-- bus-type: data bus type. Possible values are:
-  1 - MIPI CSI-2 C-PHY
-  2 - MIPI CSI1
-  3 - CCP2
-  4 - MIPI CSI-2 D-PHY
-  5 - Parallel
-  6 - Bt.656
-- bus-width: number of data lines actively used, valid for the parallel busses.
-- data-shift: on the parallel data busses, if bus-width is used to specify the
-  number of data lines, data-shift can be used to specify which data lines are
-  used, e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
-- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
-- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively.
-  Note, that if HSYNC and VSYNC polarities are not specified, embedded
-  synchronization may be required, where supported.
-- data-active: similar to HSYNC and VSYNC, specifies data line polarity.
-- data-enable-active: similar to HSYNC and VSYNC, specifies the data enable
-  signal polarity.
-- field-even-active: field signal level during the even field data transmission.
-- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock
-  signal.
-- sync-on-green-active: active state of Sync-on-green (SoG) signal, 0/1 for
-  LOW/HIGH respectively.
-- data-lanes: an array of physical data lane indexes. Position of an entry
-  determines the logical lane number, while the value of an entry indicates
-  physical lane, e.g. for 2-lane MIPI CSI-2 bus we could have
-  "data-lanes = <1 2>;", assuming the clock lane is on hardware lane 0.
-  If the hardware does not support lane reordering, monotonically
-  incremented values shall be used from 0 or 1 onwards, depending on
-  whether or not there is also a clock lane. This property is valid for
-  serial busses only (e.g. MIPI CSI-2).
-- clock-lanes: an array of physical clock lane indexes. Position of an entry
-  determines the logical lane number, while the value of an entry indicates
-  physical lane, e.g. for a MIPI CSI-2 bus we could have "clock-lanes = <0>;",
-  which places the clock lane on hardware lane 0. This property is valid for
-  serial busses only (e.g. MIPI CSI-2). Note that for the MIPI CSI-2 bus this
-  array contains only one entry.
-- clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous
-  clock mode.
-- link-frequencies: Allowed data bus frequencies. For MIPI CSI-2, for
-  instance, this is the actual frequency of the bus, not bits per clock per
-  lane value. An array of 64-bit unsigned integers.
-- lane-polarities: an array of polarities of the lanes starting from the clock
-  lane and followed by the data lanes in the same order as in data-lanes.
-  Valid values are 0 (normal) and 1 (inverted). The length of the array
-  should be the combined length of data-lanes and clock-lanes properties.
-  If the lane-polarities property is omitted, the value must be interpreted
-  as 0 (normal). This property is valid for serial busses only.
-- strobe: Whether the clock signal is used as clock (0) or strobe (1). Used
-  with CCP2, for instance.
-
-Example
--------
-
-The example snippet below describes two data pipelines.  ov772x and imx074 are
-camera sensors with a parallel and serial (MIPI CSI-2) video bus respectively.
-Both sensors are on the I2C control bus corresponding to the i2c0 controller
-node.  ov772x sensor is linked directly to the ceu0 video host interface.
-imx074 is linked to ceu0 through the MIPI CSI-2 receiver (csi2). ceu0 has a
-(single) DMA engine writing captured data to memory.  ceu0 node has a single
-'port' node which may indicate that at any time only one of the following data
-pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0.
-
-	ceu0: ceu@fe910000 {
-		compatible = "renesas,sh-mobile-ceu";
-		reg = <0xfe910000 0xa0>;
-		interrupts = <0x880>;
-
-		mclk: master_clock {
-			compatible = "renesas,ceu-clock";
-			#clock-cells = <1>;
-			clock-frequency = <50000000>;	/* Max clock frequency */
-			clock-output-names = "mclk";
-		};
-
-		port {
-			#address-cells = <1>;
-			#size-cells = <0>;
-
-			/* Parallel bus endpoint */
-			ceu0_1: endpoint@1 {
-				reg = <1>;		/* Local endpoint # */
-				remote = <&ov772x_1_1>;	/* Remote phandle */
-				bus-width = <8>;	/* Used data lines */
-				data-shift = <2>;	/* Lines 9:2 are used */
-
-				/* If hsync-active/vsync-active are missing,
-				   embedded BT.656 sync is used */
-				hsync-active = <0>;	/* Active low */
-				vsync-active = <0>;	/* Active low */
-				data-active = <1>;	/* Active high */
-				pclk-sample = <1>;	/* Rising */
-			};
-
-			/* MIPI CSI-2 bus endpoint */
-			ceu0_0: endpoint@0 {
-				reg = <0>;
-				remote = <&csi2_2>;
-			};
-		};
-	};
-
-	i2c0: i2c@fff20000 {
-		...
-		ov772x_1: camera@21 {
-			compatible = "ovti,ov772x";
-			reg = <0x21>;
-			vddio-supply = <&regulator1>;
-			vddcore-supply = <&regulator2>;
-
-			clock-frequency = <20000000>;
-			clocks = <&mclk 0>;
-			clock-names = "xclk";
-
-			port {
-				/* With 1 endpoint per port no need for addresses. */
-				ov772x_1_1: endpoint {
-					bus-width = <8>;
-					remote-endpoint = <&ceu0_1>;
-					hsync-active = <1>;
-					vsync-active = <0>; /* Who came up with an
-							       inverter here ?... */
-					data-active = <1>;
-					pclk-sample = <1>;
-				};
-			};
-		};
-
-		imx074: camera@1a {
-			compatible = "sony,imx074";
-			reg = <0x1a>;
-			vddio-supply = <&regulator1>;
-			vddcore-supply = <&regulator2>;
-
-			clock-frequency = <30000000>;	/* Shared clock with ov772x_1 */
-			clocks = <&mclk 0>;
-			clock-names = "sysclk";		/* Assuming this is the
-							   name in the datasheet */
-			port {
-				imx074_1: endpoint {
-					clock-lanes = <0>;
-					data-lanes = <1 2>;
-					remote-endpoint = <&csi2_1>;
-				};
-			};
-		};
-	};
-
-	csi2: csi2@ffc90000 {
-		compatible = "renesas,sh-mobile-csi2";
-		reg = <0xffc90000 0x1000>;
-		interrupts = <0x17a0>;
-		#address-cells = <1>;
-		#size-cells = <0>;
-
-		port@1 {
-			compatible = "renesas,csi2c";	/* One of CSI2I and CSI2C. */
-			reg = <1>;			/* CSI-2 PHY #1 of 2: PHY_S,
-							   PHY_M has port address 0,
-							   is unused. */
-			csi2_1: endpoint {
-				clock-lanes = <0>;
-				data-lanes = <2 1>;
-				remote-endpoint = <&imx074_1>;
-			};
-		};
-		port@2 {
-			reg = <2>;			/* port 2: link to the CEU */
-
-			csi2_2: endpoint {
-				remote-endpoint = <&ceu0_0>;
-			};
-		};
-	};
+This file has moved to video-interfaces.yaml and video-interface-devices.yaml.
diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml
new file mode 100644
index 000000000000..0a7a73fd59f2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml
@@ -0,0 +1,344 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/media/video-interfaces.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Common bindings for video receiver and transmitter interface endpoints
+
+maintainers:
+  - Sakari Ailus <sakari.ailus@linux.intel.com>
+  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+description: |
+  Video data pipelines usually consist of external devices, e.g. camera sensors,
+  controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including
+  video DMA engines and video data processors.
+
+  SoC internal blocks are described by DT nodes, placed similarly to other SoC
+  blocks.  External devices are represented as child nodes of their respective
+  bus controller nodes, e.g. I2C.
+
+  Data interfaces on all video devices are described by their child 'port' nodes.
+  Configuration of a port depends on other devices participating in the data
+  transfer and is described by 'endpoint' subnodes.
+
+  device {
+      ...
+      ports {
+          #address-cells = <1>;
+          #size-cells = <0>;
+
+          port@0 {
+              ...
+              endpoint@0 { ... };
+              endpoint@1 { ... };
+          };
+          port@1 { ... };
+      };
+  };
+
+  If a port can be configured to work with more than one remote device on the same
+  bus, an 'endpoint' child node must be provided for each of them.  If more than
+  one port is present in a device node or there is more than one endpoint at a
+  port, or port node needs to be associated with a selected hardware interface,
+  a common scheme using '#address-cells', '#size-cells' and 'reg' properties is
+  used.
+
+  All 'port' nodes can be grouped under optional 'ports' node, which allows to
+  specify #address-cells, #size-cells properties independently for the 'port'
+  and 'endpoint' nodes and any child device nodes a device might have.
+
+  Two 'endpoint' nodes are linked with each other through their 'remote-endpoint'
+  phandles.  An endpoint subnode of a device contains all properties needed for
+  configuration of this device for data exchange with other device.  In most
+  cases properties at the peer 'endpoint' nodes will be identical, however they
+  might need to be different when there is any signal modifications on the bus
+  between two devices, e.g. there are logic signal inverters on the lines.
+
+  It is allowed for multiple endpoints at a port to be active simultaneously,
+  where supported by a device.  For example, in case where a data interface of
+  a device is partitioned into multiple data busses, e.g. 16-bit input port
+  divided into two separate ITU-R BT.656 8-bit busses.  In such case bus-width
+  and data-shift properties can be used to assign physical data lines to each
+  endpoint node (logical bus).
+
+  Documenting bindings for devices
+  --------------------------------
+
+  All required and optional bindings the device supports shall be explicitly
+  documented in device DT binding documentation. This also includes port and
+  endpoint nodes for the device, including unit-addresses and reg properties
+  where relevant.
+
+allOf:
+  - $ref: /schemas/graph.yaml#/$defs/endpoint-base
+
+properties:
+  slave-mode:
+    type: boolean
+    description:
+      Indicates that the link is run in slave mode. The default when this
+      property is not specified is master mode. In the slave mode horizontal and
+      vertical synchronization signals are provided to the slave device (data
+      source) by the master device (data sink). In the master mode the data
+      source device is also the source of the synchronization signals.
+
+  bus-type:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum:
+      - 1 # MIPI CSI-2 C-PHY
+      - 2 # MIPI CSI1
+      - 3 # CCP2
+      - 4 # MIPI CSI-2 D-PHY
+      - 5 # Parallel
+      - 6 # BT.656
+    description:
+      Data bus type.
+
+  bus-width:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    maximum: 64
+    description:
+      Number of data lines actively used, valid for the parallel busses.
+
+  data-shift:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    maximum: 64
+    description:
+      On the parallel data busses, if bus-width is used to specify the number of
+      data lines, data-shift can be used to specify which data lines are used,
+      e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
+
+  hsync-active:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
+
+  vsync-active:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. Note,
+      that if HSYNC and VSYNC polarities are not specified, embedded
+      synchronization may be required, where supported.
+
+  data-active:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Similar to HSYNC and VSYNC, specifies data line polarity.
+
+  data-enable-active:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Similar to HSYNC and VSYNC, specifies the data enable signal polarity.
+
+  field-even-active:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Field signal level during the even field data transmission.
+
+  pclk-sample:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Sample data on rising (1) or falling (0) edge of the pixel clock signal.
+
+  sync-on-green-active:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively.
+
+  data-lanes:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 1
+    maxItems: 8
+    items:
+      # Assume up to 9 physical lane indices
+      maximum: 8
+    description:
+      An array of physical data lane indexes. Position of an entry determines
+      the logical lane number, while the value of an entry indicates physical
+      lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1 2>;",
+      assuming the clock lane is on hardware lane 0. If the hardware does not
+      support lane reordering, monotonically incremented values shall be used
+      from 0 or 1 onwards, depending on whether or not there is also a clock
+      lane. This property is valid for serial busses only (e.g. MIPI CSI-2).
+
+  clock-lanes:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    # Assume up to 9 physical lane indices
+    maximum: 8
+    description:
+      Physical clock lane index. Position of an entry determines the logical
+      lane number, while the value of an entry indicates physical lane, e.g. for
+      a MIPI CSI-2 bus we could have "clock-lanes = <0>;", which places the
+      clock lane on hardware lane 0. This property is valid for serial busses
+      only (e.g. MIPI CSI-2).
+
+  clock-noncontinuous:
+    type: boolean
+    description:
+      Allow MIPI CSI-2 non-continuous clock mode.
+
+  link-frequencies:
+    $ref: /schemas/types.yaml#/definitions/uint64-array
+    description:
+      Allowed data bus frequencies. For MIPI CSI-2, for instance, this is the
+      actual frequency of the bus, not bits per clock per lane value. An array
+      of 64-bit unsigned integers.
+
+  lane-polarities:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 1
+    maxItems: 9
+    items:
+      enum: [ 0, 1 ]
+    description:
+      An array of polarities of the lanes starting from the clock lane and
+      followed by the data lanes in the same order as in data-lanes. Valid
+      values are 0 (normal) and 1 (inverted). The length of the array should be
+      the combined length of data-lanes and clock-lanes properties. If the
+      lane-polarities property is omitted, the value must be interpreted as 0
+      (normal). This property is valid for serial busses only.
+
+  strobe:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [ 0, 1 ]
+    description:
+      Whether the clock signal is used as clock (0) or strobe (1). Used with
+      CCP2, for instance.
+
+additionalProperties: true
+
+examples:
+  # The example snippet below describes two data pipelines.  ov772x and imx074
+  # are camera sensors with a parallel and serial (MIPI CSI-2) video bus
+  # respectively. Both sensors are on the I2C control bus corresponding to the
+  # i2c0 controller node.  ov772x sensor is linked directly to the ceu0 video
+  # host interface. imx074 is linked to ceu0 through the MIPI CSI-2 receiver
+  # (csi2). ceu0 has a (single) DMA engine writing captured data to memory.
+  # ceu0 node has a single 'port' node which may indicate that at any time
+  # only one of the following data pipelines can be active:
+  # ov772x -> ceu0 or imx074 -> csi2 -> ceu0.
+  - |
+    ceu@fe910000 {
+        compatible = "renesas,sh-mobile-ceu";
+        reg = <0xfe910000 0xa0>;
+        interrupts = <0x880>;
+
+        mclk: master_clock {
+            compatible = "renesas,ceu-clock";
+            #clock-cells = <1>;
+            clock-frequency = <50000000>;  /* Max clock frequency */
+            clock-output-names = "mclk";
+        };
+
+        port {
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            /* Parallel bus endpoint */
+            ceu0_1: endpoint@1 {
+                reg = <1>;    /* Local endpoint # */
+                remote-endpoint = <&ov772x_1_1>;  /* Remote phandle */
+                bus-width = <8>;  /* Used data lines */
+                data-shift = <2>;  /* Lines 9:2 are used */
+
+                /* If hsync-active/vsync-active are missing,
+                   embedded BT.656 sync is used */
+                hsync-active = <0>;  /* Active low */
+                vsync-active = <0>;  /* Active low */
+                data-active = <1>;  /* Active high */
+                pclk-sample = <1>;  /* Rising */
+            };
+
+            /* MIPI CSI-2 bus endpoint */
+            ceu0_0: endpoint@0 {
+                reg = <0>;
+                remote-endpoint = <&csi2_2>;
+            };
+        };
+    };
+
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        camera@21 {
+            compatible = "ovti,ov772x";
+            reg = <0x21>;
+            vddio-supply = <&regulator1>;
+            vddcore-supply = <&regulator2>;
+
+            clock-frequency = <20000000>;
+            clocks = <&mclk 0>;
+            clock-names = "xclk";
+
+            port {
+                /* With 1 endpoint per port no need for addresses. */
+                ov772x_1_1: endpoint {
+                    bus-width = <8>;
+                    remote-endpoint = <&ceu0_1>;
+                    hsync-active = <1>;
+                    vsync-active = <0>; /* Who came up with an
+                               inverter here ?... */
+                    data-active = <1>;
+                    pclk-sample = <1>;
+                };
+            };
+        };
+
+        camera@1a {
+            compatible = "sony,imx074";
+            reg = <0x1a>;
+            vddio-supply = <&regulator1>;
+            vddcore-supply = <&regulator2>;
+
+            clock-frequency = <30000000>;  /* Shared clock with ov772x_1 */
+            clocks = <&mclk 0>;
+            clock-names = "sysclk";    /* Assuming this is the
+                       name in the datasheet */
+            port {
+                imx074_1: endpoint {
+                    clock-lanes = <0>;
+                    data-lanes = <1 2>;
+                    remote-endpoint = <&csi2_1>;
+                };
+            };
+        };
+    };
+
+    csi2: csi2@ffc90000 {
+        compatible = "renesas,sh-mobile-csi2";
+        reg = <0xffc90000 0x1000>;
+        interrupts = <0x17a0>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        port@1 {
+            compatible = "renesas,csi2c";  /* One of CSI2I and CSI2C. */
+            reg = <1>;      /* CSI-2 PHY #1 of 2: PHY_S,
+                       PHY_M has port address 0,
+                       is unused. */
+            csi2_1: endpoint {
+                clock-lanes = <0>;
+                data-lanes = <2 1>;
+                remote-endpoint = <&imx074_1>;
+            };
+        };
+        port@2 {
+            reg = <2>;      /* port 2: link to the CEU */
+
+            csi2_2: endpoint {
+                remote-endpoint = <&ceu0_0>;
+            };
+        };
+    };
+
+...