Documentation/arm/OMAP/DSS

   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
 362