common: DMA-mapping: add DMA_ATTR_NO_KERNEL_MAPPING attribute
[pandora-kernel.git] / Documentation / arm / OMAP / DSS
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
50 Panel and controller drivers
51 ----------------------------
52
53 The drivers implement panel or controller specific functionality and are not
54 usually visible to users except through omapfb driver.  They register
55 themselves to the DSS driver.
56
57 omapfb driver
58 -------------
59
60 The omapfb driver implements arbitrary number of standard linux framebuffers.
61 These framebuffers can be routed flexibly to any overlays, thus allowing very
62 dynamic display architecture.
63
64 The driver exports some omapfb specific ioctls, which are compatible with the
65 ioctls in the old driver.
66
67 The rest of the non standard features are exported via sysfs. Whether the final
68 implementation will use sysfs, or ioctls, is still open.
69
70 V4L2 drivers
71 ------------
72
73 V4L2 is being implemented in TI.
74
75 From omapdss point of view the V4L2 drivers should be similar to framebuffer
76 driver.
77
78 Architecture
79 --------------------
80
81 Some clarification what the different components do:
82
83     - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the
84       pixel data for the image. Framebuffer has width and height and color
85       depth.
86     - Overlay defines where the pixels are read from and where they go on the
87       screen. The overlay may be smaller than framebuffer, thus displaying only
88       part of the framebuffer. The position of the overlay may be changed if
89       the overlay is smaller than the display.
90     - Overlay manager combines the overlays in to one image and feeds them to
91       display.
92     - Display is the actual physical display device.
93
94 A framebuffer can be connected to multiple overlays to show the same pixel data
95 on all of the overlays. Note that in this case the overlay input sizes must be
96 the same, but, in case of video overlays, the output size can be different. Any
97 framebuffer can be connected to any overlay.
98
99 An overlay can be connected to one overlay manager. Also DISPC overlays can be
100 connected only to DISPC overlay managers, and virtual overlays can be only
101 connected to virtual overlays.
102
103 An overlay manager can be connected to one display. There are certain
104 restrictions which kinds of displays an overlay manager can be connected:
105
106     - DISPC TV overlay manager can be only connected to TV display.
107     - Virtual overlay managers can only be connected to DBI or DSI displays.
108     - DISPC LCD overlay manager can be connected to all displays, except TV
109       display.
110
111 Sysfs
112 -----
113 The sysfs interface is mainly used for testing. I don't think sysfs
114 interface is the best for this in the final version, but I don't quite know
115 what would be the best interfaces for these things.
116
117 The sysfs interface is divided to two parts: DSS and FB.
118
119 /sys/class/graphics/fb? directory:
120 mirror          0=off, 1=on
121 rotate          Rotation 0-3 for 0, 90, 180, 270 degrees
122 rotate_type     0 = DMA rotation, 1 = VRFB rotation
123 overlays        List of overlay numbers to which framebuffer pixels go
124 phys_addr       Physical address of the framebuffer
125 virt_addr       Virtual address of the framebuffer
126 size            Size of the framebuffer
127
128 /sys/devices/platform/omapdss/overlay? directory:
129 enabled         0=off, 1=on
130 input_size      width,height (ie. the framebuffer size)
131 manager         Destination overlay manager name
132 name
133 output_size     width,height
134 position        x,y
135 screen_width    width
136 global_alpha    global alpha 0-255 0=transparent 255=opaque
137
138 /sys/devices/platform/omapdss/manager? directory:
139 display                         Destination display
140 name
141 alpha_blending_enabled          0=off, 1=on
142 trans_key_enabled               0=off, 1=on
143 trans_key_type                  gfx-destination, video-source
144 trans_key_value                 transparency color key (RGB24)
145 default_color                   default background color (RGB24)
146
147 /sys/devices/platform/omapdss/display? directory:
148 ctrl_name       Controller name
149 mirror          0=off, 1=on
150 update_mode     0=off, 1=auto, 2=manual
151 enabled         0=off, 1=on
152 name
153 rotate          Rotation 0-3 for 0, 90, 180, 270 degrees
154 timings         Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw)
155                 When writing, two special timings are accepted for tv-out:
156                 "pal" and "ntsc"
157 panel_name
158 tear_elim       Tearing elimination 0=off, 1=on
159 venc_type       Output type (video encoder only): "composite" or "svideo"
160
161 There are also some debugfs files at <debugfs>/omapdss/ which show information
162 about clocks and registers.
163
164 Examples
165 --------
166
167 The following definitions have been made for the examples below:
168
169 ovl0=/sys/devices/platform/omapdss/overlay0
170 ovl1=/sys/devices/platform/omapdss/overlay1
171 ovl2=/sys/devices/platform/omapdss/overlay2
172
173 mgr0=/sys/devices/platform/omapdss/manager0
174 mgr1=/sys/devices/platform/omapdss/manager1
175
176 lcd=/sys/devices/platform/omapdss/display0
177 dvi=/sys/devices/platform/omapdss/display1
178 tv=/sys/devices/platform/omapdss/display2
179
180 fb0=/sys/class/graphics/fb0
181 fb1=/sys/class/graphics/fb1
182 fb2=/sys/class/graphics/fb2
183
184 Default setup on OMAP3 SDP
185 --------------------------
186
187 Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI
188 and TV-out are not in use. The columns from left to right are:
189 framebuffers, overlays, overlay managers, displays. Framebuffers are
190 handled by omapfb, and the rest by the DSS.
191
192 FB0 --- GFX  -\            DVI
193 FB1 --- VID1 --+- LCD ---- LCD
194 FB2 --- VID2 -/   TV ----- TV
195
196 Example: Switch from LCD to DVI
197 ----------------------
198
199 w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
200 h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
201
202 echo "0" > $lcd/enabled
203 echo "" > $mgr0/display
204 fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
205 # at this point you have to switch the dvi/lcd dip-switch from the omap board
206 echo "dvi" > $mgr0/display
207 echo "1" > $dvi/enabled
208
209 After this the configuration looks like:
210
211 FB0 --- GFX  -\         -- DVI
212 FB1 --- VID1 --+- LCD -/   LCD
213 FB2 --- VID2 -/   TV ----- TV
214
215 Example: Clone GFX overlay to LCD and TV
216 -------------------------------
217
218 w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
219 h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
220
221 echo "0" > $ovl0/enabled
222 echo "0" > $ovl1/enabled
223
224 echo "" > $fb1/overlays
225 echo "0,1" > $fb0/overlays
226
227 echo "$w,$h" > $ovl1/output_size
228 echo "tv" > $ovl1/manager
229
230 echo "1" > $ovl0/enabled
231 echo "1" > $ovl1/enabled
232
233 echo "1" > $tv/enabled
234
235 After this the configuration looks like (only relevant parts shown):
236
237 FB0 +-- GFX  ---- LCD ---- LCD
238      \- VID1 ---- TV  ---- TV
239
240 Misc notes
241 ----------
242
243 OMAP FB allocates the framebuffer memory using the OMAP VRAM allocator.
244
245 Using DSI DPLL to generate pixel clock it is possible produce the pixel clock
246 of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI.
247
248 Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB
249 does not support mirroring.
250
251 VRFB rotation requires much more memory than non-rotated framebuffer, so you
252 probably need to increase your vram setting before using VRFB rotation. Also,
253 many applications may not work with VRFB if they do not pay attention to all
254 framebuffer parameters.
255
256 Kernel boot arguments
257 ---------------------
258
259 vram=<size>[,<physaddr>]
260         - Amount of total VRAM to preallocate and optionally a physical start
261           memory address. For example, "10M". omapfb allocates memory for
262           framebuffers from VRAM.
263
264 omapfb.mode=<display>:<mode>[,...]
265         - Default video mode for specified displays. For example,
266           "dvi:800x400MR-24@60".  See drivers/video/modedb.c.
267           There are also two special modes: "pal" and "ntsc" that
268           can be used to tv out.
269
270 omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]
271         - VRAM allocated for a framebuffer. Normally omapfb allocates vram
272           depending on the display size. With this you can manually allocate
273           more or define the physical address of each framebuffer. For example,
274           "1:4M" to allocate 4M for fb1.
275
276 omapfb.debug=<y|n>
277         - Enable debug printing. You have to have OMAPFB debug support enabled
278           in kernel config.
279
280 omapfb.test=<y|n>
281         - Draw test pattern to framebuffer whenever framebuffer settings change.
282           You need to have OMAPFB debug support enabled in kernel config.
283
284 omapfb.vrfb=<y|n>
285         - Use VRFB rotation for all framebuffers.
286
287 omapfb.rotate=<angle>
288         - Default rotation applied to all framebuffers.
289           0 - 0 degree rotation
290           1 - 90 degree rotation
291           2 - 180 degree rotation
292           3 - 270 degree rotation
293
294 omapfb.mirror=<y|n>
295         - Default mirror for all framebuffers. Only works with DMA rotation.
296
297 omapfb.vram_cache=<y|n>
298         - Sets the framebuffer memory to be write-through cached. This may be
299           useful in the configurations where only CPU is allowed to write to
300           the framebuffer and eliminate the need for enabling shadow
301           framebuffer in Xorg DDX drivers such as xf86-video-fbdev and
302           xf86-video-omapfb. Enabling write-through cache is only useful
303           for ARM11 and Cortex-A8 processors. Cortex-A9 does not support
304           write-through cache well, see "Cortex-A9 behavior for Normal Memory
305           Cacheable memory regions" section in Cortex-A9 TRM for more details.
306
307 omapdss.def_disp=<display>
308         - Name of default display, to which all overlays will be connected.
309           Common examples are "lcd" or "tv".
310
311 omapdss.debug=<y|n>
312         - Enable debug printing. You have to have DSS debug support enabled in
313           kernel config.
314
315 TODO
316 ----
317
318 DSS locking
319
320 Error checking
321 - Lots of checks are missing or implemented just as BUG()
322
323 System DMA update for DSI
324 - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
325   to skip the empty byte?)
326
327 OMAP1 support
328 - Not sure if needed
329