Documentation/arm/omap/dss.rst

   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