[PATCH 01/12] DSS: Documentation for DSS2

[Tomi Valkeinen <tomi.valkeinen@nokia.com>]

Signed-off-by: Tomi Valkeinen <tomi.valkeinen@nokia.com>
---

 Documentation/arm/OMAP/DSS |  270 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 270 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/arm/OMAP/DSS

diff --git a/Documentation/arm/OMAP/DSS b/Documentation/arm/OMAP/DSS
new file mode 100644
index 0000000..011fee1
--- /dev/null
+++ b/Documentation/arm/OMAP/DSS
@@ -0,0 +1,270 @@
+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 (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.
+
+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
+
+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 DMA.
+
+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 omap-dss 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 a hack, but works 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.
+
+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>
+	x:<xpos>
+	y:<ypos>
+	iw:<input width, read only>
+	ih:<input height, read only>
+	w:<output width>
+	h:<output height>
+	e:<enabled>
+
+"managers" lists all overlay managers. Its format is:
+	<manager name>
+	t:<target display>
+
+"displays" lists all displays. Its format is:
+	<display name>
+	e:<enabled>
+	u:<update mode>
+	t:<tear sync on/off>
+	h:<xres/hfp/hbp/hsw>
+	v:<yres/vfp/vbp/vsw>
+	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 which
+shows how DSS has configured the clocks.
+
+Examples
+--------
+
+In the example scripts "omapfb" is a symlink to /sys/devices/platform/omapfb/.
+
+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 -vxres $w -vyres $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.
+
+Arguments
+---------
+
+vram
+	- Amount of total VRAM to preallocate. For example, "10M". omapfb
+	  allocates memory for framebuffers from VRAM.
+
+omapfb.video_mode
+	- Default video mode for default display. For example,
+	  "800x400MR-24@60".  See drivers/video/modedb.c
+
+omapfb.vram
+	- 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.
+
+omapfb.debug
+	- Enable debug printing. You have to have OMAPFB debug support enabled
+	  in kernel config.
+
+omap-dss.def_disp
+	- Name of default display, to which all overlays will be connected.
+	  Common examples are "lcd" or "tv".
+
+omap-dss.debug
+	- 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()
+
+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
+
+OMAP1 support
+- Not sure if needed
+