README update

1 files changed, 154 insertions, 131 deletions

diff --git a/README.md b/README.md
index 1850561..2727c1e 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,141 @@
 Introduction
 =================
 
-Project Etnaviv is an attempt to make an open source user-space driver for the Vivante GCxxx series of embedded GPUs.
+Project Etnaviv is an open source user-space driver for the Vivante GCxxx series of embedded GPUs.
 
-The project is currently mostly of use to developers interested in helping develop open source drivers for the 
-hardware, reverse engineering, or in interfacing with GPU hardware directly.
+A Mesa fork with the etnaviv driver can be found in the [laanwj/mesa](https://github.com/laanwj/mesa) repository. 
+At the moment, this driver provides rudimentary OpenGL ES 2.0 accelerated rendering direct to framebuffer (fbdev).
+OpenGL ES 1.0 should also work, but has not been tested much. There may still be quite a few rendering bugs, 
+specific bug reports are very welcome.
 
-A Mesa fork based on the etnaviv driver can be found at https://github.com/laanwj/mesa. At the moment, this
-provides rudimentary OpenGL ES 2.0 accelerated rendering direct to framebuffer (fbdev).
-
-Devices with Vivante GPU
+SoCs with Vivante GPU
 =========================
 
 ARM-based:
-- Google TV (Marvell Armada 1500, contains a GC1000)
-- OLPC (also Marvell Armada something with GC1000)
-- CuBox, including pro variant (Marvell Armada 510, GC600)
-- Many older tablets and such based on Rockchip 2918 SoC (GC800)
-- Freescale i.MX6 Series (GC2000 + GC320 + GC355)
-- Actions Semiconductor ATM7029 (GC1000?)
+- Marvell Armada 1500 has a GC1000: Google TV, OLPC
+- Marvell Armada 510 has a GC600: [CuBox](http://www.solid-run.com/cubox)
+- Rockchip 2918 has a GC800: some Arnova tablets
+- Freescale i.MX6 Quad has a GC2000 + GC320 + GC355 or GC880
+- Freescale i.MX6 DualLite and Solo have a GC880
+- Actions Semiconductor ATM7029 has a GC1000
 
 MIPS-based:
-- Devices based on Ingenic JZ4770 MIPS SoC (GC860), such as the GCW zero, and JZ4760 (GC200, 2D only).
+- Ingenic JZ4770 has a GC860: [GCW Zero](http://www.gcw-zero.com)
+- Ingenic JZ4760 has a GC200 (2D only)
 
 See also [wikipedia](https://en.wikipedia.org/wiki/Vivante_Corporation).
 
-For the Vivante GPUs on many platforms the detailed features and specs are known, these can be found in `doc/gpus_comparison.html`.
+For the Vivante GPUs on many platforms the detailed features and specs are known, these can be found in 
+[doc/gpus_comparison.html](http://dev.visucore.com/etna_viv/gpus_comparison.html).
+
+Compatibility
+----------------
+
+`etna_pipe` is currently compatible with at least the following GC chips:
+
+- GC600 (CuBox/dove)
+- GC800 (Rockchip/arnova)
+- GC860 (GCW Zero/v2)
+- GC880 (i.MX6)
+
+Support for GC2000 (i.MX6) and others with multiple pixel pipes planned.
+
+Building
+=========
+
+The build process is made more complicated by the existence of many different kernel drivers, with their subtly 
+different interface (different headers, different offsets for fields, different management of context, and so on). 
+These values for environment variable `GCABI` are supported out of the box:
+
+- `dove`: Marvell Dove, newer drivers (0.8.0.3184)
+- `dove_old`: Marvell Dove, older drivers (0.8.0.1998, 0.8.0.1123)
+- `arnova`: Android, Arnova 10B G3 tablet (RK2918)
+- `v2`: Various Android, for older chips (RK2918 etc.)
+- `imx6`: Various Android, for newer chips (i.MX6 specific)
+- `v4`: Various Android, for newer chips (i.MX6 etc.)
+
+If possible get the `gc_*.h` headers for your specific kernel version. If that's not possible, try to find which of the above sets
+of headers is most similar, and adapt that.
+
+General
+--------
+If you just need `libetnaviv.a` for building Mesa and are not planning to do reverse engineering,
+it is sufficient to run make in `native/etnaviv`.
+
+Otherwise, run `make` and `make rev` in `native/` (see the README.md in `native` for a description of all the directories contained within).
+
+`gc_abi.h`
+-----------
+`gc_abi.h` is an extra header that defines the following flags describing the kernel interface to etna, for a certain
+setting of the environment variable `GCABI`:
+
+- `GCABI_CONTEXT_HAS_PHYSICAL`: `struct _gcoCONTEXT` has `physical` and `bytes` fields
+- `GCABI_HAS_MINOR_FEATURES_2`: `struct _gcsHAL_QUERY_CHIP_IDENTITY` has `chipMinorFeatures2` field
+- `GCABI_HAS_MINOR_FEATURES_3`: `struct _gcsHAL_QUERY_CHIP_IDENTITY` has `chipMinorFeatures3` field
+- `GCABI_USER_SIGNAL_HAS_TYPE`: `struct _gcsHAL_USER_SIGNAL` has `signalType` field
+- `GCABI_HAS_CONTEXT`: `struct _gcsHAL_COMMIT` has `contextBuffer` field
+- `GCABI_HAS_STATE_DELTAS`: `struct _gcsHAL_COMMIT` has `delta` field
+
+It would be very useful to have an auto-detection of the Vivante kernel version, to prevent crashes and such from wrong
+interfaces. However, I don't currently know any way to do this. The kernel does check the size of the passed ioctl structure, however
+this guarantees nothing about the field offsets. There is `/proc/driver/gc` that in some cases contains a version number. In
+very new drivers there is an ioctl call `gcvHAL_VERSION` that returns the major, minor and build version.
+
+Linux cross compile
+--------------------
+
+For non-Android Linux ARM cross compile, create a script like this (example for CuBox) to set up the build environment. 
+When command stream dumping the egl demos, don't forget to also copy the EGL/GLES2/KDR headers from 
+some place and put them in a directory `include` under the location
+where the script is installed, and get the `libEGL.so` and `libGLESv2.so` from the device into `lib`:
+
+    DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+    export GCCPREFIX="arm-linux-gnueabi-"
+    export PLATFORM_CFLAGS="-I${DIR}/include"
+    export PLATFORM_CXXFLAGS="-I${DIR}/include"
+    export PLATFORM_LDFLAGS="-ldl -L${DIR}/lib"
+    export PLATFORM_GL_LIBS="-lEGL -lGLESv2 -L${TOP}/lib/egl -Xlinker --allow-shlib-undefined"
+    # Set GC kernel ABI to dove (important!)
+    #export GCABI="dove"      # 0.8.0.3184
+    export GCABI="dove_old"  # 0.8.0.1998, 0.8.0.1123
+
+If you haven't got the `arm-linux-gnueabi-` bintools, on an Debian/Ubuntu host they can be installed with
+
+    apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
+
+On ARM hardfloat targets you should use `gcc-arm-linux-gnueabihf-` instead.
+
+Android cross compile
+----------------------
+
+To build for an Android device, install the Android NDK and define the cross-build environment by setting
+environment variables, for example like this:
+
+    export NDK="/opt/ndk"
+    export TOOLCHAIN="/opt/ndk/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86"
+    export SYSROOT="/opt/ndk/platforms/android-14/arch-arm"
+    export PATH="$PATH:$TOOLCHAIN/bin"
+
+    export GCCPREFIX="arm-linux-androideabi-"
+    export CXXABI="armeabi-v7a"
+    export PLATFORM_CFLAGS="--sysroot=${SYSROOT} -DANDROID -DPIPE_ARCH_LITTLE_ENDIAN"
+    export PLATFORM_CXXFLAGS="--sysroot=${SYSROOT} -DANDROID -DPIPE_ARCH_LITTLE_ENDIAN -I${NDK}/sources/cxx-stl/gnu-libstdc++/4.6/include -I${NDK}/sources/cxx-stl/gnu-libstdc++/4.6/libs/${CXXABI}/include"
+    export PLATFORM_LDFLAGS="--sysroot=${SYSROOT} -L${NDK}/sources/cxx-stl/gnu-libstdc++/4.6/libs/${CXXABI} -lgnustl_static"
+    # Set GC kernel ABI (important!)
+    #export GCABI="v2"
+    #export GCABI="v4"
+    export GCABI="arnova"
+
+To build the egl samples (for command stream interception), you need to copy `libEGL_VIVANTE.so` `libGLESv2_VIVANTE.so` from 
+the device `/system/lib/egl` to `native/lib/egl`. This is not needed if you just want to build the `replay`, `etna` or `fb`
+tests, which do not rely in any way on the userspace blob.
+
 
 Contents
 ==========
 
 The repository contains various tools and documentation related to figuring out how to 
-program Vivante GCxxx GPU chips.
+program Vivante GCxxx GPU cores.
 
 Framebuffer tests
 ------------------
@@ -88,8 +192,24 @@ To get surfaceflinger out of the way type:
     (run test)
     adb shell start surfaceflinger
 
-State map
------------
+libetnaviv
+------------
+
+Low-level command buffer handling library and register definition headers.
+This library completely wraps the kernel interface, to isolate clients (such as Mesa) 
+from the madness of kernel-specific headers and defines.
+
+- ioctl (kernel interface) wrapping
+- video memory management
+- command buffer and event queue handling
+- context / state delta handling (still incomplete)
+- register description headers
+- converting surfaces and textures from and to Vivante specific tiling formats
+
+Currently used only by the 3D driver in `native/driver`. A future 2D, SVG or OpenCL driver can share this code.
+
+State map 
+----------
 
 Map of documentation for known render state and registers. Mapped in rules-ng-ng (envytools) format:
 
@@ -97,12 +217,16 @@ Map of documentation for known render state and registers. Mapped in rules-ng-ng
     rnndb/state_hi.xml  Host interface registers
     rnndb/state_2d.xml  2D engine state
     rnndb/state_3d.xml  3D engine state
+    rnndb/state_common.xml  Common, shared state defines
 
 Other scattered bits of documentation about the hardware and ISA can be found in `doc/hardware.md`.
 
 ISA documentation
 ------------------
-    
+
+Vivante has a unified, fixed-size, predictable instruction format with explicit inputs 
+and outputs. This does simplify code generation, compared to a weird flow 
+pipe system like the Mali 200/400.
 Shader (both vertex and fragment) instruction set description in rules-ng-ng format can be found here: 
 
     rnndb/isa.xml
@@ -111,10 +235,6 @@ Some written down notes, and examples of disassembled shaders can be found here:
 
     doc/isa.md
 
-Vivante has a unified, fixed-size, predictable instruction format with explicit inputs 
-and outputs. This does simplify code generation, compared to a weird flow 
-pipe system like the Mali 200/400.
-
 Assembler and disassembler
 ----------------------------
 
@@ -146,10 +266,10 @@ Command stream interception
 ----------------------------
 
 A significant part of reverse engineering was done by intercepting command streams while running GL simple demos. 
-`viv_hook` is a library to intercept and log the traffic between libGAL (the Vivante user space blob) and the kernel
+`viv_hook` is a library to intercept and log the traffic between `libGAL` (the Vivante user space blob) and the kernel
 driver / hardware.
     
-This library uses ELF hooks to intercept only system calls such as ioctl and mmap coming from the driver, not from
+This library uses ELF hooks to intercept only system calls such as `ioctl` and `mmap` coming from the driver, not from
 other parts of the application, unlike more crude hacks using `LD_PRELOAD`.
 
 At the beginning of the program call `the_hook`, at the end of the program call `end_hook` to finalize 
@@ -167,7 +287,7 @@ Other tools live in:
 
 The most useful ones, aside from the assembler and disassembler mentioned before are:
 
-- `show_egl2_log.sh` (uses `dump_cmdstream.py`, you may have to adapt this script to use another structure definition json depending on your kernel interface)
+- `show_egl2_log.sh` (uses `dump_cmdstream.py`, you may have to adapt this script to use another structure definition JSON depending on your kernel interface)
 
 Decodes and dumps the intercepted command stream in human readable format, making use of rnndb state maps.
 
@@ -198,8 +318,8 @@ it to the kernel driver:
     native/replay/etna_test.c (to experiment with shaders)
     native/replay/cube_etna.c (renders the GLES2 smoothed cube)
 
-Vivante GPL kernel driver
---------------------------
+Vivante GPL kernel drivers
+---------------------------
 
 The headers and implementation files for the Vivante GPL kernel drivers are also included:
 
@@ -215,10 +335,10 @@ to the GPU)
 Envytools fork
 ---------------
 
-Envytools (https://github.com/pathscale/envytools) is a set of tools aimed at developers of the open source
-NVidia driver Nouveau, however some parts such as rnndb can be applied more generally. The repository 
+[Envytools](https://github.com/pathscale/envytools) is a set of tools aimed at developers of the open source
+NVIDIA driver Nouveau, however some parts such as rnndb can be applied more generally. The repository 
 contains a slightly modified subset of envytools for header generation from 
-the state / cmdstream / isa rnndb files, so they can be used from the C code (etna), build with
+the state / command stream / ISA rnndb files, so they can be used from the C code (etna), build with
 
     cd envytools
     mkdir build
@@ -231,110 +351,13 @@ Then generate the headers with
 
     rnndb/gen_headers.sh
 
-Building
-=========
-
-The build process is complicated by the existence of many different kernel drivers, with their subtly different interface (different headers,
-different offsets for fields, different management of context, and so on). These values for environment variable `GCABI` are supported out of the box:
-
-- `dove`: Marvell Dove, newer drivers (0.8.0.3184)
-- `dove_old`: Marvell Dove, older drivers (0.8.0.1998, 0.8.0.1123)
-- `arnova`: Android, Arnova 10B G3 tablet (RK2918)
-- `v2`: Various Android, for older chips (RK2918 etc)
-- `imx6`: Various Android, for newer chips (i.MX6 specific)
-- `v4`: Various Android, for newer chips (i.MX6 etc)
-
-If possible get the `gc_*.h` headers for your specific kernel version. If that's not possible, try to find which of the above sets
-of headers is most similar, and adapt that.
-
-gc_abi.h
-----------
-`gc_abi.h` is an extra header that defines the following flags describing the kernel interface to etna, for a certain
-setting of the environment variable `GCABI`:
-
-- `GCABI_CONTEXT_HAS_PHYSICAL`: `struct _gcoCONTEXT` has `physical` and `bytes` fields
-- `GCABI_HAS_MINOR_FEATURES_2`: `struct _gcsHAL_QUERY_CHIP_IDENTITY` has `chipMinorFeatures2` field
-- `GCABI_HAS_MINOR_FEATURES_3`: `struct _gcsHAL_QUERY_CHIP_IDENTITY` has `chipMinorFeatures3` field
-- `GCABI_USER_SIGNAL_HAS_TYPE`: `struct _gcsHAL_USER_SIGNAL` has `signalType` field
-- `GCABI_HAS_CONTEXT`: `struct _gcsHAL_COMMIT` has `contextBuffer` field
-- `GCABI_HAS_STATE_DELTAS`: `struct _gcsHAL_COMMIT` has `delta` field
-
-It would be very useful to have an auto-detection of the Vivante kernel version, to prevent crashes and such from wrong
-interfaces. However, I don't currently know any way to do this. The kernel does check the size of the passed ioctl structure, however
-this guarantees nothing about the field offsets. There is `/proc/driver/gc` that in some cases contains a version number. In
-very new drivers there is an ioctl call `gcvHAL_VERSION` that returns the major, minor and build version.
-
-Android
----------
-
-To build for an Android device, install the Android NDK and define the cross-build environment by setting
-environment variables, for example like this:
-
-    export NDK="/opt/ndk"
-    export TOOLCHAIN="/opt/ndk/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86"
-    export SYSROOT="/opt/ndk/platforms/android-14/arch-arm"
-    export PATH="$PATH:$TOOLCHAIN/bin"
-
-    export GCCPREFIX="arm-linux-androideabi-"
-    export CXXABI="armeabi-v7a"
-    export PLATFORM_CFLAGS="--sysroot=${SYSROOT} -DANDROID -DPIPE_ARCH_LITTLE_ENDIAN"
-    export PLATFORM_CXXFLAGS="--sysroot=${SYSROOT} -DANDROID -DPIPE_ARCH_LITTLE_ENDIAN -I${NDK}/sources/cxx-stl/gnu-libstdc++/4.6/include -I${NDK}/sources/cxx-stl/gnu-libstdc++/4.6/libs/${CXXABI}/include"
-    export PLATFORM_LDFLAGS="--sysroot=${SYSROOT} -L${NDK}/sources/cxx-stl/gnu-libstdc++/4.6/libs/${CXXABI} -lgnustl_static"
-    # Set GC kernel ABI (important!)
-    #export GCABI="v2"
-    #export GCABI="v4"
-    export GCABI="arnova"
-
-To build the egl samples (for command stream interception), you need to copy `libEGL_VIVANTE.so` `libGLESv2_VIVANTE.so` from 
-the device `/system/lib/egl` to `native/lib/egl`. This is not needed if you just want to build the `replay`, `etna` or `fb`
-tests, which do not rely in any way on the userspace blob.
-
-Linux
--------
-
-For non-Android Linux ARM cross compile, create a script like this (example for CuBox) to set up the build environment. 
-Don't forget to also copy the EGL/GLES2/KDR headers from some place and put them in a directory `include` under the location
-where the script is installed, and get the `libEGL.so` and `libGLESv2.so` from the device into `lib`:
-
-    DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-    export GCCPREFIX="arm-linux-gnueabi-"
-    export PLATFORM_CFLAGS="-I${DIR}/include"
-    export PLATFORM_CXXFLAGS="-I${DIR}/include"
-    export PLATFORM_LDFLAGS="-ldl -L${DIR}/lib"
-    export PLATFORM_GL_LIBS="-lEGL -lGLESv2 -L${TOP}/lib/egl -Xlinker --allow-shlib-undefined"
-    # Set GC kernel ABI to dove (important!)
-    #export GCABI="dove"      # 0.8.0.3184
-    export GCABI="dove_old"  # 0.8.0.1998, 0.8.0.1123
-
-If you haven't got the `arm-linux-gnueabi-` bintools, on an Debian/Ubuntu host they can be installed with
-
-    apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
-
-On hardfloat targets you should use `gcc-arm-linux-gnueabihf-` instead.
-
-General
---------
-Run make in `native`, or alternatively in `native/gallium`, `native/etnaviv`, `native/fb`, `native/replay` and/or `native/egl` separately
-(see the README.md in `native` for a description of all the directories contained within).
-
-Compatibility
-================
-
-`Etna_pipe` is currently compatible with at least the following GC chips:
-
-- GC600 (Cubox/dove)
-- GC800 (Rockchip/arnova)
-- GC860 (GCW/v2)
-
-GC2000 support is underway.
-
-Miscellaneous
+Contact
 =============
 There is currently no mailing list for this project, and looking at other GPU reverse engineering projects the mailing lists
 usually see very little traffic, so I won't bother (but you're free to create one).
 
-We usually hang out in `#etnaviv` and `#lima` on `irc.freenode.net`. A related community, focused
-on Freescale i.MX6 sw/hw is in `#imx6-dongle`.
+We usually hang out in `#etnaviv` on `irc.freenode.net`. A related community, focused
+on Freescale i.MX6 sw/hw is in `#imx6-dongle`. Many SoC GPU developers also hang in `#lima`.
 
 Authors
 ========