Documentation/devicetree/bindings/display/xylon,logicvc-display.yaml

   1 # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
   2 # Copyright 2019 Bootlin
   3 %YAML 1.2
   4 ---
   5 $id: http://devicetree.org/schemas/display/xylon,logicvc-display.yaml#
   6 $schema: http://devicetree.org/meta-schemas/core.yaml#
   7
   8 title: Xylon LogiCVC display controller
   9
  10 maintainers:
  11   - Paul Kocialkowski <paul.kocialkowski@bootlin.com>
  12
  13 description: |
  14   The Xylon LogiCVC is a display controller that supports multiple layers.
  15   It is usually implemented as programmable logic and was optimized for use
  16   with Xilinx Zynq-7000 SoCs and Xilinx FPGAs.
  17
  18   Because the controller is intended for use in a FPGA, most of the
  19   configuration of the controller takes place at logic configuration bitstream
  20   synthesis time. As a result, many of the device-tree bindings are meant to
  21   reflect the synthesis configuration and must not be configured differently.
  22   Matching synthesis parameters are provided when applicable.
  23
  24   Layers are declared in the "layers" sub-node and have dedicated configuration.
  25   In version 3 of the controller, each layer has fixed memory offset and address
  26   starting from the video memory base address for its framebuffer. In version 4,
  27   framebuffers are configured with a direct memory address instead.
  28
  29 properties:
  30   compatible:
  31     enum:
  32       - xylon,logicvc-3.02.a-display
  33       - xylon,logicvc-4.01.a-display
  34
  35   reg:
  36     maxItems: 1
  37
  38   clocks:
  39     minItems: 1
  40     maxItems: 4
  41
  42   clock-names:
  43     minItems: 1
  44     items:
  45       # vclk is required and must be provided as first item.
  46       - const: vclk
  47       # Other clocks are optional and can be provided in any order.
  48       - enum:
  49           - vclk2
  50           - lvdsclk
  51           - lvdsclkn
  52       - enum:
  53           - vclk2
  54           - lvdsclk
  55           - lvdsclkn
  56       - enum:
  57           - vclk2
  58           - lvdsclk
  59           - lvdsclkn
  60
  61   interrupts:
  62     maxItems: 1
  63
  64   memory-region:
  65     maxItems: 1
  66
  67   xylon,display-interface:
  68     enum:
  69       # Parallel RGB interface (C_DISPLAY_INTERFACE == 0)
  70       - parallel-rgb
  71       # ITU-T BR656 interface (C_DISPLAY_INTERFACE == 1)
  72       - bt656
  73       # 4-bit LVDS interface (C_DISPLAY_INTERFACE == 2)
  74       - lvds-4bits
  75       # 3-bit LVDS interface (C_DISPLAY_INTERFACE == 4)
  76       - lvds-3bits
  77       # DVI interface (C_DISPLAY_INTERFACE == 5)
  78       - dvi
  79     description: Display output interface (C_DISPLAY_INTERFACE).
  80
  81   xylon,display-colorspace:
  82     enum:
  83       # RGB colorspace (C_DISPLAY_COLOR_SPACE == 0)
  84       - rgb
  85       # YUV 4:2:2 colorspace (C_DISPLAY_COLOR_SPACE == 1)
  86       - yuv422
  87       # YUV 4:4:4 colorspace (C_DISPLAY_COLOR_SPACE == 2)
  88       - yuv444
  89     description: Display output colorspace (C_DISPLAY_COLOR_SPACE).
  90
  91   xylon,display-depth:
  92     $ref: /schemas/types.yaml#/definitions/uint32
  93     description: Display output depth (C_PIXEL_DATA_WIDTH).
  94
  95   xylon,row-stride:
  96     $ref: /schemas/types.yaml#/definitions/uint32
  97     description: Fixed number of pixels in a framebuffer row (C_ROW_STRIDE).
  98
  99   xylon,dithering:
 100     $ref: /schemas/types.yaml#/definitions/flag
 101     description: Dithering module is enabled (C_XCOLOR)
 102
 103   xylon,background-layer:
 104     $ref: /schemas/types.yaml#/definitions/flag
 105     description: |
 106       The last layer is used to display a black background (C_USE_BACKGROUND).
 107       The layer must still be registered.
 108
 109   xylon,layers-configurable:
 110     $ref: /schemas/types.yaml#/definitions/flag
 111     description: |
 112       Configuration of layers' size, position and offset is enabled
 113       (C_USE_SIZE_POSITION).
 114
 115   layers:
 116     type: object
 117
 118     properties:
 119       "#address-cells":
 120         const: 1
 121
 122       "#size-cells":
 123         const: 0
 124
 125     patternProperties:
 126       "^layer@[0-9]+$":
 127         type: object
 128
 129         properties:
 130           reg:
 131             maxItems: 1
 132
 133           xylon,layer-depth:
 134             $ref: /schemas/types.yaml#/definitions/uint32
 135             description: Layer depth (C_LAYER_X_DATA_WIDTH).
 136
 137           xylon,layer-colorspace:
 138             enum:
 139               # RGB colorspace (C_LAYER_X_TYPE == 0)
 140               - rgb
 141               # YUV packed colorspace (C_LAYER_X_TYPE == 0)
 142               - yuv
 143             description: Layer colorspace (C_LAYER_X_TYPE).
 144
 145           xylon,layer-alpha-mode:
 146             enum:
 147               # Alpha is configured layer-wide (C_LAYER_X_ALPHA_MODE == 0)
 148               - layer
 149               # Alpha is configured per-pixel (C_LAYER_X_ALPHA_MODE == 1)
 150               - pixel
 151             description: Alpha mode for the layer (C_LAYER_X_ALPHA_MODE).
 152
 153           xylon,layer-base-offset:
 154             $ref: /schemas/types.yaml#/definitions/uint32
 155             description: |
 156               Offset in number of lines (C_LAYER_X_OFFSET) starting from the
 157               video RAM base (C_VMEM_BASEADDR), only for version 3.
 158
 159           xylon,layer-buffer-offset:
 160             $ref: /schemas/types.yaml#/definitions/uint32
 161             description: |
 162               Offset in number of lines (C_BUFFER_*_OFFSET) starting from the
 163               layer base offset for the second buffer used in double-buffering.
 164
 165           xylon,layer-primary:
 166             $ref: /schemas/types.yaml#/definitions/flag
 167             description: |
 168               Layer should be registered as a primary plane (exactly one is
 169               required).
 170
 171         additionalProperties: false
 172
 173         required:
 174           - reg
 175           - xylon,layer-depth
 176           - xylon,layer-colorspace
 177           - xylon,layer-alpha-mode
 178
 179     required:
 180       - "#address-cells"
 181       - "#size-cells"
 182       - layer@0
 183
 184     additionalProperties: false
 185
 186     description: |
 187       The description of the display controller layers, containing layer
 188       sub-nodes that each describe a registered layer.
 189
 190   port:
 191     $ref: /schemas/graph.yaml#/properties/port
 192     description: |
 193       Video output port, typically connected to a panel or bridge.
 194
 195 additionalProperties: false
 196
 197 required:
 198   - compatible
 199   - reg
 200   - clocks
 201   - clock-names
 202   - interrupts
 203   - xylon,display-interface
 204   - xylon,display-colorspace
 205   - xylon,display-depth
 206   - xylon,row-stride
 207   - layers
 208   - port
 209
 210 examples:
 211   - |
 212     #include <dt-bindings/interrupt-controller/irq.h>
 213
 214     logicvc: logicvc@43c00000 {
 215       compatible = "xylon,logicvc-3.02.a", "syscon", "simple-mfd";
 216       reg = <0x43c00000 0x6000>;
 217
 218       #address-cells = <1>;
 219       #size-cells = <1>;
 220
 221       logicvc_display: display@0 {
 222         compatible = "xylon,logicvc-3.02.a-display";
 223         reg = <0x0 0x6000>;
 224
 225         memory-region = <&logicvc_cma>;
 226
 227         clocks = <&logicvc_vclk 0>, <&logicvc_lvdsclk 0>;
 228         clock-names = "vclk", "lvdsclk";
 229
 230         interrupt-parent = <&intc>;
 231         interrupts = <0 34 IRQ_TYPE_LEVEL_HIGH>;
 232
 233         xylon,display-interface = "lvds-4bits";
 234         xylon,display-colorspace = "rgb";
 235         xylon,display-depth = <16>;
 236         xylon,row-stride = <1024>;
 237
 238         xylon,layers-configurable;
 239
 240         layers {
 241           #address-cells = <1>;
 242           #size-cells = <0>;
 243
 244           layer@0 {
 245             reg = <0>;
 246             xylon,layer-depth = <16>;
 247             xylon,layer-colorspace = "rgb";
 248             xylon,layer-alpha-mode = "layer";
 249             xylon,layer-base-offset = <0>;
 250             xylon,layer-buffer-offset = <480>;
 251             xylon,layer-primary;
 252           };
 253
 254           layer@1 {
 255             reg = <1>;
 256             xylon,layer-depth = <16>;
 257             xylon,layer-colorspace = "rgb";
 258             xylon,layer-alpha-mode = "layer";
 259             xylon,layer-base-offset = <2400>;
 260             xylon,layer-buffer-offset = <480>;
 261           };
 262
 263           layer@2 {
 264             reg = <2>;
 265             xylon,layer-depth = <16>;
 266             xylon,layer-colorspace = "rgb";
 267             xylon,layer-alpha-mode = "layer";
 268             xylon,layer-base-offset = <960>;
 269             xylon,layer-buffer-offset = <480>;
 270           };
 271
 272           layer@3 {
 273             reg = <3>;
 274             xylon,layer-depth = <16>;
 275             xylon,layer-colorspace = "rgb";
 276             xylon,layer-alpha-mode = "layer";
 277             xylon,layer-base-offset = <480>;
 278             xylon,layer-buffer-offset = <480>;
 279           };
 280
 281           layer@4 {
 282             reg = <4>;
 283             xylon,layer-depth = <16>;
 284             xylon,layer-colorspace = "rgb";
 285             xylon,layer-alpha-mode = "layer";
 286             xylon,layer-base-offset = <8192>;
 287             xylon,layer-buffer-offset = <480>;
 288           };
 289         };
 290
 291         port {
 292           #address-cells = <1>;
 293           #size-cells = <0>;
 294
 295           logicvc_output: endpoint@0 {
 296             reg = <0>;
 297             remote-endpoint = <&panel_input>;
 298           };
 299         };
 300       };
 301     };