BuildGuideCrossCompilation.md

   1 # How to Cross-Compile ArmNN on x86_64 for arm64
   2
   3 *  [Introduction](#introduction)
   4 *  [Cross-compiling ToolChain](#installCCT)
   5 *  [Build and install Google's Protobuf library](#buildProtobuf)
   6 *  [Build Caffe for x86_64](#buildCaffe)
   7 *  [Build Boost library for arm64](#installBaarch)
   8 *  [Build Compute Library](#buildCL)
   9 *  [Build ArmNN](#buildANN)
  10 *  [Run Unit Tests](#unittests)
  11 *  [Troubleshooting and Errors](#troubleshooting)
  12
  13
  14 #### <a name="introduction">Introduction</a>
  15 These are the step by step instructions on Cross-Compiling ArmNN under an x86_64 system to target an Arm64 system. This build flow has been tested with Ubuntu 16.04.
  16 The instructions show how to build the ArmNN core library and the Boost, Protobuf, Caffe, Tensorflow, Tflite, Flatbuffer and Compute Libraries necessary for compilation.
  17
  18 #### <a name="installCCT">Cross-compiling ToolChain</a>
  19 * Install the standard cross-compilation libraries for arm64:
  20     ```
  21     sudo apt install crossbuild-essential-arm64
  22     ```
  23
  24 #### <a name="buildProtobuf">Build and install Google's Protobuf library</a>
  25
  26 ## We support protobuf version 3.5.2
  27 * Get protobuf from here: https://github.com/protocolbuffers/protobuf :
  28     ```bash
  29     git clone -b v3.5.2 https://github.com/google/protobuf.git protobuf
  30     cd protobuf
  31     git submodule update --init --recursive
  32     ./autogen
  33     ```
  34 * Build a native (x86_64) version of the protobuf libraries and compiler (protoc):
  35   (Requires cUrl, autoconf, llibtool, and other build dependencies if not previously installed: sudo apt install curl autoconf libtool build-essential g++)
  36     ```
  37     mkdir x86_64_build
  38     cd x86_64_build
  39     ../configure --prefix=$HOME/armnn-devenv/google/x86_64_pb_install
  40     make install -j16
  41     cd ..
  42     ```
  43 * Build the arm64 version of the protobuf libraries:
  44     ```
  45     mkdir arm64_build
  46     cd arm64_build
  47     export CC=aarch64-linux-gnu-gcc \
  48     export CXX=aarch64-linux-gnu-g++ \
  49     ../configure --host=aarch64-linux \
  50     --prefix=$HOME/armnn-devenv/google/arm64_pb_install \
  51     --with-protoc=$HOME/armnn-devenv/google/x86_64_pb_install/bin/protoc
  52     make install -j16
  53     cd ..
  54     ```
  55
  56 #### <a name="buildCaffe">Build Caffe for x86_64</a>
  57 * Ubuntu 16.04 installation. These steps are taken from the full Caffe installation documentation at: http://caffe.berkeleyvision.org/install_apt.html
  58 * Install dependencies:
  59     ```bash
  60     sudo apt-get install libleveldb-dev libsnappy-dev libopencv-dev libhdf5-serial-dev
  61     sudo apt-get install --no-install-recommends libboost-all-dev
  62     sudo apt-get install libgflags-dev libgoogle-glog-dev liblmdb-dev
  63     sudo apt-get install libopenblas-dev
  64     sudo apt-get install libatlas-base-dev
  65     ```
  66 * Download Caffe-Master from: https://github.com/BVLC/caffe
  67     ```bash
  68     git clone https://github.com/BVLC/caffe.git
  69     cd caffe
  70     cp Makefile.config.example Makefile.config
  71     ```
  72 * Adjust Makefile.config as necessary for your environment, for example:
  73     ```
  74     #CPU only version:
  75     CPU_ONLY := 1
  76
  77     #Add hdf5 and protobuf include and library directories (Replace $HOME with explicit /home/username dir):
  78     INCLUDE_DIRS := $(PYTHON_INCLUDE) /usr/local/include /usr/include/hdf5/serial/ $HOME/armnn-devenv/google/x86_64_pb_install/include/
  79     LIBRARY_DIRS := $(PYTHON_LIB) /usr/local/lib /usr/lib /usr/lib/x86_64-linux-gnu/hdf5/serial/ $HOME/armnn-devenv/google/x86_64_pb_install/lib/
  80     ```
  81 * Setup environment:
  82     ```bash
  83     export PATH=$HOME/armnn-devenv/google/x86_64_pb_install/bin/:$PATH
  84     export LD_LIBRARY_PATH=$HOME/armnn-devenv/google/x86_64_pb_install/lib/:$LD_LIBRARY_PATH
  85     ```
  86 * Compilation with Make:
  87     ```bash
  88     make all
  89     make test
  90     make runtest
  91     ```
  92     These should all run without errors
  93 * caffe.pb.h and caffe.pb.cc will be needed when building ArmNN's Caffe Parser
  94
  95 #### <a name="installBaarch">Build Boost library for arm64</a>
  96 * Build Boost library for arm64
  97     Download Boost version 1.64 from http://www.boost.org/doc/libs/1_64_0/more/getting_started/unix-variants.html
  98     Using any version of Boost greater than 1.64 will fail to build ArmNN, due to different dependency issues.
  99     ```bash
 100     tar -zxvf boost_1_64_0.tar.gz
 101     cd boost_1_64_0
 102     echo "using gcc : arm : aarch64-linux-gnu-g++ ;" > user_config.jam
 103     ./bootstrap.sh --prefix=$HOME/armnn-devenv/boost_arm64_install
 104     ./b2 install toolset=gcc-arm link=static cxxflags=-fPIC --with-test --with-log --with-program_options -j32 --user-config=user_config.jam
 105     ```
 106
 107 #### <a name="buildCL">Build Compute Library</a>
 108 * Building the Arm Compute Library:
 109     ```bash
 110     git clone https://github.com/ARM-software/ComputeLibrary.git
 111     cd ComputeLibrary/
 112     git checkout <branch_name>
 113     git pull
 114     scons arch=arm64-v8a neon=1 opencl=1 embed_kernels=1 extra_cxx_flags="-fPIC" -j8 internal_only=0
 115     ```
 116
 117     For example, if you want to checkout release branch of 20.02:
 118         ```bash
 119         git checkout branches/arm_compute_20_02
 120         git pull
 121         ```
 122
 123 #### <a name="buildtf">Build Tensorflow</a>
 124 * Building Tensorflow version 1.15:
 125     '''bash
 126     git clone https://github.com/tensorflow/tensorflow.git
 127     cd tensorflow/
 128     git checkout 590d6eef7e91a6a7392c8ffffb7b58f2e0c8bc6b
 129     ../armnn/scripts/generate_tensorflow_protobuf.sh ../tensorflow-protobuf ../google/x86_64_pb_install
 130     '''
 131
 132 #### <"a name=buildflatbuffer">Build Flatbuffer</a>
 133 * Building Flatbuffer version 1.10.0
 134     '''bash
 135     wget -O flatbuffers-1.10.0.tar.gz https://github.com/google/flatbuffers/archive/v1.10.0.tar.gz
 136     tar xf flatbuffers-1.10.0.tar.gz
 137     cd flatbuffers-1.10.0
 138     rm -f CMakeCache.txt
 139     mkdir build
 140     cd build
 141     cmake .. -DFLATBUFFERS_BUILD_FLATC=1 \
 142              -DCMAKE_INSTALL_PREFIX:PATH=$<DIRECTORY_PATH> \
 143              -DFLATBUFFERS_BUILD_TESTS=0
 144     make all install
 145     '''
 146 * Build arm64 version of flatbuffer
 147     '''bash
 148     mkdir build-arm64
 149     cd build-arm64
 150     cmake .. -DCMAKE_C_COMPILER=/usr/bin/aarch64-linux-gnu-gcc \
 151              -DCMAKE_CXX_COMPILER=/usr/bin/aarch64-linux-gnu-g++ \
 152              -DFLATBUFFERS_BUILD_FLATC=1 \
 153              -DCMAKE_INSTALL_PREFIX:PATH=$<DIRECTORY_PATH> \
 154              -DFLATBUFFERS_BUILD_TESTS=0
 155     make all install
 156     '''
 157
 158 #### <a name="buildingONNX">Build Onnx</a>
 159 * Building Onnx
 160     '''bash
 161     git clone https://github.com/onnx/onnx.git
 162     cd onnx
 163     git fetch https://github.com/onnx/onnx.git f612532843bd8e24efeab2815e45b436479cc9ab && git checkout FETCH_HEAD
 164     export LD_LIBRARY_PATH=$<DIRECTORY_PATH>/protobuf-host/lib:$LD_LIBRARY_PATH
 165     ../google/x86_64_pb_install/bin/protoc onnx/onnx.proto --proto_path=. --proto_path=../google/x86_64_pb_install/include --cpp_out ../onnx
 166     '''
 167
 168 #### <a name="buildingtflite">Build TfLite</a>
 169 * Building TfLite
 170     '''bash
 171     mkdir tflite
 172     cd tflite
 173     cp ../tensorflow/tensorflow/lite/schema/schema.fbs .
 174     ../flatbuffers-1.10.0/build/flatc -c --gen-object-api --reflect-types --reflect-names schema.fbs
 175     '''
 176
 177 #### <a name="buildANN">Build ArmNN</a>
 178 * Compile ArmNN for arm64:
 179     ```bash
 180     git clone https://github.com/ARM-software/armnn.git
 181     cd armnn
 182     git checkout <branch_name>
 183     git pull
 184     mkdir build
 185     cd build
 186     ```
 187
 188     For example, if you want to checkout release branch of 20.02:
 189         ```bash
 190         git checkout branches/armnn_20_02
 191         git pull
 192         ```
 193
 194 * Use CMake to configure your build environment, update the following script and run it from the armnn/build directory to set up the armNN build:
 195     ```bash
 196     #!/bin/bash
 197     export CXX=aarch64-linux-gnu-g++ \
 198     export CC=aarch64-linux-gnu-gcc \
 199     cmake .. \
 200     -DARMCOMPUTE_ROOT=$HOME/armnn-devenv/ComputeLibrary \
 201     -DARMCOMPUTE_BUILD_DIR=$HOME/armnn-devenv/ComputeLibrary/build/ \
 202     -DBOOST_ROOT=$HOME/armnn-devenv/boost_arm64_install/ \
 203     -DARMCOMPUTENEON=1 -DARMCOMPUTECL=1 -DARMNNREF=1 \
 204     -DCAFFE_GENERATED_SOURCES=$HOME/armnn-devenv/caffe/build/src \
 205     -DBUILD_CAFFE_PARSER=1 \
 206     -DONNX_GENERATED_SOURCES=$HOME/onnx \
 207     -DBUILD_ONNX_PARSER=1 \
 208     -DTF_GENERATED_SOURCES=$HOME/tensorflow-protobuf \
 209     -DBUILD_TF_PARSER=1 \
 210     -DBUILD_TF_LITE_PARSER=1 \
 211     -DTF_LITE_GENERATED_PATH=$HOME/tflite \
 212     -DFLATBUFFERS_ROOT=$HOME/flatbuffers-arm64 \
 213     -DFLATC_DIR=$HOME/flatbuffers-1.10.0/build \
 214     -DPROTOBUF_ROOT=$HOME/google/x86_64_pb_install \
 215     -DPROTOBUF_ROOT=$HOME/armnn-devenv/google/x86_64_pb_install/ \
 216     -DPROTOBUF_LIBRARY_DEBUG=$HOME/armnn-devenv/google/arm64_pb_install/lib/libprotobuf.so.15.0.1 \
 217     -DPROTOBUF_LIBRARY_RELEASE=$HOME/armnn-devenv/google/arm64_pb_install/lib/libprotobuf.so.15.0.1
 218     ```
 219
 220 * If you want to include standalone sample dynamic backend tests, add the argument to enable the tests and the dynamic backend path to the CMake command:
 221     ```bash
 222     -DSAMPLE_DYNAMIC_BACKEND=1 \
 223     -DDYNAMIC_BACKEND_PATHS=$SAMPLE_DYNAMIC_BACKEND_PATH
 224     ```
 225 * Run the build
 226     ```bash
 227     make -j32
 228     ```
 229
 230 #### <a name="buildStandaloneBackend">Build Standalone Sample Dynamic Backend</a>
 231 * The sample dynamic backend is located in armnn/src/dynamic/sample
 232     ```bash
 233     mkdir build
 234     cd build
 235     ```
 236
 237 * Use CMake to configure your build environment, update the following script and run it from the armnn/src/dynamic/sample/build directory to set up the armNN build:
 238     ```bash
 239     #!/bin/bash
 240     export CXX=aarch64-linux-gnu-g++ \
 241     export CC=aarch64-linux-gnu-gcc \
 242     cmake .. \
 243     -DCMAKE_CXX_FLAGS=--std=c++14 \
 244     -DBOOST_ROOT=$HOME/armnn-devenv/boost_arm64_install/ \
 245     -DBoost_SYSTEM_LIBRARY=$HOME/armnn-devenv/boost_arm64_install/lib/libboost_system.a \
 246     -DARMNN_PATH=$HOME/armnn-devenv/armnn/build/libarmnn.so
 247     ```
 248
 249 * Run the build
 250     ```bash
 251     make
 252     ```
 253
 254 #### <a name="unittests">Run Unit Tests</a>
 255 * Copy the build folder to an arm64 linux machine
 256 * Copy the libprotobuf.so.15.0.1 library file to the build folder
 257 * If you enable the standalone sample dynamic tests, also copy libArm_SampleDynamic_backend.so library file to the folder specified as $SAMPLE_DYNAMIC_BACKEND_PATH when you build ArmNN
 258 * cd to the build folder on your arm64 machine and set your LD_LIBRARY_PATH to its current location:
 259     ```
 260     cd build/
 261     export LD_LIBRARY_PATH=`pwd`
 262     ```
 263 * Create a symbolic link to libprotobuf.so.15.0.1:
 264     ```
 265     ln -s libprotobuf.so.15.0.1 ./libprotobuf.so.15
 266     ```
 267 * Run the UnitTests:
 268     ```
 269     ./UnitTests
 270     Running 567 test cases...
 271
 272     *** No errors detected
 273     ```
 274 #### <a name="troubleshooting">Troubleshooting and Errors:</a>
 275 #### Error adding symbols: File in wrong format
 276 * When building armNN:
 277     ```
 278     /usr/local/lib/libboost_log.a: error adding symbols: File in wrong format
 279     collect2: error: ld returned 1 exit status
 280     CMakeFiles/armnn.dir/build.make:4028: recipe for target 'libarmnn.so' failed
 281     make[2]: *** [libarmnn.so] Error 1
 282     CMakeFiles/Makefile2:105: recipe for target 'CMakeFiles/armnn.dir/all' failed
 283     make[1]: *** [CMakeFiles/armnn.dir/all] Error 2
 284     Makefile:127: recipe for target 'all' failed
 285     make: *** [all] Error 2
 286     ```
 287 * Boost libraries are not compiled for the correct architecture, try recompiling for arm64
 288 ##
 289 #### Virtual memory exhausted
 290 * When compiling the boost libraries:
 291     ```bash
 292     virtual memory exhausted: Cannot allocate memory
 293     ```
 294 * Not enough memory available to compile. Increase the amount of RAM or swap space available.
 295
 296 ##
 297 #### Unrecognized command line option '-m64'
 298 * When compiling the boost libraries:
 299     ```bash
 300     aarch64-linux-gnu-g++: error: unrecognized command line option ‘-m64’
 301     ```
 302 * Clean the boost library directory before trying to build with a different architecture:
 303     ```bash
 304     sudo ./b2 clean
 305     ```
 306 * It should show the following for arm64:
 307     ```bash
 308     - 32-bit                   : no
 309     - 64-bit                   : yes
 310     - arm                      : yes
 311     ```
 312
 313 ##
 314 #### Missing libz.so.1
 315 * When compiling armNN:
 316     ```bash
 317     /usr/lib/gcc-cross/aarch64-linux-gnu/5/../../../../aarch64-linux-gnu/bin/ld: warning: libz.so.1, needed by /home/<username>/armNN/usr/lib64/libprotobuf.so.15.0.0, not found (try using -rpath or -rpath-link)
 318     ```
 319
 320 * Missing arm64 libraries for libz.so.1, these can be added by adding a second architecture to dpkg and explicitly installing them:
 321     ```bash
 322     sudo dpkg --add-architecture arm64
 323     sudo apt-get install zlib1g:arm64
 324     sudo apt-get update
 325     sudo ldconfig
 326     ```
 327 * If apt-get update returns 404 errors for arm64 repos refer to section 5 below.
 328 * Alternatively the missing arm64 version of libz.so.1 can be downloaded and installed from a .deb package here:
 329       https://launchpad.net/ubuntu/wily/arm64/zlib1g/1:1.2.8.dfsg-2ubuntu4
 330     ```bash
 331     sudo dpkg -i zlib1g_1.2.8.dfsg-2ubuntu4_arm64.deb
 332     ```
 333 ##
 334 #### Unable to install arm64 packages after adding arm64 architecture
 335 * Using sudo apt-get update should add all of the required repos for arm64 but if it does not or you are getting 404 errors the following instructions can be used to add the repos manually:
 336 * From stackoverflow:
 337 https://askubuntu.com/questions/430705/how-to-use-apt-get-to-download-multi-arch-library/430718
 338 * Open /etc/apt/sources.list with your preferred text editor.
 339
 340 * Mark all the current (default) repos as \[arch=<current_os_arch>], e.g.
 341     ```bash
 342     deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ xenial main restricted
 343     ```
 344 * Then add the following:
 345     ```bash
 346     deb [arch=arm64] http://ports.ubuntu.com/ xenial main restricted
 347     deb [arch=arm64] http://ports.ubuntu.com/ xenial-updates main restricted
 348     deb [arch=arm64] http://ports.ubuntu.com/ xenial universe
 349     deb [arch=arm64] http://ports.ubuntu.com/ xenial-updates universe
 350     deb [arch=arm64] http://ports.ubuntu.com/ xenial multiverse
 351     deb [arch=arm64] http://ports.ubuntu.com/ xenial-updates multiverse
 352     deb [arch=arm64] http://ports.ubuntu.com/ xenial-backports main restricted universe multiverse
 353     ```
 354 * Update and install again:
 355     ```bash
 356     sudo apt-get install zlib1g:arm64
 357     sudo apt-get update
 358     sudo ldconfig
 359     ```
 360 ##
 361 #### Undefined references to google::protobuf:: functions
 362 * When compiling armNN there are multiple errors of the following type:
 363     ```
 364     libarmnnCaffeParser.so: undefined reference to `google::protobuf:*
 365     ```
 366 * Missing or out of date protobuf compilation libraries.
 367     Use the command 'protoc --version' to check which version of protobuf is available (version 3.5.2 is required).
 368     Follow the instructions above to install protobuf 3.5.2
 369     Note this will require you to recompile Caffe for x86_64
 370
 371 ##
 372 #### Errors on strict-aliasing rules when compiling the Compute Library
 373 * When compiling the Compute Library there are multiple errors on strict-aliasing rules:
 374      ```
 375     cc1plus: error: unrecognized command line option ‘-Wno-implicit-fallthrough’ [-Werror]
 376      ```
 377 * Add Werror=0 to the scons command:
 378     ```
 379     scons arch=arm64-v8a neon=1 opencl=1 embed_kernels=1 extra_cxx_flags="-fPIC" -j8 internal_only=0 Werror=0
 380     ```