COMPMID-557 Integrated GLES documentation, updated instructions to link statically the graph library

Change-Id: I04300ad012d20256b06de434a8ff62b908d6c824
Reviewed-on: https://eu-gerrit-1.euhpc.arm.com/113193
Tested-by: Anthony Barbier <anthony.barbier@arm.com>
Reviewed-by: Georgios Pinitas <georgios.pinitas@arm.com>
Reviewed-by: Gian Marco Iodice <gianmarco.iodice@arm.com>

1 files changed, 55 insertions, 18 deletions

diff --git a/docs/00_introduction.dox b/docs/00_introduction.dox
index 4d6fafa980..9740f05ec8 100644
--- a/docs/00_introduction.dox
+++ b/docs/00_introduction.dox
@@ -7,7 +7,7 @@ The Computer Vision and Machine Learning library is a set of functions optimised
 Several builds of the library are available using various configurations:
  - OS: Linux, Android or bare metal.
  - Architecture: armv7a (32bit) or arm64-v8a (64bit)
- - Technology: NEON / OpenCL / NEON and OpenCL
+ - Technology: NEON / OpenCL / GLES_COMPUTE / NEON and OpenCL and GLES_COMPUTE
  - Debug / Asserts / Release: Use a build with asserts enabled to debug your application and enable extra validation. Once you are sure your application works as expected you can switch to a release build of the library for maximum performance.
 
 @section S0_1_contact Contact / Support
@@ -25,7 +25,9 @@ This archive contains:
  - The arm_compute header and source files
  - The latest Khronos OpenCL 1.2 C headers from the <a href="https://www.khronos.org/registry/cl/">Khronos OpenCL registry</a>
  - The latest Khronos cl2.hpp from the <a href="https://www.khronos.org/registry/cl/">Khronos OpenCL registry</a> (API version 2.1 when this document was written)
- - The sources for a stub version of libOpenCL.so to help you build your application.
+ - The latest Khronos OpenGL ES 3.1 C headers from the <a href="https://www.khronos.org/registry/gles/">Khronos OpenGL ES registry</a>
+ - The latest Khronos EGL 1.5 C headers from the <a href="https://www.khronos.org/registry/gles/">Khronos EGL registry</a>
+ - The sources for a stub version of libOpenCL.so, libGLESv1_CM.so, libGLESv2.so and libEGL.so to help you build your application.
  - An examples folder containing a few examples to compile and link against the library.
  - A @ref utils folder containing headers with some boiler plate code used by the examples.
  - This documentation.
@@ -46,6 +48,13 @@ You should have the following file organisation:
 	│   │   │   ├── CPPKernels.h --> Includes all the CPP kernels at once
 	│   │   │   └── kernels --> Folder containing all the CPP kernels
 	│   │   │       └── CPP*Kernel.h
+	│   │   ├── GLES_COMPUTE
+	│   │   │   ├── GCKernelLibrary.h --> Manages all the GLES kernels compilation and caching, provides accessors for the GLES Context.
+	│   │   │   ├── GCKernels.h --> Includes all the GLES kernels at once
+	│   │   │   ├── GLES specialisation of all the generic objects interfaces (IGCTensor, IGCImage, etc.)
+	│   │   │   ├── kernels --> Folder containing all the GLES kernels
+	│   │   │   │   └── GC*Kernel.h
+	│   │   │   └── OpenGLES.h --> Wrapper to configure the Khronos EGL and OpenGL ES C header
 	│   │   ├── NEON
 	│   │   │   ├── kernels --> Folder containing all the NEON kernels
 	│   │   │   │   ├── arm64 --> Folder containing the interfaces for the assembly arm64 NEON kernels
@@ -73,6 +82,12 @@ You should have the following file organisation:
 	│       ├── CPP
 	│       │   ├── CPPKernels.h --> Includes all the CPP functions at once.
 	│       │   └── CPPScheduler.h --> Basic pool of threads to execute CPP/NEON code on several cores in parallel
+	│       ├── GLES_COMPUTE
+	│       │   ├── GLES objects & allocators (GCArray, GCImage, GCTensor, etc.)
+	│       │   ├── functions --> Folder containing all the GLES functions
+	│       │   │   └── GC*.h
+	│       │   ├── GCScheduler.h --> Interface to enqueue GLES kernels and get/set the GLES CommandQueue.
+	│       │   └── GCFunctions.h --> Includes all the GLES functions at once
 	│       ├── NEON
 	│       │   ├── functions --> Folder containing all the NEON functions
 	│       │   │   └── NE*.h
@@ -86,14 +101,10 @@ You should have the following file organisation:
 	│   └── ...
 	├── documentation.xhtml -> documentation/index.xhtml
 	├── examples
