DSS2 documentation

Skip to first unread message

Koen Kooi

Jan 28, 2009, 4:42:36 AM1/28/09
to Beagle Board
OMAP2/3 Display Subsystem

This is an almost total rewrite of the OMAP FB driver in drivers/video/
(let's call it DSS1). The main differences between DSS1 and DSS2 are
TV-out and multiple display support.

The DSS2 driver (omap-dss 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.


Working and tested features include:

- MIPI DPI (parallel) output
- MIPI DSI output in command mode
- MIPI DBI (RFBI) output (not tested for a while, might've gotten
- 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
- Scaling
- Adjusting DSS FCK to find a good pixel clock
- Use DSI DPLL to create DSS FCK

omap-dss 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, omap-dss supports virtual overlays
and overlay
managers. These can be used when updating a display with CPU or system

Panel and controller drivers

The drivers implement panel or controller specific functionality and
are not
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
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

Currently there are no V4L2 display drivers planned, but it is
possible to
implement such either to omapfb driver, or as a separate one. From
point of view the V4L2 drivers should be similar to framebuffer driver.


Some clarification what the different components do:

- Framebuffer is a memory area inside OMAP's SDRAM that contains
the pixel
data for the image. Framebuffer has width and height and color
- 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 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
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

- DISPC TV overlay manager can be only connected to TV display.
- Virtual overlay managers can only be connected to DBI or DSI
- DISPC LCD overlay manager can be connected to all displays,
except TV

The sysfs interface is a hack, but works for testing. I don't think
interface is the best for this in the final version, but I don't quite
what would be the best interfaces for these things.

In /sys/devices/platform/omapfb we have four files: framebuffers,
overlays, managers and displays. You can read them so see the current
setup, and change them by writing to it in the form of
"<item-id> <opt1>:<val1> <opt2>:<val2>..."

"framebuffers" lists all framebuffers. Its format is:
<fb number>
p:<physical address, read only>
v:<virtual address, read only>
s:<size, read only>
t:<target overlay>

"overlays" lists all overlays. Its format is:
<overlay name>
t:<target manager>
iw:<input width, read only>
ih:<input height, read only>
w:<output width>
h:<output height>

"managers" lists all overlay managers. Its format is:
<manager name>
t:<target display>

"displays" lists all displays. Its format is:
<display name>
u:<update mode>
t:<tear sync on/off>
p:<pix clock, in kHz>
m:<mode str, as in drivers/video/modedb.c:fb_find_mode>

There is also a debug sysfs file at /sys/devices/platform/omap-dss/clk
shows how DSS has configured the clocks.


In the example scripts "omapfb" is a symlink to /sys/devices/platform/

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

Switch from LCD to DVI

dviline=`cat omapfb/displays |grep dvi`
w=`echo $dviline | cut -d " " -f 5 | cut -d ":" -f 2 | cut -d "/" -f 1`
h=`echo $dviline | cut -d " " -f 6 | cut -d ":" -f 2 | cut -d "/" -f 1`

echo "lcd e:0" > omapfb/displays
echo "lcd t:none" > omapfb/managers
fbset -fb /dev/fb0 -xres $w -yres $h
# at this point you have to switch the dvi/lcd dip-switch from the
omap board
echo "lcd t:dvi" > omapfb/managers
echo "dvi e:1" > omapfb/displays

After this the configuration looks like:

FB0 --- GFX -\ -- DVI
FB1 --- VID1 --+- LCD -/ LCD
FB2 --- VID2 -/ TV ----- TV

Clone GFX overlay to LCD and TV

tvline=`cat /sys/devices/platform/omapfb/displays |grep tv`
w=`echo $tvline | cut -d " " -f 5 | cut -d ":" -f 2 | cut -d "/" -f 1`
h=`echo $tvline | cut -d " " -f 6 | cut -d ":" -f 2 | cut -d "/" -f 1`

echo "1 t:none" > omapfb/framebuffers
echo "0 t:gfx,vid1" > omapfb/framebuffers
echo "gfx e:1" > omapfb/overlays
echo "vid1 t:tv w:$w h:$h e:1" > omapfb/overlays
echo "tv e:1" > omapfb/displays

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 OMAP VRAM
allocator. If
that fails, it will fall back to dma_alloc_writecombine().

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.


- Amount of total VRAM to preallocate. For example, "10M".

- Default video mode for default display. For example,
"800x400MR-24@60". See drivers/video/modedb.c

- VRAM allocated for each framebuffer. Normally omapfb allocates vram
depending on the display size. With this you can manually allocate
more. For example "4M,3M" allocates 4M for fb0, 3M for fb1.

- Enable debug printing. You have to have OMAPFB debug support enabled
in kernel config.

- Name of default display, to which all overlays will be connected.
Common examples are "lcd" or "tv".

- Enable debug printing. You have to have DSS debug support enabled in
kernel config.


DSS locking

Error checking
- Lots of checks are missing or implemented just as BUG()

Rotate (external FB)
Rotate (VRFB)
Rotate (SMS)

System DMA update for DSI
- Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
to skip the empty byte?)

Power management
- Context saving

Resolution change
- The x/y res of the framebuffer are not display resolutions, but the
of the overlay.
- The display resolution affects all planes on the display.

OMAP1 support
- Not sure if needed

Reply all
Reply to author
0 new messages