0001 =========================
0002 OMAP2/3 Display Subsystem
0003 =========================
0004
0005 This is an almost total rewrite of the OMAP FB driver in drivers/video/omap
0006 (let's call it DSS1). The main differences between DSS1 and DSS2 are DSI,
0007 TV-out and multiple display support, but there are lots of small improvements
0008 also.
0009
0010 The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB,
0011 panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live
0012 currently side by side, you can choose which one to use.
0013
0014 Features
0015 --------
0016
0017 Working and tested features include:
0018
0019 - MIPI DPI (parallel) output
0020 - MIPI DSI output in command mode
0021 - MIPI DBI (RFBI) output
0022 - SDI output
0023 - TV output
0024 - All pieces can be compiled as a module or inside kernel
0025 - Use DISPC to update any of the outputs
0026 - Use CPU to update RFBI or DSI output
0027 - OMAP DISPC planes
0028 - RGB16, RGB24 packed, RGB24 unpacked
0029 - YUV2, UYVY
0030 - Scaling
0031 - Adjusting DSS FCK to find a good pixel clock
0032 - Use DSI DPLL to create DSS FCK
0033
0034 Tested boards include:
0035 - OMAP3 SDP board
0036 - Beagle board
0037 - N810
0038
0039 omapdss driver
0040 --------------
0041
0042 The DSS driver does not itself have any support for Linux framebuffer, V4L or
0043 such like the current ones, but it has an internal kernel API that upper level
0044 drivers can use.
0045
0046 The DSS driver models OMAP's overlays, overlay managers and displays in a
0047 flexible way to enable non-common multi-display configuration. In addition to
0048 modelling the hardware overlays, omapdss supports virtual overlays and overlay
0049 managers. These can be used when updating a display with CPU or system DMA.
0050
0051 omapdss driver support for audio
0052 --------------------------------
0053 There exist several display technologies and standards that support audio as
0054 well. Hence, it is relevant to update the DSS device driver to provide an audio
0055 interface that may be used by an audio driver or any other driver interested in
0056 the functionality.
0057
0058 The audio_enable function is intended to prepare the relevant
0059 IP for playback (e.g., enabling an audio FIFO, taking in/out of reset
0060 some IP, enabling companion chips, etc). It is intended to be called before
0061 audio_start. The audio_disable function performs the reverse operation and is
0062 intended to be called after audio_stop.
0063
0064 While a given DSS device driver may support audio, it is possible that for
0065 certain configurations audio is not supported (e.g., an HDMI display using a
0066 VESA video timing). The audio_supported function is intended to query whether
0067 the current configuration of the display supports audio.
0068
0069 The audio_config function is intended to configure all the relevant audio
0070 parameters of the display. In order to make the function independent of any
0071 specific DSS device driver, a struct omap_dss_audio is defined. Its purpose
0072 is to contain all the required parameters for audio configuration. At the
0073 moment, such structure contains pointers to IEC-60958 channel status word
0074 and CEA-861 audio infoframe structures. This should be enough to support
0075 HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958.
0076
0077 The audio_enable/disable, audio_config and audio_supported functions could be
0078 implemented as functions that may sleep. Hence, they should not be called
0079 while holding a spinlock or a readlock.
0080
0081 The audio_start/audio_stop function is intended to effectively start/stop audio
0082 playback after the configuration has taken place. These functions are designed
0083 to be used in an atomic context. Hence, audio_start should return quickly and be
0084 called only after all the needed resources for audio playback (audio FIFOs,
0085 DMA channels, companion chips, etc) have been enabled to begin data transfers.
0086 audio_stop is designed to only stop the audio transfers. The resources used
0087 for playback are released using audio_disable.
0088
0089 The enum omap_dss_audio_state may be used to help the implementations of
0090 the interface to keep track of the audio state. The initial state is _DISABLED;
0091 then, the state transitions to _CONFIGURED, and then, when it is ready to
0092 play audio, to _ENABLED. The state _PLAYING is used when the audio is being
0093 rendered.
0094
0095
0096 Panel and controller drivers
0097 ----------------------------
0098
0099 The drivers implement panel or controller specific functionality and are not
0100 usually visible to users except through omapfb driver. They register
0101 themselves to the DSS driver.
0102
0103 omapfb driver
0104 -------------
0105
0106 The omapfb driver implements arbitrary number of standard linux framebuffers.
0107 These framebuffers can be routed flexibly to any overlays, thus allowing very
0108 dynamic display architecture.
0109
0110 The driver exports some omapfb specific ioctls, which are compatible with the
0111 ioctls in the old driver.
0112
0113 The rest of the non standard features are exported via sysfs. Whether the final
0114 implementation will use sysfs, or ioctls, is still open.
0115
0116 V4L2 drivers
0117 ------------
0118
0119 V4L2 is being implemented in TI.
0120
0121 From omapdss point of view the V4L2 drivers should be similar to framebuffer
0122 driver.
0123
0124 Architecture
0125 --------------------
0126
0127 Some clarification what the different components do:
0128
0129 - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the
0130 pixel data for the image. Framebuffer has width and height and color
0131 depth.
0132 - Overlay defines where the pixels are read from and where they go on the
0133 screen. The overlay may be smaller than framebuffer, thus displaying only
0134 part of the framebuffer. The position of the overlay may be changed if
0135 the overlay is smaller than the display.
0136 - Overlay manager combines the overlays in to one image and feeds them to
0137 display.
0138 - Display is the actual physical display device.
0139
0140 A framebuffer can be connected to multiple overlays to show the same pixel data
0141 on all of the overlays. Note that in this case the overlay input sizes must be
0142 the same, but, in case of video overlays, the output size can be different. Any
0143 framebuffer can be connected to any overlay.
0144
0145 An overlay can be connected to one overlay manager. Also DISPC overlays can be
0146 connected only to DISPC overlay managers, and virtual overlays can be only
0147 connected to virtual overlays.
0148
0149 An overlay manager can be connected to one display. There are certain
0150 restrictions which kinds of displays an overlay manager can be connected:
0151
0152 - DISPC TV overlay manager can be only connected to TV display.
0153 - Virtual overlay managers can only be connected to DBI or DSI displays.
0154 - DISPC LCD overlay manager can be connected to all displays, except TV
0155 display.
0156
0157 Sysfs
0158 -----
0159 The sysfs interface is mainly used for testing. I don't think sysfs
0160 interface is the best for this in the final version, but I don't quite know
0161 what would be the best interfaces for these things.
0162
0163 The sysfs interface is divided to two parts: DSS and FB.
0164
0165 /sys/class/graphics/fb? directory:
0166 mirror 0=off, 1=on
0167 rotate Rotation 0-3 for 0, 90, 180, 270 degrees
0168 rotate_type 0 = DMA rotation, 1 = VRFB rotation
0169 overlays List of overlay numbers to which framebuffer pixels go
0170 phys_addr Physical address of the framebuffer
0171 virt_addr Virtual address of the framebuffer
0172 size Size of the framebuffer
0173
0174 /sys/devices/platform/omapdss/overlay? directory:
0175 enabled 0=off, 1=on
0176 input_size width,height (ie. the framebuffer size)
0177 manager Destination overlay manager name
0178 name
0179 output_size width,height
0180 position x,y
0181 screen_width width
0182 global_alpha global alpha 0-255 0=transparent 255=opaque
0183
0184 /sys/devices/platform/omapdss/manager? directory:
0185 display Destination display
0186 name
0187 alpha_blending_enabled 0=off, 1=on
0188 trans_key_enabled 0=off, 1=on
0189 trans_key_type gfx-destination, video-source
0190 trans_key_value transparency color key (RGB24)
0191 default_color default background color (RGB24)
0192
0193 /sys/devices/platform/omapdss/display? directory:
0194
0195 =============== =============================================================
0196 ctrl_name Controller name
0197 mirror 0=off, 1=on
0198 update_mode 0=off, 1=auto, 2=manual
0199 enabled 0=off, 1=on
0200 name
0201 rotate Rotation 0-3 for 0, 90, 180, 270 degrees
0202 timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw)
0203 When writing, two special timings are accepted for tv-out:
0204 "pal" and "ntsc"
0205 panel_name
0206 tear_elim Tearing elimination 0=off, 1=on
0207 output_type Output type (video encoder only): "composite" or "svideo"
0208 =============== =============================================================
0209
0210 There are also some debugfs files at <debugfs>/omapdss/ which show information
0211 about clocks and registers.
0212
0213 Examples
0214 --------
0215
0216 The following definitions have been made for the examples below::
0217
0218 ovl0=/sys/devices/platform/omapdss/overlay0
0219 ovl1=/sys/devices/platform/omapdss/overlay1
0220 ovl2=/sys/devices/platform/omapdss/overlay2
0221
0222 mgr0=/sys/devices/platform/omapdss/manager0
0223 mgr1=/sys/devices/platform/omapdss/manager1
0224
0225 lcd=/sys/devices/platform/omapdss/display0
0226 dvi=/sys/devices/platform/omapdss/display1
0227 tv=/sys/devices/platform/omapdss/display2
0228
0229 fb0=/sys/class/graphics/fb0
0230 fb1=/sys/class/graphics/fb1
0231 fb2=/sys/class/graphics/fb2
0232
0233 Default setup on OMAP3 SDP
0234 --------------------------
0235
0236 Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI
0237 and TV-out are not in use. The columns from left to right are:
0238 framebuffers, overlays, overlay managers, displays. Framebuffers are
0239 handled by omapfb, and the rest by the DSS::
0240
0241 FB0 --- GFX -\ DVI
0242 FB1 --- VID1 --+- LCD ---- LCD
0243 FB2 --- VID2 -/ TV ----- TV
0244
0245 Example: Switch from LCD to DVI
0246 -------------------------------
0247
0248 ::
0249
0250 w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
0251 h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
0252
0253 echo "0" > $lcd/enabled
0254 echo "" > $mgr0/display
0255 fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
0256 # at this point you have to switch the dvi/lcd dip-switch from the omap board
0257 echo "dvi" > $mgr0/display
0258 echo "1" > $dvi/enabled
0259
0260 After this the configuration looks like:::
0261
0262 FB0 --- GFX -\ -- DVI
0263 FB1 --- VID1 --+- LCD -/ LCD
0264 FB2 --- VID2 -/ TV ----- TV
0265
0266 Example: Clone GFX overlay to LCD and TV
0267 ----------------------------------------
0268
0269 ::
0270
0271 w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
0272 h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
0273
0274 echo "0" > $ovl0/enabled
0275 echo "0" > $ovl1/enabled
0276
0277 echo "" > $fb1/overlays
0278 echo "0,1" > $fb0/overlays
0279
0280 echo "$w,$h" > $ovl1/output_size
0281 echo "tv" > $ovl1/manager
0282
0283 echo "1" > $ovl0/enabled
0284 echo "1" > $ovl1/enabled
0285
0286 echo "1" > $tv/enabled
0287
0288 After this the configuration looks like (only relevant parts shown)::
0289
0290 FB0 +-- GFX ---- LCD ---- LCD
0291 \- VID1 ---- TV ---- TV
0292
0293 Misc notes
0294 ----------
0295
0296 OMAP FB allocates the framebuffer memory using the standard dma allocator. You
0297 can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma
0298 allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase
0299 the global memory area for CMA.
0300
0301 Using DSI DPLL to generate pixel clock it is possible produce the pixel clock
0302 of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI.
0303
0304 Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB
0305 does not support mirroring.
0306
0307 VRFB rotation requires much more memory than non-rotated framebuffer, so you
0308 probably need to increase your vram setting before using VRFB rotation. Also,
0309 many applications may not work with VRFB if they do not pay attention to all
0310 framebuffer parameters.
0311
0312 Kernel boot arguments
0313 ---------------------
0314
0315 omapfb.mode=<display>:<mode>[,...]
0316 - Default video mode for specified displays. For example,
0317 "dvi:800x400MR-24@60". See drivers/video/modedb.c.
0318 There are also two special modes: "pal" and "ntsc" that
0319 can be used to tv out.
0320
0321 omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]
0322 - VRAM allocated for a framebuffer. Normally omapfb allocates vram
0323 depending on the display size. With this you can manually allocate
0324 more or define the physical address of each framebuffer. For example,
0325 "1:4M" to allocate 4M for fb1.
0326
0327 omapfb.debug=<y|n>
0328 - Enable debug printing. You have to have OMAPFB debug support enabled
0329 in kernel config.
0330
0331 omapfb.test=<y|n>
0332 - Draw test pattern to framebuffer whenever framebuffer settings change.
0333 You need to have OMAPFB debug support enabled in kernel config.
0334
0335 omapfb.vrfb=<y|n>
0336 - Use VRFB rotation for all framebuffers.
0337
0338 omapfb.rotate=<angle>
0339 - Default rotation applied to all framebuffers.
0340 0 - 0 degree rotation
0341 1 - 90 degree rotation
0342 2 - 180 degree rotation
0343 3 - 270 degree rotation
0344
0345 omapfb.mirror=<y|n>
0346 - Default mirror for all framebuffers. Only works with DMA rotation.
0347
0348 omapdss.def_disp=<display>
0349 - Name of default display, to which all overlays will be connected.
0350 Common examples are "lcd" or "tv".
0351
0352 omapdss.debug=<y|n>
0353 - Enable debug printing. You have to have DSS debug support enabled in
0354 kernel config.
0355
0356 TODO
0357 ----
0358
0359 DSS locking
0360
0361 Error checking
0362
0363 - Lots of checks are missing or implemented just as BUG()
0364
0365 System DMA update for DSI
0366
0367 - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
0368 to skip the empty byte?)
0369
0370 OMAP1 support
0371
0372 - Not sure if needed