-	│   ├── cl_convolution.cpp
-	│   ├── cl_events.cpp
-	│   ├── graph_lenet.cpp
-	│   ├── neoncl_scale_median_gaussian.cpp
-	│   ├── neon_cnn.cpp
-	│   ├── neon_copy_objects.cpp
-	│   ├── neon_convolution.cpp
-	│   └── neon_scale.cpp
+	│   ├── cl_*.cpp --> OpenCL examples
+	│   ├── graph_*.cpp --> Graph examples
+	│   ├── neoncl_*.cpp --> NEON / OpenCL interoperability examples
+	│   └── neon_*.cpp --> NEON examples
 	├── include
 	│   ├── CL
 	│   │   └── Khronos OpenCL C headers and C++ wrapper
@@ -101,14 +112,23 @@ You should have the following file organisation:
 	│   └── libnpy --> Library to load / write npy buffers, available from https://github.com/llohse/libnpy
 	├── opencl-1.2-stubs
 	│   └── opencl_stubs.c
+	├── opengles-3.1
+	│   ├── include
+	│   │   └── Khronos EGL and GLES C headers
+	│   ├── mali_include
+	│   │   └── EGL
+	│   │       └── fbdev_windows.h
+	│   └── stubs
 	├── scripts
 	│   ├── caffe_data_extractor.py --> Basic script to export weights from Caffe to npy files
 	│   └── tensorflow_data_extractor.py --> Basic script to export weights from Tensor Flow to npy files
 	├── src
 	│   ├── core
 	│   │   └── ... (Same structure as headers)
-	│   │       └── CL
-	│   │           └── cl_kernels --> All the OpenCL kernels
+	│   │       ├── CL
+	│   │       │   └── cl_kernels --> All the OpenCL kernels
+	│   │       └── GLES_COMPUTE
+	│   │           └── cs_shaders --> All the OpenGL ES Compute Shaders
 	│   ├── graph
 	│   │   └── ... (Same structure as headers)
 	│   └── runtime
@@ -118,10 +138,12 @@ You should have the following file organisation:
 	├── tests
 	│   ├── All test related files shared between validation and benchmark
 	│   ├── CL --> OpenCL accessors
+	│   ├── GLES_COMPUTE --> GLES accessors
 	│   ├── NEON --> NEON accessors
 	│   ├── benchmark --> Sources for benchmarking
 	│   │   ├── Benchmark specific files
 	│   │   ├── CL --> OpenCL benchmarking tests
+	│   │   ├── GLES_COMPUTE --> GLES benchmarking tests
 	│   │   └── NEON --> NEON benchmarking tests
 	│   ├── datasets
 	│   │   └── Datasets for all the validation / benchmark tests, layer configurations for various networks, etc.
@@ -132,13 +154,14 @@ You should have the following file organisation:
 	│   ├── validation --> Sources for validation
 	│   │   ├── Validation specific files
 	│   │   ├── CL --> OpenCL validation tests
+	│   │   ├── GLES_COMPUTE --> GLES validation tests
 	│   │   ├── CPP --> C++ reference implementations
 	│   │   ├── fixtures
 	│   │   │   └── Fixtures to initialise and run the runtime Functions.
 	│   │   └── NEON --> NEON validation tests
 	│   └── dataset --> Datasets defining common sets of input parameters
 	└── utils --> Boiler plate code used by examples
-	    └── Utils.h
+	    └── Various utilities to print types, load / store assets, etc.
 
 @section S2_versions_changelog Release versions and changelog
 
@@ -405,7 +428,11 @@ To see the build options available simply run ```scons -h```:
 		default: False
 		actual: False
 
-	embed_kernels: Embed OpenCL kernels in library binary (yes|no)
+	gles_compute: Enable OpenGL ES Compute Shader support (yes|no)
+		default: False
+		actual: False
+
+	embed_kernels: Embed OpenCL kernels and OpenGL ES compute shader in library binary (yes|no)
 		default: False
 		actual: False
 
@@ -461,9 +488,9 @@ To see the build options available simply run ```scons -h```:
 
 @b Werror: If you are compiling using the same toolchains as the ones used in this guide then there shouldn't be any warning and therefore you should be able to keep Werror=1. If with a different compiler version the library fails to build because of warnings interpreted as errors then, if you are sure the warnings are not important, you might want to try to build with Werror=0 (But please do report the issue either on Github or by an email to developer@arm.com so that the issue can be addressed).
 
