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