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