Tomi Valkeinen | 4d1a7c1 | 2009-08-04 15:47:11 +0300 | [diff] [blame] | 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 | |
Ricardo Neri | 9c0b842 | 2012-03-06 18:20:37 -0600 | [diff] [blame] | 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 | |
Tomi Valkeinen | 4d1a7c1 | 2009-08-04 15:47:11 +0300 | [diff] [blame] | 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 |
Grazvydas Ignotas | 0aca3c6 | 2012-04-24 00:08:54 +0300 | [diff] [blame] | 204 | output_type Output type (video encoder only): "composite" or "svideo" |
Tomi Valkeinen | 4d1a7c1 | 2009-08-04 15:47:11 +0300 | [diff] [blame] | 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 | |
Tomi Valkeinen | 0049fb2 | 2012-11-09 15:52:20 +0200 | [diff] [blame] | 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. |
Tomi Valkeinen | 4d1a7c1 | 2009-08-04 15:47:11 +0300 | [diff] [blame] | 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 | |
Tomi Valkeinen | 4d1a7c1 | 2009-08-04 15:47:11 +0300 | [diff] [blame] | 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 | |