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