![Mauro Carvalho Chehab](/assets/img/avatar_default.png)
Converts ARM the text files to ReST, preparing them to be an architecture book. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Reviewed-by Corentin Labbe <clabbe.montjoie@gmail.com> # For sun4i-ss
373 lines
13 KiB
ReStructuredText
373 lines
13 KiB
ReStructuredText
=========================
|
|
OMAP2/3 Display Subsystem
|
|
=========================
|
|
|
|
This is an almost total rewrite of the OMAP FB driver in drivers/video/omap
|
|
(let's call it DSS1). The main differences between DSS1 and DSS2 are DSI,
|
|
TV-out and multiple display support, but there are lots of small improvements
|
|
also.
|
|
|
|
The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB,
|
|
panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live
|
|
currently side by side, you can choose which one to use.
|
|
|
|
Features
|
|
--------
|
|
|
|
Working and tested features include:
|
|
|
|
- MIPI DPI (parallel) output
|
|
- MIPI DSI output in command mode
|
|
- MIPI DBI (RFBI) output
|
|
- SDI output
|
|
- TV output
|
|
- All pieces can be compiled as a module or inside kernel
|
|
- Use DISPC to update any of the outputs
|
|
- Use CPU to update RFBI or DSI output
|
|
- OMAP DISPC planes
|
|
- RGB16, RGB24 packed, RGB24 unpacked
|
|
- YUV2, UYVY
|
|
- Scaling
|
|
- Adjusting DSS FCK to find a good pixel clock
|
|
- Use DSI DPLL to create DSS FCK
|
|
|
|
Tested boards include:
|
|
- OMAP3 SDP board
|
|
- Beagle board
|
|
- N810
|
|
|
|
omapdss driver
|
|
--------------
|
|
|
|
The DSS driver does not itself have any support for Linux framebuffer, V4L or
|
|
such like the current ones, but it has an internal kernel API that upper level
|
|
drivers can use.
|
|
|
|
The DSS driver models OMAP's overlays, overlay managers and displays in a
|
|
flexible way to enable non-common multi-display configuration. In addition to
|
|
modelling the hardware overlays, omapdss supports virtual overlays and overlay
|
|
managers. These can be used when updating a display with CPU or system DMA.
|
|
|
|
omapdss driver support for audio
|
|
--------------------------------
|
|
There exist several display technologies and standards that support audio as
|
|
well. Hence, it is relevant to update the DSS device driver to provide an audio
|
|
interface that may be used by an audio driver or any other driver interested in
|
|
the functionality.
|
|
|
|
The audio_enable function is intended to prepare the relevant
|
|
IP for playback (e.g., enabling an audio FIFO, taking in/out of reset
|
|
some IP, enabling companion chips, etc). It is intended to be called before
|
|
audio_start. The audio_disable function performs the reverse operation and is
|
|
intended to be called after audio_stop.
|
|
|
|
While a given DSS device driver may support audio, it is possible that for
|
|
certain configurations audio is not supported (e.g., an HDMI display using a
|
|
VESA video timing). The audio_supported function is intended to query whether
|
|
the current configuration of the display supports audio.
|
|
|
|
The audio_config function is intended to configure all the relevant audio
|
|
parameters of the display. In order to make the function independent of any
|
|
specific DSS device driver, a struct omap_dss_audio is defined. Its purpose
|
|
is to contain all the required parameters for audio configuration. At the
|
|
moment, such structure contains pointers to IEC-60958 channel status word
|
|
and CEA-861 audio infoframe structures. This should be enough to support
|
|
HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958.
|
|
|
|
The audio_enable/disable, audio_config and audio_supported functions could be
|
|
implemented as functions that may sleep. Hence, they should not be called
|
|
while holding a spinlock or a readlock.
|
|
|
|
The audio_start/audio_stop function is intended to effectively start/stop audio
|
|
playback after the configuration has taken place. These functions are designed
|
|
to be used in an atomic context. Hence, audio_start should return quickly and be
|
|
called only after all the needed resources for audio playback (audio FIFOs,
|
|
DMA channels, companion chips, etc) have been enabled to begin data transfers.
|
|
audio_stop is designed to only stop the audio transfers. The resources used
|
|
for playback are released using audio_disable.
|
|
|
|
The enum omap_dss_audio_state may be used to help the implementations of
|
|
the interface to keep track of the audio state. The initial state is _DISABLED;
|
|
then, the state transitions to _CONFIGURED, and then, when it is ready to
|
|
play audio, to _ENABLED. The state _PLAYING is used when the audio is being
|
|
rendered.
|
|
|
|
|
|
Panel and controller drivers
|
|
----------------------------
|
|
|
|
The drivers implement panel or controller specific functionality and are not
|
|
usually visible to users except through omapfb driver. They register
|
|
themselves to the DSS driver.
|
|
|
|
omapfb driver
|
|
-------------
|
|
|
|
The omapfb driver implements arbitrary number of standard linux framebuffers.
|
|
These framebuffers can be routed flexibly to any overlays, thus allowing very
|
|
dynamic display architecture.
|
|
|
|
The driver exports some omapfb specific ioctls, which are compatible with the
|
|
ioctls in the old driver.
|
|
|
|
The rest of the non standard features are exported via sysfs. Whether the final
|
|
implementation will use sysfs, or ioctls, is still open.
|
|
|
|
V4L2 drivers
|
|
------------
|
|
|
|
V4L2 is being implemented in TI.
|
|
|
|
From omapdss point of view the V4L2 drivers should be similar to framebuffer
|
|
driver.
|
|
|
|
Architecture
|
|
--------------------
|
|
|
|
Some clarification what the different components do:
|
|
|
|
- Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the
|
|
pixel data for the image. Framebuffer has width and height and color
|
|
depth.
|
|
- Overlay defines where the pixels are read from and where they go on the
|
|
screen. The overlay may be smaller than framebuffer, thus displaying only
|
|
part of the framebuffer. The position of the overlay may be changed if
|
|
the overlay is smaller than the display.
|
|
- Overlay manager combines the overlays in to one image and feeds them to
|
|
display.
|
|
- Display is the actual physical display device.
|
|
|
|
A framebuffer can be connected to multiple overlays to show the same pixel data
|
|
on all of the overlays. Note that in this case the overlay input sizes must be
|
|
the same, but, in case of video overlays, the output size can be different. Any
|
|
framebuffer can be connected to any overlay.
|
|
|
|
An overlay can be connected to one overlay manager. Also DISPC overlays can be
|
|
connected only to DISPC overlay managers, and virtual overlays can be only
|
|
connected to virtual overlays.
|
|
|
|
An overlay manager can be connected to one display. There are certain
|
|
restrictions which kinds of displays an overlay manager can be connected:
|
|
|
|
- DISPC TV overlay manager can be only connected to TV display.
|
|
- Virtual overlay managers can only be connected to DBI or DSI displays.
|
|
- DISPC LCD overlay manager can be connected to all displays, except TV
|
|
display.
|
|
|
|
Sysfs
|
|
-----
|
|
The sysfs interface is mainly used for testing. I don't think sysfs
|
|
interface is the best for this in the final version, but I don't quite know
|
|
what would be the best interfaces for these things.
|
|
|
|
The sysfs interface is divided to two parts: DSS and FB.
|
|
|
|
/sys/class/graphics/fb? directory:
|
|
mirror 0=off, 1=on
|
|
rotate Rotation 0-3 for 0, 90, 180, 270 degrees
|
|
rotate_type 0 = DMA rotation, 1 = VRFB rotation
|
|
overlays List of overlay numbers to which framebuffer pixels go
|
|
phys_addr Physical address of the framebuffer
|
|
virt_addr Virtual address of the framebuffer
|
|
size Size of the framebuffer
|
|
|
|
/sys/devices/platform/omapdss/overlay? directory:
|
|
enabled 0=off, 1=on
|
|
input_size width,height (ie. the framebuffer size)
|
|
manager Destination overlay manager name
|
|
name
|
|
output_size width,height
|
|
position x,y
|
|
screen_width width
|
|
global_alpha global alpha 0-255 0=transparent 255=opaque
|
|
|
|
/sys/devices/platform/omapdss/manager? directory:
|
|
display Destination display
|
|
name
|
|
alpha_blending_enabled 0=off, 1=on
|
|
trans_key_enabled 0=off, 1=on
|
|
trans_key_type gfx-destination, video-source
|
|
trans_key_value transparency color key (RGB24)
|
|
default_color default background color (RGB24)
|
|
|
|
/sys/devices/platform/omapdss/display? directory:
|
|
|
|
=============== =============================================================
|
|
ctrl_name Controller name
|
|
mirror 0=off, 1=on
|
|
update_mode 0=off, 1=auto, 2=manual
|
|
enabled 0=off, 1=on
|
|
name
|
|
rotate Rotation 0-3 for 0, 90, 180, 270 degrees
|
|
timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw)
|
|
When writing, two special timings are accepted for tv-out:
|
|
"pal" and "ntsc"
|
|
panel_name
|
|
tear_elim Tearing elimination 0=off, 1=on
|
|
output_type Output type (video encoder only): "composite" or "svideo"
|
|
=============== =============================================================
|
|
|
|
There are also some debugfs files at <debugfs>/omapdss/ which show information
|
|
about clocks and registers.
|
|
|
|
Examples
|
|
--------
|
|
|
|
The following definitions have been made for the examples below::
|
|
|
|
ovl0=/sys/devices/platform/omapdss/overlay0
|
|
ovl1=/sys/devices/platform/omapdss/overlay1
|
|
ovl2=/sys/devices/platform/omapdss/overlay2
|
|
|
|
mgr0=/sys/devices/platform/omapdss/manager0
|
|
mgr1=/sys/devices/platform/omapdss/manager1
|
|
|
|
lcd=/sys/devices/platform/omapdss/display0
|
|
dvi=/sys/devices/platform/omapdss/display1
|
|
tv=/sys/devices/platform/omapdss/display2
|
|
|
|
fb0=/sys/class/graphics/fb0
|
|
fb1=/sys/class/graphics/fb1
|
|
fb2=/sys/class/graphics/fb2
|
|
|
|
Default setup on OMAP3 SDP
|
|
--------------------------
|
|
|
|
Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI
|
|
and TV-out are not in use. The columns from left to right are:
|
|
framebuffers, overlays, overlay managers, displays. Framebuffers are
|
|
handled by omapfb, and the rest by the DSS::
|
|
|
|
FB0 --- GFX -\ DVI
|
|
FB1 --- VID1 --+- LCD ---- LCD
|
|
FB2 --- VID2 -/ TV ----- TV
|
|
|
|
Example: Switch from LCD to DVI
|
|
-------------------------------
|
|
|
|
::
|
|
|
|
w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
|
|
h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
|
|
|
|
echo "0" > $lcd/enabled
|
|
echo "" > $mgr0/display
|
|
fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
|
|
# at this point you have to switch the dvi/lcd dip-switch from the omap board
|
|
echo "dvi" > $mgr0/display
|
|
echo "1" > $dvi/enabled
|
|
|
|
After this the configuration looks like:::
|
|
|
|
FB0 --- GFX -\ -- DVI
|
|
FB1 --- VID1 --+- LCD -/ LCD
|
|
FB2 --- VID2 -/ TV ----- TV
|
|
|
|
Example: Clone GFX overlay to LCD and TV
|
|
----------------------------------------
|
|
|
|
::
|
|
|
|
w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
|
|
h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
|
|
|
|
echo "0" > $ovl0/enabled
|
|
echo "0" > $ovl1/enabled
|
|
|
|
echo "" > $fb1/overlays
|
|
echo "0,1" > $fb0/overlays
|
|
|
|
echo "$w,$h" > $ovl1/output_size
|
|
echo "tv" > $ovl1/manager
|
|
|
|
echo "1" > $ovl0/enabled
|
|
echo "1" > $ovl1/enabled
|
|
|
|
echo "1" > $tv/enabled
|
|
|
|
After this the configuration looks like (only relevant parts shown)::
|
|
|
|
FB0 +-- GFX ---- LCD ---- LCD
|
|
\- VID1 ---- TV ---- TV
|
|
|
|
Misc notes
|
|
----------
|
|
|
|
OMAP FB allocates the framebuffer memory using the standard dma allocator. You
|
|
can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma
|
|
allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase
|
|
the global memory area for CMA.
|
|
|
|
Using DSI DPLL to generate pixel clock it is possible produce the pixel clock
|
|
of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI.
|
|
|
|
Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB
|
|
does not support mirroring.
|
|
|
|
VRFB rotation requires much more memory than non-rotated framebuffer, so you
|
|
probably need to increase your vram setting before using VRFB rotation. Also,
|
|
many applications may not work with VRFB if they do not pay attention to all
|
|
framebuffer parameters.
|
|
|
|
Kernel boot arguments
|
|
---------------------
|
|
|
|
omapfb.mode=<display>:<mode>[,...]
|
|
- Default video mode for specified displays. For example,
|
|
"dvi:800x400MR-24@60". See drivers/video/modedb.c.
|
|
There are also two special modes: "pal" and "ntsc" that
|
|
can be used to tv out.
|
|
|
|
omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]
|
|
- VRAM allocated for a framebuffer. Normally omapfb allocates vram
|
|
depending on the display size. With this you can manually allocate
|
|
more or define the physical address of each framebuffer. For example,
|
|
"1:4M" to allocate 4M for fb1.
|
|
|
|
omapfb.debug=<y|n>
|
|
- Enable debug printing. You have to have OMAPFB debug support enabled
|
|
in kernel config.
|
|
|
|
omapfb.test=<y|n>
|
|
- Draw test pattern to framebuffer whenever framebuffer settings change.
|
|
You need to have OMAPFB debug support enabled in kernel config.
|
|
|
|
omapfb.vrfb=<y|n>
|
|
- Use VRFB rotation for all framebuffers.
|
|
|
|
omapfb.rotate=<angle>
|
|
- Default rotation applied to all framebuffers.
|
|
0 - 0 degree rotation
|
|
1 - 90 degree rotation
|
|
2 - 180 degree rotation
|
|
3 - 270 degree rotation
|
|
|
|
omapfb.mirror=<y|n>
|
|
- Default mirror for all framebuffers. Only works with DMA rotation.
|
|
|
|
omapdss.def_disp=<display>
|
|
- Name of default display, to which all overlays will be connected.
|
|
Common examples are "lcd" or "tv".
|
|
|
|
omapdss.debug=<y|n>
|
|
- Enable debug printing. You have to have DSS debug support enabled in
|
|
kernel config.
|
|
|
|
TODO
|
|
----
|
|
|
|
DSS locking
|
|
|
|
Error checking
|
|
|
|
- Lots of checks are missing or implemented just as BUG()
|
|
|
|
System DMA update for DSI
|
|
|
|
- Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
|
|
to skip the empty byte?)
|
|
|
|
OMAP1 support
|
|
|
|
- Not sure if needed
|