# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/display/panel/panel-timing.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: panel timing

maintainers:
  - Thierry Reding <thierry.reding@gmail.com>
  - Sam Ravnborg <sam@ravnborg.org>

description: |
  There are different ways of describing the timing data of a panel. The
  devicetree representation corresponds to the one commonly found in datasheets
  for panels.

  The parameters are defined as seen in the following illustration.

  +-------+----------+-------------------------------------+----------+
  |       |          |        ^                            |          |
  |       |          |        |vsync_len                   |          |
  |       |          |        v                            |          |
  +-------+----------+-------------------------------------+----------+
  |       |          |        ^                            |          |
  |       |          |        |vback_porch                 |          |
  |       |          |        v                            |          |
  +-------+----------#######################################----------+
  |       |          #        ^                            #          |
  |       |          #        |                            #          |
  | hsync |  hback   #        |                            #  hfront  |
  |  len  |   porch  #        |       hactive              #  porch   |
  |<----->|<-------->#<-------+--------------------------->#<-------->|
  |       |          #        |                            #          |
  |       |          #        |vactive                     #          |
  |       |          #        |                            #          |
  |       |          #        v                            #          |
  +-------+----------#######################################----------+
  |       |          |        ^                            |          |
  |       |          |        |vfront_porch                |          |
  |       |          |        v                            |          |
  +-------+----------+-------------------------------------+----------+


  The following is the panel timings shown with time on the x-axis.
  This matches the timing diagrams often found in data sheets.

              Active                 Front           Sync           Back
              Region                 Porch                          Porch
  <-----------------------><----------------><-------------><-------------->
    //////////////////////|
   ////////////////////// |
  //////////////////////  |..................               ................
                                             _______________

  Timing can be specified either as a typical value or as a tuple
  of min, typ, max values.

properties:

  clock-frequency:
    description: Panel clock in Hz

  hactive:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Horizontal panel resolution in pixels

  vactive:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: Vertical panel resolution in pixels

  hfront-porch:
    description: Horizontal front porch panel timing
    $ref: /schemas/types.yaml#/definitions/uint32-array
    oneOf:
      - maxItems: 1
        items:
          description: typical number of pixels
      - minItems: 3
        maxItems: 3
        items:
          description: min, typ, max number of pixels

  hback-porch:
    description: Horizontal back porch timing
    $ref: /schemas/types.yaml#/definitions/uint32-array
    oneOf:
      - maxItems: 1
        items:
          description: typical number of pixels
      - minItems: 3
        maxItems: 3
        items:
          description: min, typ, max number of pixels

  hsync-len:
    description: Horizontal sync length panel timing
    $ref: /schemas/types.yaml#/definitions/uint32-array
    oneOf:
      - maxItems: 1
        items:
          description: typical number of pixels
      - minItems: 3
        maxItems: 3
        items:
          description: min, typ, max number of pixels

  vfront-porch:
    description: Vertical front porch panel timing
    $ref: /schemas/types.yaml#/definitions/uint32-array
    oneOf:
      - maxItems: 1
        items:
          description: typical number of lines
      - minItems: 3
        maxItems: 3
        items:
          description: min, typ, max number of lines

  vback-porch:
    description: Vertical back porch panel timing
    $ref: /schemas/types.yaml#/definitions/uint32-array
    oneOf:
      - maxItems: 1
        items:
          description: typical number of lines
      - minItems: 3
        maxItems: 3
        items:
          description: min, typ, max number of lines

  vsync-len:
    description: Vertical sync length panel timing
    $ref: /schemas/types.yaml#/definitions/uint32-array
    oneOf:
      - maxItems: 1
        items:
          description: typical number of lines
      - minItems: 3
        maxItems: 3
        items:
          description: min, typ, max number of lines

  hsync-active:
    description: |
      Horizontal sync pulse.
      0 selects active low, 1 selects active high.
      If omitted then it is not used by the hardware
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]

  vsync-active:
    description: |
      Vertical sync pulse.
      0 selects active low, 1 selects active high.
      If omitted then it is not used by the hardware
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]

  de-active:
    description: |
      Data enable.
      0 selects active low, 1 selects active high.
      If omitted then it is not used by the hardware
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]

  pixelclk-active:
    description: |
      Data driving on rising or falling edge.
      Use 0 to drive pixel data on falling edge and
      sample data on rising edge.
      Use 1 to drive pixel data on rising edge and
      sample data on falling edge
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]

  syncclk-active:
    description: |
      Drive sync on rising or sample sync on falling edge.
      If not specified then the setup is as specified by pixelclk-active.
      Use 0 to drive sync on falling edge and
      sample sync on rising edge of pixel clock.
      Use 1 to drive sync on rising edge and
      sample sync on falling edge of pixel clock
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]

  interlaced:
    type: boolean
    description: Enable interlaced mode

  doublescan:
    type: boolean
    description: Enable double scan mode

  doubleclk:
    type: boolean
    description: Enable double clock mode

required:
  - clock-frequency
  - hactive
  - vactive
  - hfront-porch
  - hback-porch
  - hsync-len
  - vfront-porch
  - vback-porch
  - vsync-len

additionalProperties: false

...