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 318