dss.rst 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372
  1. =========================
  2. OMAP2/3 Display Subsystem
  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. The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB,
  9. panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live
  10. currently side by side, you can choose which one to use.
  11. Features
  12. --------
  13. Working and tested features include:
  14. - MIPI DPI (parallel) output
  15. - MIPI DSI output in command mode
  16. - MIPI DBI (RFBI) output
  17. - SDI output
  18. - TV output
  19. - All pieces can be compiled as a module or inside kernel
  20. - Use DISPC to update any of the outputs
  21. - Use CPU to update RFBI or DSI output
  22. - OMAP DISPC planes
  23. - RGB16, RGB24 packed, RGB24 unpacked
  24. - YUV2, UYVY
  25. - Scaling
  26. - Adjusting DSS FCK to find a good pixel clock
  27. - Use DSI DPLL to create DSS FCK
  28. Tested boards include:
  29. - OMAP3 SDP board
  30. - Beagle board
  31. - N810
  32. omapdss driver
  33. --------------
  34. The DSS driver does not itself have any support for Linux framebuffer, V4L or
  35. such like the current ones, but it has an internal kernel API that upper level
  36. drivers can use.
  37. The DSS driver models OMAP's overlays, overlay managers and displays in a
  38. flexible way to enable non-common multi-display configuration. In addition to
  39. modelling the hardware overlays, omapdss supports virtual overlays and overlay
  40. managers. These can be used when updating a display with CPU or system DMA.
  41. omapdss driver support for audio
  42. --------------------------------
  43. There exist several display technologies and standards that support audio as
  44. well. Hence, it is relevant to update the DSS device driver to provide an audio
  45. interface that may be used by an audio driver or any other driver interested in
  46. the functionality.
  47. The audio_enable function is intended to prepare the relevant
  48. IP for playback (e.g., enabling an audio FIFO, taking in/out of reset
  49. some IP, enabling companion chips, etc). It is intended to be called before
  50. audio_start. The audio_disable function performs the reverse operation and is
  51. intended to be called after audio_stop.
  52. While a given DSS device driver may support audio, it is possible that for
  53. certain configurations audio is not supported (e.g., an HDMI display using a
  54. VESA video timing). The audio_supported function is intended to query whether
  55. the current configuration of the display supports audio.
  56. The audio_config function is intended to configure all the relevant audio
  57. parameters of the display. In order to make the function independent of any
  58. specific DSS device driver, a struct omap_dss_audio is defined. Its purpose
  59. is to contain all the required parameters for audio configuration. At the
  60. moment, such structure contains pointers to IEC-60958 channel status word
  61. and CEA-861 audio infoframe structures. This should be enough to support
  62. HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958.
  63. The audio_enable/disable, audio_config and audio_supported functions could be
  64. implemented as functions that may sleep. Hence, they should not be called
  65. while holding a spinlock or a readlock.
  66. The audio_start/audio_stop function is intended to effectively start/stop audio
  67. playback after the configuration has taken place. These functions are designed
  68. to be used in an atomic context. Hence, audio_start should return quickly and be
  69. called only after all the needed resources for audio playback (audio FIFOs,
  70. DMA channels, companion chips, etc) have been enabled to begin data transfers.
  71. audio_stop is designed to only stop the audio transfers. The resources used
  72. for playback are released using audio_disable.
  73. The enum omap_dss_audio_state may be used to help the implementations of
  74. the interface to keep track of the audio state. The initial state is _DISABLED;
  75. then, the state transitions to _CONFIGURED, and then, when it is ready to
  76. play audio, to _ENABLED. The state _PLAYING is used when the audio is being
  77. rendered.
  78. Panel and controller drivers
  79. ----------------------------
  80. The drivers implement panel or controller specific functionality and are not
  81. usually visible to users except through omapfb driver. They register
  82. themselves to the DSS driver.
  83. omapfb driver
  84. -------------
  85. The omapfb driver implements arbitrary number of standard linux framebuffers.
  86. These framebuffers can be routed flexibly to any overlays, thus allowing very
  87. dynamic display architecture.
  88. The driver exports some omapfb specific ioctls, which are compatible with the
  89. ioctls in the old driver.
  90. The rest of the non standard features are exported via sysfs. Whether the final
  91. implementation will use sysfs, or ioctls, is still open.
  92. V4L2 drivers
  93. ------------
  94. V4L2 is being implemented in TI.
  95. From omapdss point of view the V4L2 drivers should be similar to framebuffer
  96. driver.
  97. Architecture
  98. --------------------
  99. Some clarification what the different components do:
  100. - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the
  101. pixel data for the image. Framebuffer has width and height and color
  102. depth.
  103. - Overlay defines where the pixels are read from and where they go on the
  104. screen. The overlay may be smaller than framebuffer, thus displaying only
  105. part of the framebuffer. The position of the overlay may be changed if
  106. the overlay is smaller than the display.
  107. - Overlay manager combines the overlays in to one image and feeds them to
  108. display.
  109. - Display is the actual physical display device.
  110. A framebuffer can be connected to multiple overlays to show the same pixel data
  111. on all of the overlays. Note that in this case the overlay input sizes must be
  112. the same, but, in case of video overlays, the output size can be different. Any
  113. framebuffer can be connected to any overlay.
  114. An overlay can be connected to one overlay manager. Also DISPC overlays can be
  115. connected only to DISPC overlay managers, and virtual overlays can be only
  116. connected to virtual overlays.
  117. An overlay manager can be connected to one display. There are certain
  118. restrictions which kinds of displays an overlay manager can be connected:
  119. - DISPC TV overlay manager can be only connected to TV display.
  120. - Virtual overlay managers can only be connected to DBI or DSI displays.
  121. - DISPC LCD overlay manager can be connected to all displays, except TV
  122. display.
  123. Sysfs
  124. -----
  125. The sysfs interface is mainly used for testing. I don't think sysfs
  126. interface is the best for this in the final version, but I don't quite know
  127. what would be the best interfaces for these things.
  128. The sysfs interface is divided to two parts: DSS and FB.
  129. /sys/class/graphics/fb? directory:
  130. mirror 0=off, 1=on
  131. rotate Rotation 0-3 for 0, 90, 180, 270 degrees
  132. rotate_type 0 = DMA rotation, 1 = VRFB rotation
  133. overlays List of overlay numbers to which framebuffer pixels go
  134. phys_addr Physical address of the framebuffer
  135. virt_addr Virtual address of the framebuffer
  136. size Size of the framebuffer
  137. /sys/devices/platform/omapdss/overlay? directory:
  138. enabled 0=off, 1=on
  139. input_size width,height (ie. the framebuffer size)
  140. manager Destination overlay manager name
  141. name
  142. output_size width,height
  143. position x,y
  144. screen_width width
  145. global_alpha global alpha 0-255 0=transparent 255=opaque
  146. /sys/devices/platform/omapdss/manager? directory:
  147. display Destination display
  148. name
  149. alpha_blending_enabled 0=off, 1=on
  150. trans_key_enabled 0=off, 1=on
  151. trans_key_type gfx-destination, video-source
  152. trans_key_value transparency color key (RGB24)
  153. default_color default background color (RGB24)
  154. /sys/devices/platform/omapdss/display? directory:
  155. =============== =============================================================
  156. ctrl_name Controller name
  157. mirror 0=off, 1=on
  158. update_mode 0=off, 1=auto, 2=manual
  159. enabled 0=off, 1=on
  160. name
  161. rotate Rotation 0-3 for 0, 90, 180, 270 degrees
  162. timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw)
  163. When writing, two special timings are accepted for tv-out:
  164. "pal" and "ntsc"
  165. panel_name
  166. tear_elim Tearing elimination 0=off, 1=on
  167. output_type Output type (video encoder only): "composite" or "svideo"
  168. =============== =============================================================
  169. There are also some debugfs files at <debugfs>/omapdss/ which show information
  170. about clocks and registers.
  171. Examples
  172. --------
  173. The following definitions have been made for the examples below::
  174. ovl0=/sys/devices/platform/omapdss/overlay0
  175. ovl1=/sys/devices/platform/omapdss/overlay1
  176. ovl2=/sys/devices/platform/omapdss/overlay2
  177. mgr0=/sys/devices/platform/omapdss/manager0
  178. mgr1=/sys/devices/platform/omapdss/manager1
  179. lcd=/sys/devices/platform/omapdss/display0
  180. dvi=/sys/devices/platform/omapdss/display1
  181. tv=/sys/devices/platform/omapdss/display2
  182. fb0=/sys/class/graphics/fb0
  183. fb1=/sys/class/graphics/fb1
  184. fb2=/sys/class/graphics/fb2
  185. Default setup on OMAP3 SDP
  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. FB0 --- GFX -\ DVI
  192. FB1 --- VID1 --+- LCD ---- LCD
  193. FB2 --- VID2 -/ TV ----- TV
  194. Example: Switch from LCD to DVI
  195. -------------------------------
  196. ::
  197. w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
  198. h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
  199. echo "0" > $lcd/enabled
  200. echo "" > $mgr0/display
  201. fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
  202. # at this point you have to switch the dvi/lcd dip-switch from the omap board
  203. echo "dvi" > $mgr0/display
  204. echo "1" > $dvi/enabled
  205. After this the configuration looks like:::
  206. FB0 --- GFX -\ -- DVI
  207. FB1 --- VID1 --+- LCD -/ LCD
  208. FB2 --- VID2 -/ TV ----- TV
  209. Example: Clone GFX overlay to LCD and TV
  210. ----------------------------------------
  211. ::
  212. w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
  213. h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
  214. echo "0" > $ovl0/enabled
  215. echo "0" > $ovl1/enabled
  216. echo "" > $fb1/overlays
  217. echo "0,1" > $fb0/overlays
  218. echo "$w,$h" > $ovl1/output_size
  219. echo "tv" > $ovl1/manager
  220. echo "1" > $ovl0/enabled
  221. echo "1" > $ovl1/enabled
  222. echo "1" > $tv/enabled
  223. After this the configuration looks like (only relevant parts shown)::
  224. FB0 +-- GFX ---- LCD ---- LCD
  225. \- VID1 ---- TV ---- TV
  226. Misc notes
  227. ----------
  228. OMAP FB allocates the framebuffer memory using the standard dma allocator. You
  229. can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma
  230. allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase
  231. the global memory area for CMA.
  232. Using DSI DPLL to generate pixel clock it is possible produce the pixel clock
  233. of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI.
  234. Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB
  235. does not support mirroring.
  236. VRFB rotation requires much more memory than non-rotated framebuffer, so you
  237. probably need to increase your vram setting before using VRFB rotation. Also,
  238. many applications may not work with VRFB if they do not pay attention to all
  239. framebuffer parameters.
  240. Kernel boot arguments
  241. ---------------------
  242. omapfb.mode=<display>:<mode>[,...]
  243. - Default video mode for specified displays. For example,
  244. "dvi:800x400MR-24@60". See drivers/video/modedb.c.
  245. There are also two special modes: "pal" and "ntsc" that
  246. can be used to tv out.
  247. omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]
  248. - VRAM allocated for a framebuffer. Normally omapfb allocates vram
  249. depending on the display size. With this you can manually allocate
  250. more or define the physical address of each framebuffer. For example,
  251. "1:4M" to allocate 4M for fb1.
  252. omapfb.debug=<y|n>
  253. - Enable debug printing. You have to have OMAPFB debug support enabled
  254. in kernel config.
  255. omapfb.test=<y|n>
  256. - Draw test pattern to framebuffer whenever framebuffer settings change.
  257. You need to have OMAPFB debug support enabled in kernel config.
  258. omapfb.vrfb=<y|n>
  259. - Use VRFB rotation for all framebuffers.
  260. omapfb.rotate=<angle>
  261. - Default rotation applied to all framebuffers.
  262. 0 - 0 degree rotation
  263. 1 - 90 degree rotation
  264. 2 - 180 degree rotation
  265. 3 - 270 degree rotation
  266. omapfb.mirror=<y|n>
  267. - Default mirror for all framebuffers. Only works with DMA rotation.
  268. omapdss.def_disp=<display>
  269. - Name of default display, to which all overlays will be connected.
  270. Common examples are "lcd" or "tv".
  271. omapdss.debug=<y|n>
  272. - Enable debug printing. You have to have DSS debug support enabled in
  273. kernel config.
  274. TODO
  275. ----
  276. DSS locking
  277. Error checking
  278. - Lots of checks are missing or implemented just as BUG()
  279. System DMA update for DSI
  280. - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
  281. to skip the empty byte?)
  282. OMAP1 support
  283. - Not sure if needed