cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

dss.rst (12936B)


      1=========================
      2OMAP2/3 Display Subsystem
      3=========================
      4
      5This is an almost total rewrite of the OMAP FB driver in drivers/video/omap
      6(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 improvements
      8also.
      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 live
     12currently side by side, you can choose which one to use.
     13
     14Features
     15--------
     16
     17Working and tested features include:
     18
     19- MIPI DPI (parallel) output
     20- MIPI DSI output in command mode
     21- MIPI DBI (RFBI) output
     22- SDI output
     23- TV output
     24- All pieces can be compiled as a module or inside kernel
     25- Use DISPC to update any of the outputs
     26- Use CPU to update RFBI or DSI output
     27- OMAP DISPC planes
     28- RGB16, RGB24 packed, RGB24 unpacked
     29- YUV2, UYVY
     30- Scaling
     31- Adjusting DSS FCK to find a good pixel clock
     32- Use DSI DPLL to create DSS FCK
     33
     34Tested boards include:
     35- OMAP3 SDP board
     36- Beagle board
     37- N810
     38
     39omapdss driver
     40--------------
     41
     42The DSS driver does not itself have any support for Linux framebuffer, V4L or
     43such like the current ones, but it has an internal kernel API that upper level
     44drivers can use.
     45
     46The DSS driver models OMAP's overlays, overlay managers and displays in a
     47flexible way to enable non-common multi-display configuration. In addition to
     48modelling the hardware overlays, omapdss supports virtual overlays and overlay
     49managers. These can be used when updating a display with CPU or system DMA.
     50
     51omapdss driver support for audio
     52--------------------------------
     53There exist several display technologies and standards that support audio as
     54well. Hence, it is relevant to update the DSS device driver to provide an audio
     55interface that may be used by an audio driver or any other driver interested in
     56the functionality.
     57
     58The audio_enable function is intended to prepare the relevant
     59IP for playback (e.g., enabling an audio FIFO, taking in/out of reset
     60some IP, enabling companion chips, etc). It is intended to be called before
     61audio_start. The audio_disable function performs the reverse operation and is
     62intended to be called after audio_stop.
     63
     64While a given DSS device driver may support audio, it is possible that for
     65certain configurations audio is not supported (e.g., an HDMI display using a
     66VESA video timing). The audio_supported function is intended to query whether
     67the current configuration of the display supports audio.
     68
     69The audio_config function is intended to configure all the relevant audio
     70parameters of the display. In order to make the function independent of any
     71specific DSS device driver, a struct omap_dss_audio is defined. Its purpose
     72is to contain all the required parameters for audio configuration. At the
     73moment, such structure contains pointers to IEC-60958 channel status word
     74and CEA-861 audio infoframe structures. This should be enough to support
     75HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958.
     76
     77The audio_enable/disable, audio_config and audio_supported functions could be
     78implemented as functions that may sleep. Hence, they should not be called
     79while holding a spinlock or a readlock.
     80
     81The audio_start/audio_stop function is intended to effectively start/stop audio
     82playback after the configuration has taken place. These functions are designed
     83to be used in an atomic context. Hence, audio_start should return quickly and be
     84called 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 used
     87for playback are released using audio_disable.
     88
     89The enum omap_dss_audio_state may be used to help the implementations of
     90the 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 to
     92play audio, to _ENABLED. The state _PLAYING is used when the audio is being
     93rendered.
     94
     95
     96Panel and controller drivers
     97----------------------------
     98
     99The drivers implement panel or controller specific functionality and are not
    100usually visible to users except through omapfb driver.  They register
    101themselves to the DSS driver.
    102
    103omapfb driver
    104-------------
    105
    106The omapfb driver implements arbitrary number of standard linux framebuffers.
    107These framebuffers can be routed flexibly to any overlays, thus allowing very
    108dynamic display architecture.
    109
    110The driver exports some omapfb specific ioctls, which are compatible with the
    111ioctls in the old driver.
    112
    113The rest of the non standard features are exported via sysfs. Whether the final
    114implementation will use sysfs, or ioctls, is still open.
    115
    116V4L2 drivers
    117------------
    118
    119V4L2 is being implemented in TI.
    120
    121From omapdss point of view the V4L2 drivers should be similar to framebuffer
    122driver.
    123
    124Architecture
    125--------------------
    126
    127Some clarification what the different components do:
    128
    129    - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the
    130      pixel data for the image. Framebuffer has width and height and color
    131      depth.
    132    - Overlay defines where the pixels are read from and where they go on the
    133      screen. The overlay may be smaller than framebuffer, thus displaying only
    134      part of the framebuffer. The position of the overlay may be changed if
    135      the overlay is smaller than the display.
    136    - Overlay manager combines the overlays in to one image and feeds them to
    137      display.
    138    - Display is the actual physical display device.
    139
    140A framebuffer can be connected to multiple overlays to show the same pixel data
    141on all of the overlays. Note that in this case the overlay input sizes must be
    142the same, but, in case of video overlays, the output size can be different. Any
    143framebuffer can be connected to any overlay.
    144
    145An overlay can be connected to one overlay manager. Also DISPC overlays can be
    146connected only to DISPC overlay managers, and virtual overlays can be only
    147connected to virtual overlays.
    148
    149An overlay manager can be connected to one display. There are certain
    150restrictions 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 TV
    155      display.
    156
    157Sysfs
    158-----
    159The sysfs interface is mainly used for testing. I don't think sysfs
    160interface is the best for this in the final version, but I don't quite know
    161what 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=on
    167rotate		Rotation 0-3 for 0, 90, 180, 270 degrees
    168rotate_type	0 = DMA rotation, 1 = VRFB rotation
    169overlays	List of overlay numbers to which framebuffer pixels go
    170phys_addr	Physical address of the framebuffer
    171virt_addr	Virtual address of the framebuffer
    172size		Size of the framebuffer
    173
    174/sys/devices/platform/omapdss/overlay? directory:
    175enabled		0=off, 1=on
    176input_size	width,height (ie. the framebuffer size)
    177manager		Destination overlay manager name
    178name
    179output_size	width,height
    180position	x,y
    181screen_width	width
    182global_alpha   	global alpha 0-255 0=transparent 255=opaque
    183
    184/sys/devices/platform/omapdss/manager? directory:
    185display				Destination display
    186name
    187alpha_blending_enabled		0=off, 1=on
    188trans_key_enabled		0=off, 1=on
    189trans_key_type			gfx-destination, video-source
    190trans_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 name
    197mirror		0=off, 1=on
    198update_mode	0=off, 1=auto, 2=manual
    199enabled		0=off, 1=on
    200name
    201rotate		Rotation 0-3 for 0, 90, 180, 270 degrees
    202timings		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_name
    206tear_elim	Tearing elimination 0=off, 1=on
    207output_type	Output type (video encoder only): "composite" or "svideo"
    208=============== =============================================================
    209
    210There are also some debugfs files at <debugfs>/omapdss/ which show information
    211about clocks and registers.
    212
    213Examples
    214--------
    215
    216The following definitions have been made for the examples below::
    217
    218	ovl0=/sys/devices/platform/omapdss/overlay0
    219	ovl1=/sys/devices/platform/omapdss/overlay1
    220	ovl2=/sys/devices/platform/omapdss/overlay2
    221
    222	mgr0=/sys/devices/platform/omapdss/manager0
    223	mgr1=/sys/devices/platform/omapdss/manager1
    224
    225	lcd=/sys/devices/platform/omapdss/display0
    226	dvi=/sys/devices/platform/omapdss/display1
    227	tv=/sys/devices/platform/omapdss/display2
    228
    229	fb0=/sys/class/graphics/fb0
    230	fb1=/sys/class/graphics/fb1
    231	fb2=/sys/class/graphics/fb2
    232
    233Default setup on OMAP3 SDP
    234--------------------------
    235
    236Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI
    237and TV-out are not in use. The columns from left to right are:
    238framebuffers, overlays, overlay managers, displays. Framebuffers are
    239handled by omapfb, and the rest by the DSS::
    240
    241	FB0 --- GFX  -\            DVI
    242	FB1 --- VID1 --+- LCD ---- LCD
    243	FB2 --- VID2 -/   TV ----- TV
    244
    245Example: Switch from LCD to DVI
    246-------------------------------
    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/enabled
    254	echo "" > $mgr0/display
    255	fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
    256	# at this point you have to switch the dvi/lcd dip-switch from the omap board
    257	echo "dvi" > $mgr0/display
    258	echo "1" > $dvi/enabled
    259
    260After this the configuration looks like:::
    261
    262	FB0 --- GFX  -\         -- DVI
    263	FB1 --- VID1 --+- LCD -/   LCD
    264	FB2 --- VID2 -/   TV ----- TV
    265
    266Example: Clone GFX overlay to LCD and TV
    267----------------------------------------
    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/enabled
    275	echo "0" > $ovl1/enabled
    276
    277	echo "" > $fb1/overlays
    278	echo "0,1" > $fb0/overlays
    279
    280	echo "$w,$h" > $ovl1/output_size
    281	echo "tv" > $ovl1/manager
    282
    283	echo "1" > $ovl0/enabled
    284	echo "1" > $ovl1/enabled
    285
    286	echo "1" > $tv/enabled
    287
    288After this the configuration looks like (only relevant parts shown)::
    289
    290	FB0 +-- GFX  ---- LCD ---- LCD
    291	\- VID1 ---- TV  ---- TV
    292
    293Misc notes
    294----------
    295
    296OMAP FB allocates the framebuffer memory using the standard dma allocator. You
    297can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma
    298allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase
    299the global memory area for CMA.
    300
    301Using DSI DPLL to generate pixel clock it is possible produce the pixel clock
    302of 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. VRFB
    305does not support mirroring.
    306
    307VRFB rotation requires much more memory than non-rotated framebuffer, so you
    308probably 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 all
    310framebuffer parameters.
    311
    312Kernel boot arguments
    313---------------------
    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" that
    319	  can be used to tv out.
    320
    321omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]
    322	- VRAM allocated for a framebuffer. Normally omapfb allocates vram
    323	  depending on the display size. With this you can manually allocate
    324	  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 enabled
    329	  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 rotation
    341	  1 - 90 degree rotation
    342	  2 - 180 degree rotation
    343	  3 - 270 degree rotation
    344
    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 in
    354	  kernel config.
    355
    356TODO
    357----
    358
    359DSS locking
    360
    361Error checking
    362
    363- Lots of checks are missing or implemented just as BUG()
    364
    365System DMA update for DSI
    366
    367- Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
    368  to skip the empty byte?)
    369
    370OMAP1 support
    371
    372- Not sure if needed