A big README update

The instructions, links, etc.
Signed-off-by: Siarhei Siamashka <siarhei.siamashka@gmail.com>

README

-xf86-video-sunxifb - video driver for devices based on the Allwinner A10/A13 SoC,
-and other ARM-based devices.
+xf86-video-sunxifb - video driver, primarily optimized for the devices powered
+by the Allwinner SoC (A10, A13, A20). It can use some of the 2D/3D hardware
+acceleration features.
 
-Please submit bugs & patches to:
+And because this driver is based on xf86-video-fbdev (with none of the
+original features stripped), it actually supports all the same hardware
+as xf86-video-fbdev. Essentially, xf86-video-sunxifb can be just used as
+a drop-in replacement and run on practically any Linux system. There will
+be no real difference on x86, but any ARM based system should see better
+performance thanks to some additional optimizations (the elimination of
+ShadowFB layer, ARM NEON/VFP code for dealing with uncached framebuffer
+reads, automatic backing store management for faster window moves).
 
-        https://github.com/ssvb/xf86-video-sunxifb
+== 2D graphics acceleration features ==
 
-All questions regarding this software should be directed at the
-linux-sunxi mailing list:
+Hardware accelerated window moving/scrolling on Allwinner A10/A20 (using the
+G2D Mixer Processor).
 
-        https://groups.google.com/d/forum/linux-sunxi
+== 3D graphics acceleration features ==
 
-This driver is intended to be a drop-in replacement for x86-video-mali
-and the installation instructions from http://linux-sunxi.org should
-also work. Gentoo Linux users may find the following portage overlay
-useful to simplify the installation process:
+First a disclaimer to prevent any possible misunderstanding. The Xorg DDX
+drivers (neither this one, nor the others) do not do any actual 3D acceleration
+by themselves. They are nothing else but just a glue between the 3D drivers
+and the X11 window system. Still a poorly implemented glue can easily become
+the source of major performance problems. So it's important to do it right.
 
-        https://github.com/ssvb/gentoo-overlay-sunxi-x11
+This DDX driver provides integration for Mali 400 GPU into Xorg. Any device
+with Mali 400 should have a properly working OpenGL ES 2.0 acceleration if
+it has Mali/UMP modules in the Linux kernel and libMali.so proprietary
+binary blob installed in the system. Additionally, the hardware overlay
+feature of Allwinner A10/A13/A20 display controller allows to support
+zero-copy OpenGL ES buffer flipping without tearing. The rest of the
+devices with Mali 400 hardware (Exynos4, Rockchip, ...) are expected to
+have roughly the same 3D performance as when using the reference vendor
+provided Xorg DDX driver xf86-video-mali.
+
+== Video acceleration features ==
+
+XV overlay is supported on Allwinner A10/A13/A20.
+
+== Installation instructions ==
+
+https://github.com/ssvb/xf86-video-sunxifb/wiki/Installation
+
+== Troubleshooting ==
+
+If something does not work right, it's a good idea to check dmesg log and
+/var/log/Xorg.0.log for any suspicious error messages or warnings.
+Some important notes:
+
+1. The messages "(EE) SUNXIFB(0): FBIOPUTCMAP: Invalid argument" in
+   Xorg.0.log can be safely ignored. They are harmless.
+
+2. If you are limited by exactly 60 FPS in benchmarks and want to see more,
+   then just change option "SwapbuffersWait" to "false" in /etc/X11/xorg.conf
+   Buffer swaps are synchronized to vertical refresh by default on Allwinner
+   hardware. This is generally good for the applications, but bad for
+   benchmarks.
+
+3. If there is still a high CPU usage in Xorg server and the performance
+   is poor for 3D graphics on Allwinner hardware, please make sure that
+   the framebuffer size reservation is large enough to allocate memory
+   for DRI2 buffers. The value fb0_framebuffer_num needs to be set at
+   least to 3 in the fex file. Also if you have a compositing window
+   manager, then compositing (the desktop effects) should be disabled
+   for best performance.
+
+   The expected final score for glmark2-es2 on Allwinner A10 hardware
+   with "SwapbuffersWait" set to "false" is more than 100-150. Some
+   of the individual tests from glmark2-es2 should run with more
+   than 200-300 FPS.
+
+4. https://github.com/ssvb/xf86-video-sunxifb/wiki/Troubleshooting
+
+== Contacts. Reporting bugs ==
+
+If something from the list above does not seem to work right, then that's
+likely either some misconfiguration issue or a bug in the code. Don't
+hesitate to ping me on #linux-sunxi, #odroid or #gentoo-embedded channels
+at freenode.net irc. I'm known as "ssvb" there. The platforms other than
+allwinner/sunxi are also supported.
+
+Or alternatively just use the issue tracker for reporting bugs:
+     https://github.com/ssvb/xf86-video-sunxifb/issues
+
+== Links to the other interesting projects ==
+
+- http://limadriver.org
+- https://github.com/jemk/libvdpau-sunxi
+
+== TL;DR ==
+
+This Xorg driver is a superset and drop-in replacement for xf86-video-fbdev
+and xf86-video-mali drivers. It just generally provides better performance
+on ARM hardware.