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
8title: Xylon LogiCVC display controller
9
10maintainers:
11  - Paul Kocialkowski <paul.kocialkowski@bootlin.com>
12
13description: |
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
29properties:
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
195additionalProperties: false
196
197required:
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
210examples:
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    };
302