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