Signed-off-by: Tomi Valkeinen <tomi.valkeinen@xxxxxxxxx> --- 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 + -- To unsubscribe from this list: send the line "unsubscribe linux-omap" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
