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