Commit | Line | Data |
---|---|---|
4d1a7c12 TV |
1 | OMAP2/3 Display Subsystem |
2 | ------------------------- | |
3 | ||
4 | This is an almost total rewrite of the OMAP FB driver in drivers/video/omap | |
5 | (let's call it DSS1). The main differences between DSS1 and DSS2 are DSI, | |
6 | TV-out and multiple display support, but there are lots of small improvements | |
7 | also. | |
8 | ||
9 | The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB, | |
10 | panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live | |
11 | currently side by side, you can choose which one to use. | |
12 | ||
13 | Features | |
14 | -------- | |
15 | ||
16 | Working and tested features include: | |
17 | ||
18 | - MIPI DPI (parallel) output | |
19 | - MIPI DSI output in command mode | |
20 | - MIPI DBI (RFBI) output | |
21 | - SDI output | |
22 | - TV output | |
23 | - All pieces can be compiled as a module or inside kernel | |
24 | - Use DISPC to update any of the outputs | |
25 | - Use CPU to update RFBI or DSI output | |
26 | - OMAP DISPC planes | |
27 | - RGB16, RGB24 packed, RGB24 unpacked | |
28 | - YUV2, UYVY | |
29 | - Scaling | |
30 | - Adjusting DSS FCK to find a good pixel clock | |
31 | - Use DSI DPLL to create DSS FCK | |
32 | ||
33 | Tested boards include: | |
34 | - OMAP3 SDP board | |
35 | - Beagle board | |
36 | - N810 | |
37 | ||
38 | omapdss driver | |
39 | -------------- | |
40 | ||
41 | The DSS driver does not itself have any support for Linux framebuffer, V4L or | |
42 | such like the current ones, but it has an internal kernel API that upper level | |
43 | drivers can use. | |
44 | ||
45 | The DSS driver models OMAP's overlays, overlay managers and displays in a | |
46 | flexible way to enable non-common multi-display configuration. In addition to | |
47 | modelling the hardware overlays, omapdss supports virtual overlays and overlay | |
48 | managers. These can be used when updating a display with CPU or system DMA. | |
49 | ||
9c0b8420 RN |
50 | omapdss driver support for audio |
51 | -------------------------------- | |
52 | There exist several display technologies and standards that support audio as | |
53 | well. Hence, it is relevant to update the DSS device driver to provide an audio | |
54 | interface that may be used by an audio driver or any other driver interested in | |
55 | the functionality. | |
56 | ||
57 | The audio_enable function is intended to prepare the relevant | |
58 | IP for playback (e.g., enabling an audio FIFO, taking in/out of reset | |
59 | some IP, enabling companion chips, etc). It is intended to be called before | |
60 | audio_start. The audio_disable function performs the reverse operation and is | |
61 | intended to be called after audio_stop. | |
62 | ||
63 | While a given DSS device driver may support audio, it is possible that for | |
64 | certain configurations audio is not supported (e.g., an HDMI display using a | |
65 | VESA video timing). The audio_supported function is intended to query whether | |
66 | the current configuration of the display supports audio. | |
67 | ||
68 | The audio_config function is intended to configure all the relevant audio | |
69 | parameters of the display. In order to make the function independent of any | |
70 | specific DSS device driver, a struct omap_dss_audio is defined. Its purpose | |
71 | is to contain all the required parameters for audio configuration. At the | |
72 | moment, such structure contains pointers to IEC-60958 channel status word | |
73 | and CEA-861 audio infoframe structures. This should be enough to support | |
74 | HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958. | |
75 | ||
76 | The audio_enable/disable, audio_config and audio_supported functions could be | |
77 | implemented as functions that may sleep. Hence, they should not be called | |
78 | while holding a spinlock or a readlock. | |
79 | ||
80 | The audio_start/audio_stop function is intended to effectively start/stop audio | |
81 | playback after the configuration has taken place. These functions are designed | |
82 | to be used in an atomic context. Hence, audio_start should return quickly and be | |
83 | called only after all the needed resources for audio playback (audio FIFOs, | |
84 | DMA channels, companion chips, etc) have been enabled to begin data transfers. | |
85 | audio_stop is designed to only stop the audio transfers. The resources used | |
86 | for playback are released using audio_disable. | |
87 | ||
88 | The enum omap_dss_audio_state may be used to help the implementations of | |
89 | the interface to keep track of the audio state. The initial state is _DISABLED; | |
90 | then, the state transitions to _CONFIGURED, and then, when it is ready to | |
91 | play audio, to _ENABLED. The state _PLAYING is used when the audio is being | |
92 | rendered. | |
93 | ||
94 | ||
4d1a7c12 TV |
95 | Panel and controller drivers |
96 | ---------------------------- | |
97 | ||
98 | The drivers implement panel or controller specific functionality and are not | |
99 | usually visible to users except through omapfb driver. They register | |
100 | themselves to the DSS driver. | |
101 | ||
102 | omapfb driver | |
103 | ------------- | |
104 | ||
105 | The omapfb driver implements arbitrary number of standard linux framebuffers. | |
106 | These framebuffers can be routed flexibly to any overlays, thus allowing very | |
107 | dynamic display architecture. | |
108 | ||
109 | The driver exports some omapfb specific ioctls, which are compatible with the | |
110 | ioctls in the old driver. | |
111 | ||
112 | The rest of the non standard features are exported via sysfs. Whether the final | |
113 | implementation will use sysfs, or ioctls, is still open. | |
114 | ||
115 | V4L2 drivers | |
116 | ------------ | |
117 | ||
118 | V4L2 is being implemented in TI. | |
119 | ||
120 | From omapdss point of view the V4L2 drivers should be similar to framebuffer | |
121 | driver. | |
122 | ||
123 | Architecture | |
124 | -------------------- | |
125 | ||
126 | Some clarification what the different components do: | |
127 | ||
128 | - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the | |
129 | pixel data for the image. Framebuffer has width and height and color | |
130 | depth. | |
131 | - Overlay defines where the pixels are read from and where they go on the | |
132 | screen. The overlay may be smaller than framebuffer, thus displaying only | |
133 | part of the framebuffer. The position of the overlay may be changed if | |
134 | the overlay is smaller than the display. | |
135 | - Overlay manager combines the overlays in to one image and feeds them to | |
136 | display. | |
137 | - Display is the actual physical display device. | |
138 | ||
139 | A framebuffer can be connected to multiple overlays to show the same pixel data | |
140 | on all of the overlays. Note that in this case the overlay input sizes must be | |
141 | the same, but, in case of video overlays, the output size can be different. Any | |
142 | framebuffer can be connected to any overlay. | |
143 | ||
144 | An overlay can be connected to one overlay manager. Also DISPC overlays can be | |
145 | connected only to DISPC overlay managers, and virtual overlays can be only | |
146 | connected to virtual overlays. | |
147 | ||
148 | An overlay manager can be connected to one display. There are certain | |
149 | restrictions which kinds of displays an overlay manager can be connected: | |
150 | ||
151 | - DISPC TV overlay manager can be only connected to TV display. | |
152 | - Virtual overlay managers can only be connected to DBI or DSI displays. | |
153 | - DISPC LCD overlay manager can be connected to all displays, except TV | |
154 | display. | |
155 | ||
156 | Sysfs | |
157 | ----- | |
158 | The sysfs interface is mainly used for testing. I don't think sysfs | |
159 | interface is the best for this in the final version, but I don't quite know | |
160 | what would be the best interfaces for these things. | |
161 | ||
162 | The sysfs interface is divided to two parts: DSS and FB. | |
163 | ||
164 | /sys/class/graphics/fb? directory: | |
165 | mirror 0=off, 1=on | |
166 | rotate Rotation 0-3 for 0, 90, 180, 270 degrees | |
167 | rotate_type 0 = DMA rotation, 1 = VRFB rotation | |
168 | overlays List of overlay numbers to which framebuffer pixels go | |
169 | phys_addr Physical address of the framebuffer | |
170 | virt_addr Virtual address of the framebuffer | |
171 | size Size of the framebuffer | |
172 | ||
173 | /sys/devices/platform/omapdss/overlay? directory: | |
174 | enabled 0=off, 1=on | |
175 | input_size width,height (ie. the framebuffer size) | |
176 | manager Destination overlay manager name | |
177 | name | |
178 | output_size width,height | |
179 | position x,y | |
180 | screen_width width | |
181 | global_alpha global alpha 0-255 0=transparent 255=opaque | |
182 | ||
183 | /sys/devices/platform/omapdss/manager? directory: | |
184 | display Destination display | |
185 | name | |
186 | alpha_blending_enabled 0=off, 1=on | |
187 | trans_key_enabled 0=off, 1=on | |
188 | trans_key_type gfx-destination, video-source | |
189 | trans_key_value transparency color key (RGB24) | |
190 | default_color default background color (RGB24) | |
191 | ||
192 | /sys/devices/platform/omapdss/display? directory: | |
193 | ctrl_name Controller name | |
194 | mirror 0=off, 1=on | |
195 | update_mode 0=off, 1=auto, 2=manual | |
196 | enabled 0=off, 1=on | |
197 | name | |
198 | rotate Rotation 0-3 for 0, 90, 180, 270 degrees | |
199 | timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw) | |
200 | When writing, two special timings are accepted for tv-out: | |
201 | "pal" and "ntsc" | |
202 | panel_name | |
203 | tear_elim Tearing elimination 0=off, 1=on | |
0aca3c63 | 204 | output_type Output type (video encoder only): "composite" or "svideo" |
4d1a7c12 TV |
205 | |
206 | There are also some debugfs files at <debugfs>/omapdss/ which show information | |
207 | about clocks and registers. | |
208 | ||
209 | Examples | |
210 | -------- | |
211 | ||
212 | The following definitions have been made for the examples below: | |
213 | ||
214 | ovl0=/sys/devices/platform/omapdss/overlay0 | |
215 | ovl1=/sys/devices/platform/omapdss/overlay1 | |
216 | ovl2=/sys/devices/platform/omapdss/overlay2 | |
217 | ||
218 | mgr0=/sys/devices/platform/omapdss/manager0 | |
219 | mgr1=/sys/devices/platform/omapdss/manager1 | |
220 | ||
221 | lcd=/sys/devices/platform/omapdss/display0 | |
222 | dvi=/sys/devices/platform/omapdss/display1 | |
223 | tv=/sys/devices/platform/omapdss/display2 | |
224 | ||
225 | fb0=/sys/class/graphics/fb0 | |
226 | fb1=/sys/class/graphics/fb1 | |
227 | fb2=/sys/class/graphics/fb2 | |
228 | ||
229 | Default setup on OMAP3 SDP | |
230 | -------------------------- | |
231 | ||
232 | Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI | |
233 | and TV-out are not in use. The columns from left to right are: | |
234 | framebuffers, overlays, overlay managers, displays. Framebuffers are | |
235 | handled by omapfb, and the rest by the DSS. | |
236 | ||
237 | FB0 --- GFX -\ DVI | |
238 | FB1 --- VID1 --+- LCD ---- LCD | |
239 | FB2 --- VID2 -/ TV ----- TV | |
240 | ||
241 | Example: Switch from LCD to DVI | |
242 | ---------------------- | |
243 | ||
244 | w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1` | |
245 | h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1` | |
246 | ||
247 | echo "0" > $lcd/enabled | |
248 | echo "" > $mgr0/display | |
249 | fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h | |
250 | # at this point you have to switch the dvi/lcd dip-switch from the omap board | |
251 | echo "dvi" > $mgr0/display | |
252 | echo "1" > $dvi/enabled | |
253 | ||
254 | After this the configuration looks like: | |
255 | ||
256 | FB0 --- GFX -\ -- DVI | |
257 | FB1 --- VID1 --+- LCD -/ LCD | |
258 | FB2 --- VID2 -/ TV ----- TV | |
259 | ||
260 | Example: Clone GFX overlay to LCD and TV | |
261 | ------------------------------- | |
262 | ||
263 | w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1` | |
264 | h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1` | |
265 | ||
266 | echo "0" > $ovl0/enabled | |
267 | echo "0" > $ovl1/enabled | |
268 | ||
269 | echo "" > $fb1/overlays | |
270 | echo "0,1" > $fb0/overlays | |
271 | ||
272 | echo "$w,$h" > $ovl1/output_size | |
273 | echo "tv" > $ovl1/manager | |
274 | ||
275 | echo "1" > $ovl0/enabled | |
276 | echo "1" > $ovl1/enabled | |
277 | ||
278 | echo "1" > $tv/enabled | |
279 | ||
280 | After this the configuration looks like (only relevant parts shown): | |
281 | ||
282 | FB0 +-- GFX ---- LCD ---- LCD | |
283 | \- VID1 ---- TV ---- TV | |
284 | ||
285 | Misc notes | |
286 | ---------- | |
287 | ||
0049fb26 TV |
288 | OMAP FB allocates the framebuffer memory using the standard dma allocator. You |
289 | can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma | |
290 | allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase | |
291 | the global memory area for CMA. | |
4d1a7c12 TV |
292 | |
293 | Using DSI DPLL to generate pixel clock it is possible produce the pixel clock | |
294 | of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI. | |
295 | ||
296 | Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB | |
297 | does not support mirroring. | |
298 | ||
299 | VRFB rotation requires much more memory than non-rotated framebuffer, so you | |
300 | probably need to increase your vram setting before using VRFB rotation. Also, | |
301 | many applications may not work with VRFB if they do not pay attention to all | |
302 | framebuffer parameters. | |
303 | ||
304 | Kernel boot arguments | |
305 | --------------------- | |
306 | ||
4d1a7c12 TV |
307 | omapfb.mode=<display>:<mode>[,...] |
308 | - Default video mode for specified displays. For example, | |
309 | "dvi:800x400MR-24@60". See drivers/video/modedb.c. | |
310 | There are also two special modes: "pal" and "ntsc" that | |
311 | can be used to tv out. | |
312 | ||
313 | omapfb.vram=<fbnum>:<size>[@<physaddr>][,...] | |
314 | - VRAM allocated for a framebuffer. Normally omapfb allocates vram | |
315 | depending on the display size. With this you can manually allocate | |
316 | more or define the physical address of each framebuffer. For example, | |
317 | "1:4M" to allocate 4M for fb1. | |
318 | ||
319 | omapfb.debug=<y|n> | |
320 | - Enable debug printing. You have to have OMAPFB debug support enabled | |
321 | in kernel config. | |
322 | ||
323 | omapfb.test=<y|n> | |
324 | - Draw test pattern to framebuffer whenever framebuffer settings change. | |
325 | You need to have OMAPFB debug support enabled in kernel config. | |
326 | ||
327 | omapfb.vrfb=<y|n> | |
328 | - Use VRFB rotation for all framebuffers. | |
329 | ||
330 | omapfb.rotate=<angle> | |
331 | - Default rotation applied to all framebuffers. | |
332 | 0 - 0 degree rotation | |
333 | 1 - 90 degree rotation | |
334 | 2 - 180 degree rotation | |
335 | 3 - 270 degree rotation | |
336 | ||
337 | omapfb.mirror=<y|n> | |
338 | - Default mirror for all framebuffers. Only works with DMA rotation. | |
339 | ||
340 | omapdss.def_disp=<display> | |
341 | - Name of default display, to which all overlays will be connected. | |
342 | Common examples are "lcd" or "tv". | |
343 | ||
344 | omapdss.debug=<y|n> | |
345 | - Enable debug printing. You have to have DSS debug support enabled in | |
346 | kernel config. | |
347 | ||
348 | TODO | |
349 | ---- | |
350 | ||
351 | DSS locking | |
352 | ||
353 | Error checking | |
354 | - Lots of checks are missing or implemented just as BUG() | |
355 | ||
356 | System DMA update for DSI | |
357 | - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how | |
358 | to skip the empty byte?) | |
359 | ||
360 | OMAP1 support | |
361 | - Not sure if needed | |
362 |