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