Gitiles
Code Review Sign In
review.mlplatform.org / ml / ComputeLibrary / 20dbb827a30c8529bc4f2c076dcaed3d48514456 / . / docs / 00_introduction.dox
blob: 9740f05ec8e19ee9829991837418d80831d1c7e2 [file] [log] [blame]
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]1/** @mainpage Introduction
2
3@tableofcontents
4
5The Computer Vision and Machine Learning library is a set of functions optimised for both ARM CPUs and GPUs using SIMD technologies.
6
7Several builds of the library are available using various configurations:
8 - OS: Linux, Android or bare metal.
9 - Architecture: armv7a (32bit) or arm64-v8a (64bit)
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]10 - Technology: NEON / OpenCL / GLES_COMPUTE / NEON and OpenCL and GLES_COMPUTE
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]11 - 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.
12
13@section S0_1_contact Contact / Support
14
15Please email developer@arm.com
16
17In order to facilitate the work of the support team please provide the build information of the library you are using. To get the version of the library you are using simply run:
18
19 $ strings android-armv7a-cl-asserts/libarm_compute.so | grep arm_compute_version
20 arm_compute_version=v16.12 Build options: {'embed_kernels': '1', 'opencl': '1', 'arch': 'armv7a', 'neon': '0', 'asserts': '1', 'debug': '0', 'os': 'android', 'Werror': '1'} Git hash=f51a545d4ea12a9059fe4e598a092f1fd06dc858
21
22@section S1_file_organisation File organisation
23
24This archive contains:
25 - The arm_compute header and source files
26 - The latest Khronos OpenCL 1.2 C headers from the <a href="https://www.khronos.org/registry/cl/">Khronos OpenCL registry</a>
27 - 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)
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]28 - The latest Khronos OpenGL ES 3.1 C headers from the <a href="https://www.khronos.org/registry/gles/">Khronos OpenGL ES registry</a>
29 - The latest Khronos EGL 1.5 C headers from the <a href="https://www.khronos.org/registry/gles/">Khronos EGL registry</a>
30 - The sources for a stub version of libOpenCL.so, libGLESv1_CM.so, libGLESv2.so and libEGL.so to help you build your application.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]31 - An examples folder containing a few examples to compile and link against the library.
32 - A @ref utils folder containing headers with some boiler plate code used by the examples.
33 - This documentation.
34
35You should have the following file organisation:
36
37 .
38 ├── arm_compute --> All the arm_compute headers
39 │   ├── core
40 │   │   ├── CL
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]41 │   │   │   ├── CLKernelLibrary.h --> Manages all the OpenCL kernels compilation and caching, provides accessors for the OpenCL Context.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]42 │   │   │   ├── CLKernels.h --> Includes all the OpenCL kernels at once
43 │   │   │   ├── CL specialisation of all the generic objects interfaces (ICLTensor, ICLImage, etc.)
44 │   │   │   ├── kernels --> Folder containing all the OpenCL kernels
45 │   │   │   │   └── CL*Kernel.h
46 │   │   │   └── OpenCL.h --> Wrapper to configure the Khronos OpenCL C++ header
47 │   │ ├── CPP
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]48 │   │   │   ├── CPPKernels.h --> Includes all the CPP kernels at once
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]49 │   │ │   └── kernels --> Folder containing all the CPP kernels
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]50 │   │   │      └── CPP*Kernel.h
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]51 │   │   ├── GLES_COMPUTE
52 │   │   │   ├── GCKernelLibrary.h --> Manages all the GLES kernels compilation and caching, provides accessors for the GLES Context.
53 │   │   │   ├── GCKernels.h --> Includes all the GLES kernels at once
54 │   │   │   ├── GLES specialisation of all the generic objects interfaces (IGCTensor, IGCImage, etc.)
55 │   │   │   ├── kernels --> Folder containing all the GLES kernels
56 │   │   │   │   └── GC*Kernel.h
57 │   │   │   └── OpenGLES.h --> Wrapper to configure the Khronos EGL and OpenGL ES C header
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]58 │   │   ├── NEON
59 │   │   │   ├── kernels --> Folder containing all the NEON kernels
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]60 │   │   │   │ ├── arm64 --> Folder containing the interfaces for the assembly arm64 NEON kernels
61 │   │   │   │ ├── arm32 --> Folder containing the interfaces for the assembly arm32 NEON kernels
62 │   │   │   │ ├── assembly --> Folder containing the NEON assembly routines.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]63 │   │   │   │   └── NE*Kernel.h
64 │   │   │   └── NEKernels.h --> Includes all the NEON kernels at once
65 │   │   ├── All common basic types (Types.h, Window, Coordinates, Iterator, etc.)
66 │   │   ├── All generic objects interfaces (ITensor, IImage, etc.)
67 │   │   └── Objects metadata classes (ImageInfo, TensorInfo, MultiImageInfo)
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]68 │   ├── graph
69 │   │   ├── CL --> OpenCL specific operations
70 │   │   │   └── CLMap.h / CLUnmap.h
71 │   │   ├── nodes
72 │   │   │   └── The various nodes supported by the graph API
73 │   │   ├── Nodes.h --> Includes all the Graph nodes at once.
74 │   │   └── Graph objects ( INode, ITensorAccessor, Graph, etc.)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]75 │   └── runtime
76 │   ├── CL
77 │   │   ├── CL objects & allocators (CLArray, CLImage, CLTensor, etc.)
78 │   │   ├── functions --> Folder containing all the OpenCL functions
79 │   │   │   └── CL*.h
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]80 │   │   ├── CLScheduler.h --> Interface to enqueue OpenCL kernels and get/set the OpenCL CommandQueue and ICLTuner.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]81 │   │   └── CLFunctions.h --> Includes all the OpenCL functions at once
82 │   ├── CPP
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]83 │      │   ├── CPPKernels.h --> Includes all the CPP functions at once.
84 │   │   └── CPPScheduler.h --> Basic pool of threads to execute CPP/NEON code on several cores in parallel
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]85 │   ├── GLES_COMPUTE
86 │   │   ├── GLES objects & allocators (GCArray, GCImage, GCTensor, etc.)
87 │   │   ├── functions --> Folder containing all the GLES functions
88 │   │   │   └── GC*.h
89 │   │   ├── GCScheduler.h --> Interface to enqueue GLES kernels and get/set the GLES CommandQueue.
90 │   │   └── GCFunctions.h --> Includes all the GLES functions at once
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]91 │   ├── NEON
92 │   │ ├── functions --> Folder containing all the NEON functions
93 │   │ │   └── NE*.h
94 │   │ └── NEFunctions.h --> Includes all the NEON functions at once
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]95 │   ├── OMP
96 │   │   └── OMPScheduler.h --> OpenMP scheduler (Alternative to the CPPScheduler)
97 │ ├── Memory manager files (LifetimeManager, PoolManager, etc.)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]98 │   └── Basic implementations of the generic object interfaces (Array, Image, Tensor, etc.)
99 ├── documentation
100 │   ├── index.xhtml
101 │   └── ...
102 ├── documentation.xhtml -> documentation/index.xhtml
103 ├── examples
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]104 │   ├── cl_*.cpp --> OpenCL examples
105 │   ├── graph_*.cpp --> Graph examples
106 │   ├── neoncl_*.cpp --> NEON / OpenCL interoperability examples
107 │   └── neon_*.cpp --> NEON examples
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]108 ├── include
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]109 │   ├── CL
110 │   │ └── Khronos OpenCL C headers and C++ wrapper
111 │   ├── half --> FP16 library available from http://half.sourceforge.net
112 │  └── libnpy --> Library to load / write npy buffers, available from https://github.com/llohse/libnpy
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]113 ├── opencl-1.2-stubs
114 │ └── opencl_stubs.c
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]115 ├── opengles-3.1
116 │ ├── include
117 │   │ └── Khronos EGL and GLES C headers
118 │ ├── mali_include
119 │   │ └── EGL
120 │   │ └── fbdev_windows.h
121 │   └── stubs
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]122 ├── scripts
123 │   ├── caffe_data_extractor.py --> Basic script to export weights from Caffe to npy files
124 │   └── tensorflow_data_extractor.py --> Basic script to export weights from Tensor Flow to npy files
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]125 ├── src
126 │   ├── core
127 │ │ └── ... (Same structure as headers)
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]128 │   │ ├── CL
129 │   │ │ └── cl_kernels --> All the OpenCL kernels
130 │   │ └── GLES_COMPUTE
131 │   │ └── cs_shaders --> All the OpenGL ES Compute Shaders
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]132 │   ├── graph
133 │ │ └── ... (Same structure as headers)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]134 │ └── runtime
135 │ └── ... (Same structure as headers)
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]136 ├── support
137 │ └── Various headers to work around toolchains / platform issues.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]138 ├── tests
139 │   ├── All test related files shared between validation and benchmark
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]140 │   ├── CL --> OpenCL accessors
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]141 │   ├── GLES_COMPUTE --> GLES accessors
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]142 │   ├── NEON --> NEON accessors
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]143 │   ├── benchmark --> Sources for benchmarking
144 │ │ ├── Benchmark specific files
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]145 │ │ ├── CL --> OpenCL benchmarking tests
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]146 │ │ ├── GLES_COMPUTE --> GLES benchmarking tests
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]147 │ │ └── NEON --> NEON benchmarking tests
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]148 │   ├── datasets
149 │ │ └── Datasets for all the validation / benchmark tests, layer configurations for various networks, etc.
150 │   ├── framework
151 │ │ └── Boiler plate code for both validation and benchmark test suites (Command line parsers, instruments, output loggers, etc.)
152 │   ├── networks
153 │ │ └── Examples of how to instantiate networks.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]154 │   ├── validation --> Sources for validation
155 │ │ ├── Validation specific files
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]156 │ │ ├── CL --> OpenCL validation tests
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]157 │ │ ├── GLES_COMPUTE --> GLES validation tests
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]158 │ │ ├── CPP --> C++ reference implementations
159 │   │ ├── fixtures
160 │ │ │ └── Fixtures to initialise and run the runtime Functions.
161 │ │ └── NEON --> NEON validation tests
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]162 │   └── dataset --> Datasets defining common sets of input parameters
163 └── utils --> Boiler plate code used by examples
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]164 └── Various utilities to print types, load / store assets, etc.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]165
166@section S2_versions_changelog Release versions and changelog
167
168@subsection S2_1_versions Release versions
169
170All releases are numbered vYY.MM Where YY are the last two digits of the year, and MM the month number.
171If there is more than one release in a month then an extra sequential number is appended at the end:
172
173 v17.03 (First release of March 2017)
174 v17.03.1 (Second release of March 2017)
175 v17.04 (First release of April 2017)
176
177@note We're aiming at releasing one major public release with new features per quarter. All releases in between will only contain bug fixes.
178
179@subsection S2_2_changelog Changelog
180
Gian Marcoff850932017-12-11 12:37:17 +0000[diff] [blame]181v17.12 Public major release
182 - Most machine learning functions on OpenCL support the new data type QASYMM8
183 - Introduced logging interface
184 - Introduced opencl timer
185 - Reworked GEMMLowp interface
186 - Added new NEON assembly kernels for GEMMLowp, SGEMM and HGEMM
187 - Added validation method for most Machine Learning kernels / functions
188 - Added new graph examples such as googlenet, mobilenet, squeezenet, vgg16 and vgg19
189 - Added sgemm example for OpenCL
190 - Added absolute difference example for GLES compute
191 - Added new tests and benchmarks in validation and benchmark frameworks
192 - Added new kernels / functions for GLES compute
193
194 - New OpenGL ES kernels / functions
195 - @ref arm_compute::GCAbsoluteDifferenceKernel / @ref arm_compute::GCAbsoluteDifference
196 - @ref arm_compute::GCActivationLayerKernel / @ref arm_compute::GCActivationLayer
197 - @ref arm_compute::GCBatchNormalizationLayerKernel / @ref arm_compute::GCBatchNormalizationLayer
198 - @ref arm_compute::GCCol2ImKernel
199 - @ref arm_compute::GCDepthConcatenateLayerKernel / @ref arm_compute::GCDepthConcatenateLayer
200 - @ref arm_compute::GCDirectConvolutionLayerKernel / @ref arm_compute::GCDirectConvolutionLayer
201 - @ref arm_compute::GCDropoutLayerKernel / @ref arm_compute::GCDropoutLayer
202 - @ref arm_compute::GCFillBorderKernel / @ref arm_compute::GCFillBorder
203 - @ref arm_compute::GCGEMMInterleave4x4Kernel / @ref arm_compute::GCGEMMInterleave4x4
204 - @ref arm_compute::GCGEMMMatrixAccumulateBiasesKernel / @ref arm_compute::GCGEMMMatrixAdditionKernel / @ref arm_compute::GCGEMMMatrixMultiplyKernel / @ref arm_compute::GCGEMM
205 - @ref arm_compute::GCGEMMTranspose1xWKernel / @ref arm_compute::GCGEMMTranspose1xW
206 - @ref arm_compute::GCIm2ColKernel
207 - @ref arm_compute::GCNormalizationLayerKernel / @ref arm_compute::GCNormalizationLayer
208 - @ref arm_compute::GCPixelWiseMultiplicationKernel / @ref arm_compute::GCPixelWiseMultiplication
209 - @ref arm_compute::GCPoolingLayerKernel / @ref arm_compute::GCPoolingLayer
210 - @ref arm_compute::GCLogits1DMaxKernel / @ref arm_compute::GCLogits1DShiftExpSumKernel / @ref arm_compute::GCLogits1DNormKernel / @ref arm_compute::GCSoftmaxLayer
211 - @ref arm_compute::GCTransposeKernel / @ref arm_compute::GCTranspose
212
213 - New NEON kernels / functions
214 - @ref arm_compute::NEGEMMLowpAArch64A53Kernel / @ref arm_compute::NEGEMMLowpAArch64Kernel / @ref arm_compute::NEGEMMLowpAArch64V8P4Kernel / arm_compute::NEGEMMInterleavedBlockedKernel / @ref arm_compute::NEGEMMLowpAssemblyMatrixMultiplyCore
215 - @ref arm_compute::NEHGEMMAArch64FP16Kernel
216 - @ref arm_compute::NEDepthwiseConvolutionLayer3x3Kernel / @ref arm_compute::NEDepthwiseIm2ColKernel / @ref arm_compute::NEGEMMMatrixVectorMultiplyKernel / @ref arm_compute::NEDepthwiseVectorToTensorKernel / @ref arm_compute::NEDepthwiseConvolutionLayer
217 - @ref arm_compute::NEGEMMLowpOffsetContributionKernel / @ref arm_compute::NEGEMMLowpMatrixAReductionKernel / @ref arm_compute::NEGEMMLowpMatrixBReductionKernel / @ref arm_compute::NEGEMMLowpMatrixMultiplyCore
218 - @ref arm_compute::NEGEMMLowpQuantizeDownInt32ToUint8ScaleByFixedPointKernel / @ref arm_compute::NEGEMMLowpQuantizeDownInt32ToUint8ScaleByFixedPoint
219 - @ref arm_compute::NEGEMMLowpQuantizeDownInt32ToUint8ScaleKernel / @ref arm_compute::NEGEMMLowpQuantizeDownInt32ToUint8Scale
220 - @ref arm_compute::NEWinogradLayerKernel / @ref arm_compute::NEWinogradLayer
221
222 - New OpenCL kernels / functions
223 - @ref arm_compute::CLGEMMLowpOffsetContributionKernel / @ref arm_compute::CLGEMMLowpMatrixAReductionKernel / @ref arm_compute::CLGEMMLowpMatrixBReductionKernel / @ref arm_compute::CLGEMMLowpMatrixMultiplyCore
224 - @ref arm_compute::CLGEMMLowpQuantizeDownInt32ToUint8ScaleByFixedPointKernel / @ref arm_compute::CLGEMMLowpQuantizeDownInt32ToUint8ScaleByFixedPoint
225 - @ref arm_compute::CLGEMMLowpQuantizeDownInt32ToUint8ScaleKernel / @ref arm_compute::CLGEMMLowpQuantizeDownInt32ToUint8Scale
226
227 - New graph nodes for NEON and OpenCL
228 - @ref arm_compute::graph::BranchLayer
229 - @ref arm_compute::graph::DepthConvertLayer
230 - @ref arm_compute::graph::DepthwiseConvolutionLayer
231 - @ref arm_compute::graph::DequantizationLayer
232 - @ref arm_compute::graph::FlattenLayer
233 - @ref arm_compute::graph::QuantizationLayer
234 - @ref arm_compute::graph::ReshapeLayer
235
Anthony Barbier3c5b4ff2017-10-12 13:20:52 +0100[diff] [blame]236v17.10 Public maintenance release
237 - Bug fixes:
238 - Check the maximum local workgroup size supported by OpenCL devices
239 - Minor documentation updates (Fixed instructions to build the examples)
240 - Introduced a arm_compute::graph::GraphContext
241 - Added a few new Graph nodes, support for branches and grouping.
242 - Automatically enable cl_printf in debug builds
243 - Fixed bare metal builds for armv7a
244 - Added AlexNet and cartoon effect examples
245 - Fixed library builds: libraries are no longer built as supersets of each other.(It means application using the Runtime part of the library now need to link against both libarm_compute_core and libarm_compute)
246
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]247v17.09 Public major release
248 - Experimental Graph support: initial implementation of a simple stream API to easily chain machine learning layers.
249 - Memory Manager (@ref arm_compute::BlobLifetimeManager, @ref arm_compute::BlobMemoryPool, @ref arm_compute::ILifetimeManager, @ref arm_compute::IMemoryGroup, @ref arm_compute::IMemoryManager, @ref arm_compute::IMemoryPool, @ref arm_compute::IPoolManager, @ref arm_compute::MemoryManagerOnDemand, @ref arm_compute::PoolManager)
250 - New validation and benchmark frameworks (Boost and Google frameworks replaced by homemade framework).
251 - Most machine learning functions support both fixed point 8 and 16 bit (QS8, QS16) for both NEON and OpenCL.
252 - New NEON kernels / functions:
253 - @ref arm_compute::NEGEMMAssemblyBaseKernel @ref arm_compute::NEGEMMAArch64Kernel
254 - @ref arm_compute::NEDequantizationLayerKernel / @ref arm_compute::NEDequantizationLayer
255 - @ref arm_compute::NEFloorKernel / @ref arm_compute::NEFloor
Giorgio Arena04a8f8c2017-11-23 11:45:24 +0000[diff] [blame]256 - @ref arm_compute::NEL2NormalizeLayerKernel / @ref arm_compute::NEL2NormalizeLayer
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]257 - @ref arm_compute::NEQuantizationLayerKernel @ref arm_compute::NEMinMaxLayerKernel / @ref arm_compute::NEQuantizationLayer
258 - @ref arm_compute::NEROIPoolingLayerKernel / @ref arm_compute::NEROIPoolingLayer
259 - @ref arm_compute::NEReductionOperationKernel / @ref arm_compute::NEReductionOperation
260 - @ref arm_compute::NEReshapeLayerKernel / @ref arm_compute::NEReshapeLayer
261
262 - New OpenCL kernels / functions:
Giorgio Arena04a8f8c2017-11-23 11:45:24 +0000[diff] [blame]263 - @ref arm_compute::CLDepthwiseConvolutionLayer3x3Kernel @ref arm_compute::CLDepthwiseIm2ColKernel @ref arm_compute::CLDepthwiseVectorToTensorKernel @ref arm_compute::CLDepthwiseWeightsReshapeKernel / @ref arm_compute::CLDepthwiseConvolutionLayer3x3 @ref arm_compute::CLDepthwiseConvolutionLayer @ref arm_compute::CLDepthwiseSeparableConvolutionLayer
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]264 - @ref arm_compute::CLDequantizationLayerKernel / @ref arm_compute::CLDequantizationLayer
265 - @ref arm_compute::CLDirectConvolutionLayerKernel / @ref arm_compute::CLDirectConvolutionLayer
266 - @ref arm_compute::CLFlattenLayer
267 - @ref arm_compute::CLFloorKernel / @ref arm_compute::CLFloor
268 - @ref arm_compute::CLGEMMTranspose1xW
269 - @ref arm_compute::CLGEMMMatrixVectorMultiplyKernel
Giorgio Arena04a8f8c2017-11-23 11:45:24 +0000[diff] [blame]270 - @ref arm_compute::CLL2NormalizeLayerKernel / @ref arm_compute::CLL2NormalizeLayer
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]271 - @ref arm_compute::CLQuantizationLayerKernel @ref arm_compute::CLMinMaxLayerKernel / @ref arm_compute::CLQuantizationLayer
272 - @ref arm_compute::CLROIPoolingLayerKernel / @ref arm_compute::CLROIPoolingLayer
273 - @ref arm_compute::CLReductionOperationKernel / @ref arm_compute::CLReductionOperation
274 - @ref arm_compute::CLReshapeLayerKernel / @ref arm_compute::CLReshapeLayer
275
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]276v17.06 Public major release
277 - Various bug fixes
278 - Added support for fixed point 8 bit (QS8) to the various NEON machine learning kernels.
279 - Added unit tests and benchmarks (AlexNet, LeNet)
280 - Added support for sub tensors.
281 - Added infrastructure to provide GPU specific optimisation for some OpenCL kernels.
282 - Added @ref arm_compute::OMPScheduler (OpenMP) scheduler for NEON
283 - Added @ref arm_compute::SingleThreadScheduler scheduler for NEON (For bare metal)
284 - User can specify his own scheduler by implementing the @ref arm_compute::IScheduler interface.
285 - New OpenCL kernels / functions:
286 - @ref arm_compute::CLBatchNormalizationLayerKernel / @ref arm_compute::CLBatchNormalizationLayer
Giorgio Arena04a8f8c2017-11-23 11:45:24 +0000[diff] [blame]287 - @ref arm_compute::CLDepthConcatenateLayerKernel / @ref arm_compute::CLDepthConcatenateLayer
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]288 - @ref arm_compute::CLHOGOrientationBinningKernel @ref arm_compute::CLHOGBlockNormalizationKernel, @ref arm_compute::CLHOGDetectorKernel / @ref arm_compute::CLHOGDescriptor @ref arm_compute::CLHOGDetector @ref arm_compute::CLHOGGradient @ref arm_compute::CLHOGMultiDetection
289 - @ref arm_compute::CLLocallyConnectedMatrixMultiplyKernel / @ref arm_compute::CLLocallyConnectedLayer
290 - @ref arm_compute::CLWeightsReshapeKernel / @ref arm_compute::CLConvolutionLayerReshapeWeights
291 - New C++ kernels:
292 - @ref arm_compute::CPPDetectionWindowNonMaximaSuppressionKernel
293 - New NEON kernels / functions:
294 - @ref arm_compute::NEBatchNormalizationLayerKernel / @ref arm_compute::NEBatchNormalizationLayer
Giorgio Arena04a8f8c2017-11-23 11:45:24 +0000[diff] [blame]295 - @ref arm_compute::NEDepthConcatenateLayerKernel / @ref arm_compute::NEDepthConcatenateLayer
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]296 - @ref arm_compute::NEDirectConvolutionLayerKernel / @ref arm_compute::NEDirectConvolutionLayer
297 - @ref arm_compute::NELocallyConnectedMatrixMultiplyKernel / @ref arm_compute::NELocallyConnectedLayer
298 - @ref arm_compute::NEWeightsReshapeKernel / @ref arm_compute::NEConvolutionLayerReshapeWeights
299
300v17.05 Public bug fixes release
301 - Various bug fixes
302 - Remaining of the functions ported to use accurate padding.
303 - Library does not link against OpenCL anymore (It uses dlopen / dlsym at runtime instead to determine whether or not OpenCL is available).
304 - Added "free" method to allocator.
305 - Minimum version of g++ required for armv7 Linux changed from 4.8 to 4.9
306
307v17.04 Public bug fixes release
308
309 The following functions have been ported to use the new accurate padding:
310 - @ref arm_compute::CLColorConvertKernel
311 - @ref arm_compute::CLEdgeNonMaxSuppressionKernel
312 - @ref arm_compute::CLEdgeTraceKernel
313 - @ref arm_compute::CLGaussianPyramidHorKernel
314 - @ref arm_compute::CLGaussianPyramidVertKernel
315 - @ref arm_compute::CLGradientKernel
316 - @ref arm_compute::NEChannelCombineKernel
317 - @ref arm_compute::NEFillArrayKernel
318 - @ref arm_compute::NEGaussianPyramidHorKernel
319 - @ref arm_compute::NEGaussianPyramidVertKernel
320 - @ref arm_compute::NEHarrisScoreFP16Kernel
321 - @ref arm_compute::NEHarrisScoreKernel
322 - @ref arm_compute::NEHOGDetectorKernel
323 - @ref arm_compute::NELogits1DMaxKernel
324 - @ref arm_compute::NELogits1DShiftExpSumKernel
325 - @ref arm_compute::NELogits1DNormKernel
326 - @ref arm_compute::NENonMaximaSuppression3x3FP16Kernel
327 - @ref arm_compute::NENonMaximaSuppression3x3Kernel
328
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]329v17.03.1 First Major public release of the sources
330 - Renamed the library to arm_compute
331 - New CPP target introduced for C++ kernels shared between NEON and CL functions.
332 - New padding calculation interface introduced and ported most kernels / functions to use it.
333 - New OpenCL kernels / functions:
Gian Marco05288a22017-11-21 10:57:50 +0000[diff] [blame]334 - @ref arm_compute::CLGEMMLowpMatrixMultiplyKernel / arm_compute::CLGEMMLowp
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]335 - New NEON kernels / functions:
336 - @ref arm_compute::NENormalizationLayerKernel / @ref arm_compute::NENormalizationLayer
337 - @ref arm_compute::NETransposeKernel / @ref arm_compute::NETranspose
338 - @ref arm_compute::NELogits1DMaxKernel, @ref arm_compute::NELogits1DShiftExpSumKernel, @ref arm_compute::NELogits1DNormKernel / @ref arm_compute::NESoftmaxLayer
339 - @ref arm_compute::NEIm2ColKernel, @ref arm_compute::NECol2ImKernel, arm_compute::NEConvolutionLayerWeightsReshapeKernel / @ref arm_compute::NEConvolutionLayer
340 - @ref arm_compute::NEGEMMMatrixAccumulateBiasesKernel / @ref arm_compute::NEFullyConnectedLayer
Gian Marcoe75a02b2017-11-08 12:24:09 +0000[diff] [blame]341 - @ref arm_compute::NEGEMMLowpMatrixMultiplyKernel / arm_compute::NEGEMMLowp
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]342
343v17.03 Sources preview
344 - New OpenCL kernels / functions:
345 - @ref arm_compute::CLGradientKernel, @ref arm_compute::CLEdgeNonMaxSuppressionKernel, @ref arm_compute::CLEdgeTraceKernel / @ref arm_compute::CLCannyEdge
346 - GEMM refactoring + FP16 support: @ref arm_compute::CLGEMMInterleave4x4Kernel, @ref arm_compute::CLGEMMTranspose1xWKernel, @ref arm_compute::CLGEMMMatrixMultiplyKernel, @ref arm_compute::CLGEMMMatrixAdditionKernel / @ref arm_compute::CLGEMM
347 - @ref arm_compute::CLGEMMMatrixAccumulateBiasesKernel / @ref arm_compute::CLFullyConnectedLayer
348 - @ref arm_compute::CLTransposeKernel / @ref arm_compute::CLTranspose
349 - @ref arm_compute::CLLKTrackerInitKernel, @ref arm_compute::CLLKTrackerStage0Kernel, @ref arm_compute::CLLKTrackerStage1Kernel, @ref arm_compute::CLLKTrackerFinalizeKernel / @ref arm_compute::CLOpticalFlow
350 - @ref arm_compute::CLNormalizationLayerKernel / @ref arm_compute::CLNormalizationLayer
351 - @ref arm_compute::CLLaplacianPyramid, @ref arm_compute::CLLaplacianReconstruct
352 - New NEON kernels / functions:
353 - @ref arm_compute::NEActivationLayerKernel / @ref arm_compute::NEActivationLayer
354 - GEMM refactoring + FP16 support (Requires armv8.2 CPU): @ref arm_compute::NEGEMMInterleave4x4Kernel, @ref arm_compute::NEGEMMTranspose1xWKernel, @ref arm_compute::NEGEMMMatrixMultiplyKernel, @ref arm_compute::NEGEMMMatrixAdditionKernel / @ref arm_compute::NEGEMM
355 - @ref arm_compute::NEPoolingLayerKernel / @ref arm_compute::NEPoolingLayer
356
357v17.02.1 Sources preview
358 - New OpenCL kernels / functions:
359 - @ref arm_compute::CLLogits1DMaxKernel, @ref arm_compute::CLLogits1DShiftExpSumKernel, @ref arm_compute::CLLogits1DNormKernel / @ref arm_compute::CLSoftmaxLayer
360 - @ref arm_compute::CLPoolingLayerKernel / @ref arm_compute::CLPoolingLayer
Gian Marco Iodice5cb4c422017-06-23 10:38:25 +0100[diff] [blame]361 - @ref arm_compute::CLIm2ColKernel, @ref arm_compute::CLCol2ImKernel, arm_compute::CLConvolutionLayerWeightsReshapeKernel / @ref arm_compute::CLConvolutionLayer
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]362 - @ref arm_compute::CLRemapKernel / @ref arm_compute::CLRemap
363 - @ref arm_compute::CLGaussianPyramidHorKernel, @ref arm_compute::CLGaussianPyramidVertKernel / @ref arm_compute::CLGaussianPyramid, @ref arm_compute::CLGaussianPyramidHalf, @ref arm_compute::CLGaussianPyramidOrb
364 - @ref arm_compute::CLMinMaxKernel, @ref arm_compute::CLMinMaxLocationKernel / @ref arm_compute::CLMinMaxLocation
365 - @ref arm_compute::CLNonLinearFilterKernel / @ref arm_compute::CLNonLinearFilter
366 - New NEON FP16 kernels (Requires armv8.2 CPU)
367 - @ref arm_compute::NEAccumulateWeightedFP16Kernel
368 - @ref arm_compute::NEBox3x3FP16Kernel
369 - @ref arm_compute::NENonMaximaSuppression3x3FP16Kernel
370
371v17.02 Sources preview
372 - New OpenCL kernels / functions:
373 - @ref arm_compute::CLActivationLayerKernel / @ref arm_compute::CLActivationLayer
374 - @ref arm_compute::CLChannelCombineKernel / @ref arm_compute::CLChannelCombine
375 - @ref arm_compute::CLDerivativeKernel / @ref arm_compute::CLChannelExtract
376 - @ref arm_compute::CLFastCornersKernel / @ref arm_compute::CLFastCorners
377 - @ref arm_compute::CLMeanStdDevKernel / @ref arm_compute::CLMeanStdDev
378 - New NEON kernels / functions:
379 - HOG / SVM: @ref arm_compute::NEHOGOrientationBinningKernel, @ref arm_compute::NEHOGBlockNormalizationKernel, @ref arm_compute::NEHOGDetectorKernel, arm_compute::NEHOGNonMaximaSuppressionKernel / @ref arm_compute::NEHOGDescriptor, @ref arm_compute::NEHOGDetector, @ref arm_compute::NEHOGGradient, @ref arm_compute::NEHOGMultiDetection
380 - @ref arm_compute::NENonLinearFilterKernel / @ref arm_compute::NENonLinearFilter
381 - Introduced a CLScheduler to manage the default context and command queue used by the runtime library and create synchronisation events.
382 - Switched all the kernels / functions to use tensors instead of images.
383 - Updated documentation to include instructions to build the library from sources.
384
385v16.12 Binary preview release
386 - Original release
387
388@section S3_how_to_build How to build the library and the examples
389
390@subsection S3_1_build_options Build options
391
392scons 2.3 or above is required to build the library.
393To see the build options available simply run ```scons -h```:
394
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]395 debug: Debug (yes|no)
396 default: False
397 actual: False
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]398
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]399 asserts: Enable asserts (this flag is forced to 1 for debug=1) (yes|no)
400 default: False
401 actual: False
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]402
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]403 arch: Target Architecture (armv7a|arm64-v8a|arm64-v8.2-a|x86_32|x86_64)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]404 default: armv7a
405 actual: armv7a
406
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]407 os: Target OS (linux|android|bare_metal)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]408 default: linux
409 actual: linux
410
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]411 build: Build type (native|cross_compile)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]412 default: cross_compile
413 actual: cross_compile
414
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]415 examples: Build example programs (yes|no)
416 default: True
417 actual: True
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]418
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]419 Werror: Enable/disable the -Werror compilation flag (yes|no)
420 default: True
421 actual: True
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]422
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]423 opencl: Enable OpenCL support (yes|no)
424 default: True
425 actual: True
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]426
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]427 neon: Enable Neon support (yes|no)
428 default: False
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]429 actual: False
430
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]431 gles_compute: Enable OpenGL ES Compute Shader support (yes|no)
432 default: False
433 actual: False
434
435 embed_kernels: Embed OpenCL kernels and OpenGL ES compute shader in library binary (yes|no)
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]436 default: False
437 actual: False
438
439 set_soname: Set the library's soname and shlibversion (requires SCons 2.4 or above) (yes|no)
440 default: False
441 actual: False
442
443 openmp: Enable OpenMP backend (yes|no)
444 default: False
445 actual: False
446
447 cppthreads: Enable C++11 threads backend (yes|no)
448 default: True
449 actual: True
450
451 build_dir: Specify sub-folder for the build ( /path/to/build_dir )
452 default: .
453 actual: .
454
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]455 extra_cxx_flags: Extra CXX flags to be appended to the build command
456 default:
457 actual:
458
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]459 pmu: Enable PMU counters (yes|no)
460 default: False
461 actual: False
462
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]463 mali: Enable Mali hardware counters (yes|no)
464 default: False
465 actual: False
466
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]467 validation_tests: Build validation test programs (yes|no)
468 default: False
469 actual: False
470
471 benchmark_tests: Build benchmark test programs (yes|no)
472 default: False
473 actual: False
474
475@b debug / @b asserts:
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]476 - With debug=1 asserts are enabled, and the library is built with symbols and no optimisations enabled.
477 - With debug=0 and asserts=1: Optimisations are enabled and symbols are removed, however all the asserts are still present (This is about 20% slower than the release build)
478 - With debug=0 and asserts=0: All optimisations are enable and no validation is performed, if the application misuses the library it is likely to result in a crash. (Only use this mode once you are sure your application is working as expected).
479
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]480@b arch: The x86_32 and x86_64 targets can only be used with neon=0 and opencl=1.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]481
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]482@b os: Choose the operating system you are targeting: Linux, Android or bare metal.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]483@note bare metal can only be used for NEON (not OpenCL), only static libraries get built and NEON's multi-threading support is disabled.
484
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]485@b build: you can either build directly on your device (native) or cross compile from your desktop machine (cross-compile). In both cases make sure the compiler is available in your path.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]486
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]487@note If you want to natively compile for 32bit on a 64bit ARM device running a 64bit OS then you will have to use cross-compile too.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]488
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]489@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).
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]490
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]491@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)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]492
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]493@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".
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]494
495@b set_soname: Do you want to build the versioned version of the library ?
496
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]497If enabled the library will contain a SONAME and SHLIBVERSION and some symlinks will automatically be created between the objects.
498Example:
499 libarm_compute_core.so -> libarm_compute_core.so.1.0.0
500 libarm_compute_core.so.1 -> libarm_compute_core.so.1.0.0
501 libarm_compute_core.so.1.0.0
502
503@note This options is disabled by default as it requires SCons version 2.4 or above.
504
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]505@b extra_cxx_flags: Custom CXX flags which will be appended to the end of the build command.
506
507@b build_dir: Build the library in a subfolder of the "build" folder. (Allows to build several configurations in parallel).
508
509@b examples: Build or not the examples
510
511@b validation_tests: Enable the build of the validation suite.
512
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]513@b benchmark_tests: Enable the build of the benchmark tests
514
515@b pmu: Enable the PMU cycle counter to measure execution time in benchmark tests. (Your device needs to support it)
516
Anthony Barbier6a5627a2017-09-26 14:42:02 +0100[diff] [blame]517@b mali: Enable the collection of Mali hardware counters to measure execution time in benchmark tests. (Your device needs to have a Mali driver that supports it)
518
Anthony Barbier79c61782017-06-23 11:48:24 +0100[diff] [blame]519@b openmp Build in the OpenMP scheduler for NEON.
520
521@note Only works when building with g++ not clang++
522
523@b cppthreads Build in the C++11 scheduler for NEON.
524
525@sa arm_compute::Scheduler::set
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]526
Moritz Pflanzer07674de2017-07-21 09:39:36 +0100[diff] [blame]527@subsection S3_2_linux Building for Linux
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]528
529@subsubsection S3_2_1_library How to build the library ?
530
531For Linux, the library was successfully built and tested using the following Linaro GCC toolchain:
532
533 - gcc-linaro-arm-linux-gnueabihf-4.9-2014.07_linux
534 - gcc-linaro-4.9-2016.02-x86_64_aarch64-linux-gnu
535 - gcc-linaro-6.3.1-2017.02-i686_aarch64-linux-gnu
536
537@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)
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]538@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)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]539
540To cross-compile the library in debug mode, with NEON only support, for Linux 32bit:
541
542 scons Werror=1 -j8 debug=1 neon=1 opencl=0 os=linux arch=armv7a
543
544To cross-compile the library in asserts mode, with OpenCL only support, for Linux 64bit:
545
546 scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=1 embed_kernels=1 os=linux arch=arm64-v8a
547
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]548To cross-compile the library in asserts mode, with GLES_COMPUTE only support, for Linux 64bit:
549
550 scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=0 gles_compute=1 embed_kernels=1 os=linux arch=arm64-v8a
551
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]552You can also compile the library natively on an ARM device by using <b>build=native</b>:
553
554 scons Werror=1 -j8 debug=0 neon=1 opencl=0 os=linux arch=arm64-v8a build=native
555 scons Werror=1 -j8 debug=0 neon=1 opencl=0 os=linux arch=armv7a build=native
556
557@note g++ for ARM is mono-arch, therefore if you want to compile for Linux 32bit on a Linux 64bit platform you will have to use a cross compiler.
558
559For example on a 64bit Debian based system you would have to install <b>g++-arm-linux-gnueabihf</b>
560
561 apt-get install g++-arm-linux-gnueabihf
562
563Then run
564
565 scons Werror=1 -j8 debug=0 neon=1 opencl=0 os=linux arch=armv7a build=cross_compile
566
567or simply remove the build parameter as build=cross_compile is the default value:
568
569 scons Werror=1 -j8 debug=0 neon=1 opencl=0 os=linux arch=armv7a
570
571@attention To cross compile with opencl=1 you need to make sure to have a version of libOpenCL matching your target architecture.
572
573@subsubsection S3_2_2_examples How to manually build the examples ?
574
575The 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.
576
577@note The following command lines assume the arm_compute and libOpenCL binaries are present in the current directory or in the system library path. If this is not the case you can specify the location of the pre-built library with the compiler option -L. When building the OpenCL example the commands below assume that the CL headers are located in the include folder where the command is executed.
578
579To cross compile a NEON example for Linux 32bit:
580
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]581 arm-linux-gnueabihf-g++ examples/neon_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -mfpu=neon -L. -larm_compute -larm_compute_core -o neon_convolution
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]582
583To cross compile a NEON example for Linux 64bit:
584
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]585 aarch64-linux-gnu-g++ examples/neon_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -L. -larm_compute -larm_compute_core -o neon_convolution
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]586
587(notice the only difference with the 32 bit command is that we don't need the -mfpu option and the compiler's name is different)
588
589To cross compile an OpenCL example for Linux 32bit:
590
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]591 arm-linux-gnueabihf-g++ examples/cl_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -mfpu=neon -L. -larm_compute -larm_compute_core -lOpenCL -o cl_convolution -DARM_COMPUTE_CL
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]592
593To cross compile an OpenCL example for Linux 64bit:
594
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]595 aarch64-linux-gnu-g++ examples/cl_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -L. -larm_compute -larm_compute_core -lOpenCL -o cl_convolution -DARM_COMPUTE_CL
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]596
597(notice the only difference with the 32 bit command is that we don't need the -mfpu option and the compiler's name is different)
598
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]599To cross compile the examples with the Graph API, such as graph_lenet.cpp, you need to link the library arm_compute_graph.so also.
600(notice the compute library has to be built with both neon and opencl enabled - neon=1 and opencl=1)
601
602i.e. to cross compile the "graph_lenet" example for Linux 32bit:
603
Isabella Gottardib28f29d2017-11-09 17:05:07 +0000[diff] [blame]604 arm-linux-gnueabihf-g++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -mfpu=neon -L. -larm_compute_graph -larm_compute -larm_compute_core -Wl,--allow-shlib-undefined
605 -o graph_lenet
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]606
607i.e. to cross compile the "graph_lenet" example for Linux 64bit:
608
Isabella Gottardib28f29d2017-11-09 17:05:07 +0000[diff] [blame]609 aarch64-linux-gnu-g++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -L. -larm_compute_graph -larm_compute -larm_compute_core -Wl,--allow-shlib-undefined -o graph_lenet
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]610
611(notice the only difference with the 32 bit command is that we don't need the -mfpu option and the compiler's name is different)
612
Anthony Barbiere5007472017-10-27 15:01:44 +0100[diff] [blame]613@note If compiling using static libraries, this order must be followed when linking: arm_compute_graph_static, arm_compute, arm_compute_core
614
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]615To compile natively (i.e directly on an ARM device) for NEON for Linux 32bit:
616
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]617 g++ examples/neon_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -mfpu=neon -larm_compute -larm_compute_core -o neon_convolution
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]618
619To compile natively (i.e directly on an ARM device) for NEON for Linux 64bit:
620
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]621 g++ examples/neon_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -larm_compute -larm_compute_core -o neon_convolution
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]622
623(notice the only difference with the 32 bit command is that we don't need the -mfpu option)
624
625To compile natively (i.e directly on an ARM device) for OpenCL for Linux 32bit or Linux 64bit:
626
Anthony Barbierb2881fc2017-09-29 17:12:12 +0100[diff] [blame]627 g++ examples/cl_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -larm_compute -larm_compute_core -lOpenCL -o cl_convolution -DARM_COMPUTE_CL
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]628
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]629To compile natively (i.e directly on an ARM device) the examples with the Graph API, such as graph_lenet.cpp, you need to link the library arm_compute_graph.so also.
630(notice the compute library has to be built with both neon and opencl enabled - neon=1 and opencl=1)
631
632i.e. to cross compile the "graph_lenet" example for Linux 32bit:
633
Isabella Gottardib28f29d2017-11-09 17:05:07 +0000[diff] [blame]634 g++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 -mfpu=neon -L. -larm_compute_graph -larm_compute -larm_compute_core -Wl,--allow-shlib-undefined -o graph_lenet
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]635
636i.e. to cross compile the "graph_lenet" example for Linux 64bit:
637
Isabella Gottardib28f29d2017-11-09 17:05:07 +0000[diff] [blame]638 g++ examples/graph_lenet.cpp utils/Utils.cpp utils/GraphUtils.cpp -I. -Iinclude -std=c++11 L. -larm_compute_graph -larm_compute -larm_compute_core -Wl,--allow-shlib-undefined -o graph_lenet
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]639
640(notice the only difference with the 32 bit command is that we don't need the -mfpu option)
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]641
Anthony Barbiere5007472017-10-27 15:01:44 +0100[diff] [blame]642@note If compiling using static libraries, this order must be followed when linking: arm_compute_graph_static, arm_compute, arm_compute_core
643
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]644@note These two commands assume libarm_compute.so is available in your library path, if not add the path to it using -L
645
646To run the built executable simply run:
647
648 LD_LIBRARY_PATH=build ./neon_convolution
649
650or
651
652 LD_LIBRARY_PATH=build ./cl_convolution
653
654@note If you built the library with support for both OpenCL and NEON you will need to link against OpenCL even if your application only uses NEON.
655
Moritz Pflanzer07674de2017-07-21 09:39:36 +0100[diff] [blame]656@subsection S3_3_android Building for Android
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]657
658For Android, the library was successfully built and tested using Google's standalone toolchains:
659 - arm-linux-androideabi-4.9 for armv7a (clang++)
660 - aarch64-linux-android-4.9 for arm64-v8a (g++)
661
662Here is a guide to <a href="https://developer.android.com/ndk/guides/standalone_toolchain.html">create your Android standalone toolchains from the NDK</a>
663
664- Download the NDK r14 from here: https://developer.android.com/ndk/downloads/index.html
665- Make sure you have Python 2 installed on your machine.
666- Generate the 32 and/or 64 toolchains by running the following commands:
667
668
Anthony Barbiere5007472017-10-27 15:01:44 +0100[diff] [blame]669 $NDK/build/tools/make_standalone_toolchain.py --arch arm64 --install-dir $MY_TOOLCHAINS/aarch64-linux-android-4.9 --stl gnustl --api 21
670 $NDK/build/tools/make_standalone_toolchain.py --arch arm --install-dir $MY_TOOLCHAINS/arm-linux-androideabi-4.9 --stl gnustl --api 21
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]671
672@attention Due to some NDK issues make sure you use g++ & gnustl for aarch64 and clang++ & gnustl for armv7
673
674@note Make sure to add the toolchains to your PATH: export PATH=$PATH:$MY_TOOLCHAINS/aarch64-linux-android-4.9/bin:$MY_TOOLCHAINS/arm-linux-androideabi-4.9/bin
675
676@subsubsection S3_3_1_library How to build the library ?
677
678@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)
679
680To cross-compile the library in debug mode, with NEON only support, for Android 32bit:
681
682 CXX=clang++ CC=clang scons Werror=1 -j8 debug=1 neon=1 opencl=0 os=android arch=armv7a
683
684To cross-compile the library in asserts mode, with OpenCL only support, for Android 64bit:
685
686 scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=1 embed_kernels=1 os=android arch=arm64-v8a
687
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]688To cross-compile the library in asserts mode, with GLES_COMPUTE only support, for Android 64bit:
689
690 scons Werror=1 -j8 debug=0 asserts=1 neon=0 opencl=0 gles_compute=1 embed_kernels=1 os=android arch=arm64-v8a
691
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]692@subsubsection S3_3_2_examples How to manually build the examples ?
693
694The 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.
695
Anthony Barbierfabb0382017-06-23 14:42:52 +0100[diff] [blame]696@note The following command lines assume the arm_compute and libOpenCL binaries are present in the current directory or in the system library path. If this is not the case you can specify the location of the pre-built library with the compiler option -L. When building the OpenCL example the commands below assume that the CL headers are located in the include folder where the command is executed.
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]697
698Once you've got your Android standalone toolchain built and added to your path you can do the following:
699
700To cross compile a NEON example:
701
702 #32 bit:
Georgios Pinitas9873ea32017-12-05 15:28:55 +0000[diff] [blame]703 arm-linux-androideabi-clang++ examples/neon_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -larm_compute-static -larm_compute_core-static -L. -o neon_convolution_arm -static-libstdc++ -pie
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]704 #64 bit:
Georgios Pinitas9873ea32017-12-05 15:28:55 +0000[diff] [blame]705 aarch64-linux-android-g++ examples/neon_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -larm_compute-static -larm_compute_core-static -L. -o neon_convolution_aarch64 -static-libstdc++ -pie
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]706
707To cross compile an OpenCL example:
708
709 #32 bit:
Georgios Pinitas9873ea32017-12-05 15:28:55 +0000[diff] [blame]710 arm-linux-androideabi-clang++ examples/cl_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -larm_compute-static -larm_compute_core-static -L. -o cl_convolution_arm -static-libstdc++ -pie -lOpenCL -DARM_COMPUTE_CL
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]711 #64 bit:
Georgios Pinitas9873ea32017-12-05 15:28:55 +0000[diff] [blame]712 aarch64-linux-android-g++ examples/cl_convolution.cpp utils/Utils.cpp -I. -Iinclude -std=c++11 -larm_compute-static -larm_compute_core-static -L. -o cl_convolution_aarch64 -static-libstdc++ -pie -lOpenCL -DARM_COMPUTE_CL
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]713
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]714To cross compile the examples with the Graph API, such as graph_lenet.cpp, you need to link the library arm_compute_graph also.
715(notice the compute library has to be built with both neon and opencl enabled - neon=1 and opencl=1)
716
717 #32 bit:
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]718 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
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]719 #64 bit:
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]720 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
Gian Marco Iodicedaec1aa2017-09-29 12:03:18 +0100[diff] [blame]721
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]722@note Due to some issues in older versions of the Mali OpenCL DDK (<= r13p0), we recommend to link arm_compute statically on Android.
Anthony Barbier20dbb822017-12-13 21:19:39 +0000[diff] [blame^]723@note When linked statically the arm_compute_graph library currently needs the --whole-archive linker flag in order to work properly
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]724
725Then you need to do is upload the executable and the shared library to the device using ADB:
726
727 adb push neon_convolution_arm /data/local/tmp/
728 adb push cl_convolution_arm /data/local/tmp/
729 adb shell chmod 777 -R /data/local/tmp/
730
731And finally to run the example:
732
733 adb shell /data/local/tmp/neon_convolution_arm
734 adb shell /data/local/tmp/cl_convolution_arm
735
736For 64bit:
737
738 adb push neon_convolution_aarch64 /data/local/tmp/
739 adb push cl_convolution_aarch64 /data/local/tmp/
740 adb shell chmod 777 -R /data/local/tmp/
741
742And finally to run the example:
743
744 adb shell /data/local/tmp/neon_convolution_aarch64
745 adb shell /data/local/tmp/cl_convolution_aarch64
746
Michalis Spyrou6e52ba32017-10-04 15:40:38 +0100[diff] [blame]747@subsection S3_4_bare_metal Building for bare metal
748
749For bare metal, the library was successfully built using linaros's latest (gcc-linaro-6.3.1-2017.05) bare metal toolchains:
750 - arm-eabi for armv7a
751 - aarch64-elf for arm64-v8a
752
753Download linaro for <a href="https://releases.linaro.org/components/toolchain/binaries/6.3-2017.05/arm-eabi/">armv7a</a> and <a href="https://releases.linaro.org/components/toolchain/binaries/6.3-2017.05/aarch64-elf/">arm64-v8a</a>.
754
755@note Make sure to add the toolchains to your PATH: export PATH=$PATH:$MY_TOOLCHAINS/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-elf/bin:$MY_TOOLCHAINS/gcc-linaro-6.3.1-2017.05-x86_64_arm-eabi/bin
756
757@subsubsection S3_4_1_library How to build the library ?
758
759To cross-compile the library with NEON support for baremetal arm64-v8a:
760
761 scons Werror=1 -j8 debug=0 neon=1 opencl=0 os=bare_metal arch=arm64-v8a build=cross_compile cppthreads=0 openmp=0 standalone=1
762
763@subsubsection S3_4_2_examples How to manually build the examples ?
764
765Examples are disabled when building for bare metal. If you want to build the examples you need to provide a custom bootcode depending on the target architecture and link against the compute library. More information about bare metal bootcode can be found <a href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dai0527a/index.html">here</a>.
766
767@subsection S3_5_windows_host Building on a Windows host system
Moritz Pflanzer07674de2017-07-21 09:39:36 +0100[diff] [blame]768
769Using `scons` directly from the Windows command line is known to cause
770problems. The reason seems to be that if `scons` is setup for cross-compilation
771it gets confused about Windows style paths (using backslashes). Thus it is
772recommended to follow one of the options outlined below.
773
Michalis Spyrou6e52ba32017-10-04 15:40:38 +0100[diff] [blame]774@subsubsection S3_5_1_ubuntu_on_windows Bash on Ubuntu on Windows
Moritz Pflanzer07674de2017-07-21 09:39:36 +0100[diff] [blame]775
776The best and easiest option is to use
777<a href="https://msdn.microsoft.com/en-gb/commandline/wsl/about">Ubuntu on Windows</a>.
778This feature is still marked as *beta* and thus might not be available.
779However, if it is building the library is as simple as opening a *Bash on
780Ubuntu on Windows* shell and following the general guidelines given above.
781
Michalis Spyrou6e52ba32017-10-04 15:40:38 +0100[diff] [blame]782@subsubsection S3_5_2_cygwin Cygwin
Moritz Pflanzer07674de2017-07-21 09:39:36 +0100[diff] [blame]783
784If the Windows subsystem for Linux is not available <a href="https://www.cygwin.com/">Cygwin</a>
785can be used to install and run `scons`. In addition to the default packages
786installed by Cygwin `scons` has to be selected in the installer. (`git` might
787also be useful but is not strictly required if you already have got the source
788code of the library.) Linaro provides pre-built versions of
789<a href="http://releases.linaro.org/components/toolchain/binaries/">GCC cross-compilers</a>
790that can be used from the Cygwin terminal. When building for Android the
791compiler is included in the Android standalone toolchain. After everything has
792been set up in the Cygwin terminal the general guide on building the library
793can be followed.
794
Michalis Spyrou6e52ba32017-10-04 15:40:38 +0100[diff] [blame]795@subsection S3_6_cl_stub_library The OpenCL stub library
Anthony Barbier6ff3b192017-09-04 18:44:23 +0100[diff] [blame]796
797In the opencl-1.2-stubs folder you will find the sources to build a stub OpenCL library which then can be used to link your application or arm_compute against.
798
799If you preferred you could retrieve the OpenCL library from your device and link against this one but often this library will have dependencies on a range of system libraries forcing you to link your application against those too even though it is not using them.
800
801@warning This OpenCL library provided is a stub and *not* a real implementation. You can use it to resolve OpenCL's symbols in arm_compute while building the example but you must make sure the real libOpenCL.so is in your PATH when running the example or it will not work.
802
803To cross-compile the stub OpenCL library simply run:
804
805 <target-prefix>-gcc -o libOpenCL.so -Iinclude opencl-1.2-stubs/opencl_stubs.c -fPIC -shared
806
807For example:
808
809 <target-prefix>-gcc -o libOpenCL.so -Iinclude opencl-1.2-stubs/opencl_stubs.c -fPIC -shared
810 #Linux 32bit
811 arm-linux-gnueabihf-gcc -o libOpenCL.so -Iinclude opencl-1.2-stubs/opencl_stubs.c -fPIC -shared
812 #Linux 64bit
813 aarch64-linux-gnu-gcc -o libOpenCL.so -Iinclude -shared opencl-1.2-stubs/opencl_stubs.c -fPIC
814 #Android 32bit
815 arm-linux-androideabi-clang -o libOpenCL.so -Iinclude -shared opencl-1.2-stubs/opencl_stubs.c -fPIC -shared
816 #Android 64bit
817 aarch64-linux-android-gcc -o libOpenCL.so -Iinclude -shared opencl-1.2-stubs/opencl_stubs.c -fPIC -shared
818*/