373 lines · plain
1=========================2OMAP2/3 Display Subsystem3=========================4 5This is an almost total rewrite of the OMAP FB driver in drivers/video/omap6(let's call it DSS1). The main differences between DSS1 and DSS2 are DSI,7TV-out and multiple display support, but there are lots of small improvements8also.9 10The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB,11panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live12currently side by side, you can choose which one to use.13 14Features15--------16 17Working and tested features include:18 19- MIPI DPI (parallel) output20- MIPI DSI output in command mode21- MIPI DBI (RFBI) output22- SDI output23- TV output24- All pieces can be compiled as a module or inside kernel25- Use DISPC to update any of the outputs26- Use CPU to update RFBI or DSI output27- OMAP DISPC planes28- RGB16, RGB24 packed, RGB24 unpacked29- YUV2, UYVY30- Scaling31- Adjusting DSS FCK to find a good pixel clock32- Use DSI DPLL to create DSS FCK33 34Tested boards include:35- OMAP3 SDP board36- Beagle board37- N81038 39omapdss driver40--------------41 42The DSS driver does not itself have any support for Linux framebuffer, V4L or43such like the current ones, but it has an internal kernel API that upper level44drivers can use.45 46The DSS driver models OMAP's overlays, overlay managers and displays in a47flexible way to enable non-common multi-display configuration. In addition to48modelling the hardware overlays, omapdss supports virtual overlays and overlay49managers. These can be used when updating a display with CPU or system DMA.50 51omapdss driver support for audio52--------------------------------53There exist several display technologies and standards that support audio as54well. Hence, it is relevant to update the DSS device driver to provide an audio55interface that may be used by an audio driver or any other driver interested in56the functionality.57 58The audio_enable function is intended to prepare the relevant59IP for playback (e.g., enabling an audio FIFO, taking in/out of reset60some IP, enabling companion chips, etc). It is intended to be called before61audio_start. The audio_disable function performs the reverse operation and is62intended to be called after audio_stop.63 64While a given DSS device driver may support audio, it is possible that for65certain configurations audio is not supported (e.g., an HDMI display using a66VESA video timing). The audio_supported function is intended to query whether67the current configuration of the display supports audio.68 69The audio_config function is intended to configure all the relevant audio70parameters of the display. In order to make the function independent of any71specific DSS device driver, a struct omap_dss_audio is defined. Its purpose72is to contain all the required parameters for audio configuration. At the73moment, such structure contains pointers to IEC-60958 channel status word74and CEA-861 audio infoframe structures. This should be enough to support75HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958.76 77The audio_enable/disable, audio_config and audio_supported functions could be78implemented as functions that may sleep. Hence, they should not be called79while holding a spinlock or a readlock.80 81The audio_start/audio_stop function is intended to effectively start/stop audio82playback after the configuration has taken place. These functions are designed83to be used in an atomic context. Hence, audio_start should return quickly and be84called only after all the needed resources for audio playback (audio FIFOs,85DMA channels, companion chips, etc) have been enabled to begin data transfers.86audio_stop is designed to only stop the audio transfers. The resources used87for playback are released using audio_disable.88 89The enum omap_dss_audio_state may be used to help the implementations of90the interface to keep track of the audio state. The initial state is _DISABLED;91then, the state transitions to _CONFIGURED, and then, when it is ready to92play audio, to _ENABLED. The state _PLAYING is used when the audio is being93rendered.94 95 96Panel and controller drivers97----------------------------98 99The drivers implement panel or controller specific functionality and are not100usually visible to users except through omapfb driver. They register101themselves to the DSS driver.102 103omapfb driver104-------------105 106The omapfb driver implements arbitrary number of standard linux framebuffers.107These framebuffers can be routed flexibly to any overlays, thus allowing very108dynamic display architecture.109 110The driver exports some omapfb specific ioctls, which are compatible with the111ioctls in the old driver.112 113The rest of the non standard features are exported via sysfs. Whether the final114implementation will use sysfs, or ioctls, is still open.115 116V4L2 drivers117------------118 119V4L2 is being implemented in TI.120 121From omapdss point of view the V4L2 drivers should be similar to framebuffer122driver.123 124Architecture125--------------------126 127Some clarification what the different components do:128 129 - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the130 pixel data for the image. Framebuffer has width and height and color131 depth.132 - Overlay defines where the pixels are read from and where they go on the133 screen. The overlay may be smaller than framebuffer, thus displaying only134 part of the framebuffer. The position of the overlay may be changed if135 the overlay is smaller than the display.136 - Overlay manager combines the overlays in to one image and feeds them to137 display.138 - Display is the actual physical display device.139 140A framebuffer can be connected to multiple overlays to show the same pixel data141on all of the overlays. Note that in this case the overlay input sizes must be142the same, but, in case of video overlays, the output size can be different. Any143framebuffer can be connected to any overlay.144 145An overlay can be connected to one overlay manager. Also DISPC overlays can be146connected only to DISPC overlay managers, and virtual overlays can be only147connected to virtual overlays.148 149An overlay manager can be connected to one display. There are certain150restrictions 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 TV155 display.156 157Sysfs158-----159The sysfs interface is mainly used for testing. I don't think sysfs160interface is the best for this in the final version, but I don't quite know161what would be the best interfaces for these things.162 163The sysfs interface is divided to two parts: DSS and FB.164 165/sys/class/graphics/fb? directory:166mirror 0=off, 1=on167rotate Rotation 0-3 for 0, 90, 180, 270 degrees168rotate_type 0 = DMA rotation, 1 = VRFB rotation169overlays List of overlay numbers to which framebuffer pixels go170phys_addr Physical address of the framebuffer171virt_addr Virtual address of the framebuffer172size Size of the framebuffer173 174/sys/devices/platform/omapdss/overlay? directory:175enabled 0=off, 1=on176input_size width,height (ie. the framebuffer size)177manager Destination overlay manager name178name179output_size width,height180position x,y181screen_width width182global_alpha global alpha 0-255 0=transparent 255=opaque183 184/sys/devices/platform/omapdss/manager? directory:185display Destination display186name187alpha_blending_enabled 0=off, 1=on188trans_key_enabled 0=off, 1=on189trans_key_type gfx-destination, video-source190trans_key_value transparency color key (RGB24)191default_color default background color (RGB24)192 193/sys/devices/platform/omapdss/display? directory:194 195=============== =============================================================196ctrl_name Controller name197mirror 0=off, 1=on198update_mode 0=off, 1=auto, 2=manual199enabled 0=off, 1=on200name201rotate Rotation 0-3 for 0, 90, 180, 270 degrees202timings 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"205panel_name206tear_elim Tearing elimination 0=off, 1=on207output_type Output type (video encoder only): "composite" or "svideo"208=============== =============================================================209 210There are also some debugfs files at <debugfs>/omapdss/ which show information211about clocks and registers.212 213Examples214--------215 216The following definitions have been made for the examples below::217 218 ovl0=/sys/devices/platform/omapdss/overlay0219 ovl1=/sys/devices/platform/omapdss/overlay1220 ovl2=/sys/devices/platform/omapdss/overlay2221 222 mgr0=/sys/devices/platform/omapdss/manager0223 mgr1=/sys/devices/platform/omapdss/manager1224 225 lcd=/sys/devices/platform/omapdss/display0226 dvi=/sys/devices/platform/omapdss/display1227 tv=/sys/devices/platform/omapdss/display2228 229 fb0=/sys/class/graphics/fb0230 fb1=/sys/class/graphics/fb1231 fb2=/sys/class/graphics/fb2232 233Default setup on OMAP3 SDP234--------------------------235 236Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI237and TV-out are not in use. The columns from left to right are:238framebuffers, overlays, overlay managers, displays. Framebuffers are239handled by omapfb, and the rest by the DSS::240 241 FB0 --- GFX -\ DVI242 FB1 --- VID1 --+- LCD ---- LCD243 FB2 --- VID2 -/ TV ----- TV244 245Example: Switch from LCD to DVI246-------------------------------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/enabled254 echo "" > $mgr0/display255 fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h256 # at this point you have to switch the dvi/lcd dip-switch from the omap board257 echo "dvi" > $mgr0/display258 echo "1" > $dvi/enabled259 260After this the configuration looks like:::261 262 FB0 --- GFX -\ -- DVI263 FB1 --- VID1 --+- LCD -/ LCD264 FB2 --- VID2 -/ TV ----- TV265 266Example: Clone GFX overlay to LCD and TV267----------------------------------------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/enabled275 echo "0" > $ovl1/enabled276 277 echo "" > $fb1/overlays278 echo "0,1" > $fb0/overlays279 280 echo "$w,$h" > $ovl1/output_size281 echo "tv" > $ovl1/manager282 283 echo "1" > $ovl0/enabled284 echo "1" > $ovl1/enabled285 286 echo "1" > $tv/enabled287 288After this the configuration looks like (only relevant parts shown)::289 290 FB0 +-- GFX ---- LCD ---- LCD291 \- VID1 ---- TV ---- TV292 293Misc notes294----------295 296OMAP FB allocates the framebuffer memory using the standard dma allocator. You297can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma298allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase299the global memory area for CMA.300 301Using DSI DPLL to generate pixel clock it is possible produce the pixel clock302of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI.303 304Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB305does not support mirroring.306 307VRFB rotation requires much more memory than non-rotated framebuffer, so you308probably need to increase your vram setting before using VRFB rotation. Also,309many applications may not work with VRFB if they do not pay attention to all310framebuffer parameters.311 312Kernel boot arguments313---------------------314 315omapfb.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" that319 can be used to tv out.320 321omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]322 - VRAM allocated for a framebuffer. Normally omapfb allocates vram323 depending on the display size. With this you can manually allocate324 more or define the physical address of each framebuffer. For example,325 "1:4M" to allocate 4M for fb1.326 327omapfb.debug=<y|n>328 - Enable debug printing. You have to have OMAPFB debug support enabled329 in kernel config.330 331omapfb.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 335omapfb.vrfb=<y|n>336 - Use VRFB rotation for all framebuffers.337 338omapfb.rotate=<angle>339 - Default rotation applied to all framebuffers.340 0 - 0 degree rotation341 1 - 90 degree rotation342 2 - 180 degree rotation343 3 - 270 degree rotation344 345omapfb.mirror=<y|n>346 - Default mirror for all framebuffers. Only works with DMA rotation.347 348omapdss.def_disp=<display>349 - Name of default display, to which all overlays will be connected.350 Common examples are "lcd" or "tv".351 352omapdss.debug=<y|n>353 - Enable debug printing. You have to have DSS debug support enabled in354 kernel config.355 356TODO357----358 359DSS locking360 361Error checking362 363- Lots of checks are missing or implemented just as BUG()364 365System DMA update for DSI366 367- Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how368 to skip the empty byte?)369 370OMAP1 support371 372- Not sure if needed373