-@b opencl / @b neon: Choose which SIMD technology you want to target. (NEON for ARM Cortex-A CPUs or OpenCL for ARM Mali GPUs)
+@b opencl / @b neon / @b gles_compute: Choose which SIMD technology you want to target. (NEON for ARM Cortex-A CPUs or OpenCL / GLES_COMPUTE for ARM Mali GPUs)
 
-@b embed_kernels: For OpenCL only: set embed_kernels=1 if you want the OpenCL kernels to be built in the library's binaries instead of being read from separate ".cl" files. If embed_kernels is set to 0 then the application can set the path to the folder containing the OpenCL kernel files by calling CLKernelLibrary::init(). By default the path is set to "./cl_kernels".
+@b embed_kernels: For OpenCL / GLES_COMPUTE only: set embed_kernels=1 if you want the OpenCL / GLES_COMPUTE kernels to be built in the library's binaries instead of being read from separate ".cl" / ".cs" files. If embed_kernels is set to 0 then the application can set the path to the folder containing the OpenCL / GLES_COMPUTE kernel files by calling CLKernelLibrary::init() / GCKernelLibrary::init(). By default the path is set to "./cl_kernels" / "./cs_shaders".
 
 @b set_soname: Do you want to build the versioned version of the library ?
 
@@ -508,6 +535,7 @@ For Linux, the library was successfully built and tested using the following Lin
  - gcc-linaro-6.3.1-2017.02-i686_aarch64-linux-gnu
 
 @note If you are building with opencl=1 then scons will expect to find libOpenCL.so either in the current directory or in "build" (See the section below if you need a stub OpenCL library to link against)
+@note If you are building with gles_compute=1 then scons will expect to find libEGL.so / libGLESv1_CM.so / libGLESv2.so either in the current directory or in "build" (See the section below if you need a stub OpenCL library to link against)
 
 To cross-compile the library in debug mode, with NEON only support, for Linux 32bit:
 
@@ -517,6 +545,10 @@ To cross-compile the library in asserts mode, with OpenCL only support, for Linu
 
 	scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=1 embed_kernels=1 os=linux arch=arm64-v8a
 
+To cross-compile the library in asserts mode, with GLES_COMPUTE only support, for Linux 64bit:
+
+	scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=0 gles_compute=1 embed_kernels=1 os=linux arch=arm64-v8a
+
 You can also compile the library natively on an ARM device by using <b>build=native</b>:
 
 	scons Werror=1 -j8 debug=0 neon=1 opencl=0 os=linux arch=arm64-v8a build=native
@@ -653,6 +685,10 @@ To cross-compile the library in asserts mode, with OpenCL only support, for Andr
 
 	scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=1 embed_kernels=1 os=android arch=arm64-v8a
 
+To cross-compile the library in asserts mode, with GLES_COMPUTE only support, for Android 64bit:
+
+	scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=0 gles_compute=1 embed_kernels=1 os=android arch=arm64-v8a
+
 @subsubsection S3_3_2_examples How to manually build the examples ?
 
 The examples get automatically built by scons as part of the build process of the library described above. This section just describes how you can build and link your own application against our library.
@@ -679,11 +715,12 @@ To cross compile the examples with the Graph API, such as graph_lenet.cpp, you n
 (notice the compute library has to be built with both neon and opencl enabled - neon=1 and opencl=1)
 
 	#32 bit:
-	arm-linux-androideabi-clang++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -larm_compute_graph-static -larm_compute-static -larm_compute_core -static-L. -o graph_lenet_arm -static-libstdc++ -pie -lOpenCL -DARM_COMPUTE_CL
+	arm-linux-androideabi-clang++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -Wl,--whole-archive -larm_compute_graph-static -Wl,--no-whole-archive -larm_compute-static -larm_compute_core-static -L. -o graph_lenet_arm -static-libstdc++ -pie -lOpenCL -DARM_COMPUTE_CL
 	#64 bit:
-	aarch64-linux-android-g++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -larm_compute_graph-static -larm_compute-static -larm_compute_core-static -L. -o graph_lenet_aarch64 -static-libstdc++ -pie -lOpenCL -DARM_COMPUTE_CL
+	aarch64-linux-android-g++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -Wl,--whole-archive -larm_compute_graph-static -Wl,--no-whole-archive -larm_compute-static -larm_compute_core-static -L. -o graph_lenet_aarch64 -static-libstdc++ -pie -lOpenCL -DARM_COMPUTE_CL
 
 @note Due to some issues in older versions of the Mali OpenCL DDK (<= r13p0), we recommend to link arm_compute statically on Android.
+@note When linked statically the arm_compute_graph library currently needs the --whole-archive linker flag in order to work properly
 
 Then you need to do is upload the executable and the shared library to the device using ADB: