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 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 * Get protobuf-all-3.5.1.tar.gz from here: https://github.com/protocolbuffers/protobuf/releases/tag/v3.5.1
  27 * Extract:
  28     ```bash
  29     tar -zxvf protobuf-all-3.5.1.tar.gz
  30     cd protobuf-3.5.1
  31     ```
  32 * Build a native (x86_64) version of the protobuf libraries and compiler (protoc):
  33   (Requires cUrl, autoconf, llibtool, and other build dependencies if not previously installed: sudo apt install curl autoconf libtool build-essential g++)
  34     ```
  35     mkdir x86_64_build
  36     cd x86_64_build
  37     ../configure --prefix=$HOME/armnn-devenv/google/x86_64_pb_install
  38     make install -j16
  39     cd ..
  40     ```
  41 * Build the arm64 version of the protobuf libraries:
  42     ```
  43     mkdir arm64_build
  44     cd arm64_build
  45     CC=aarch64-linux-gnu-gcc \
  46     CXX=aarch64-linux-gnu-g++ \
  47     ../configure --host=aarch64-linux \
  48     --prefix=$HOME/armnn-devenv/google/arm64_pb_install \
  49     --with-protoc=$HOME/armnn-devenv/google/x86_64_pb_install/bin/protoc
  50     make install -j16
  51     cd ..
  52     ```
  53
  54 #### <a name="buildCaffe">Build Caffe for x86_64</a>
  55 * Ubuntu 16.04 installation. These steps are taken from the full Caffe installation documentation at: http://caffe.berkeleyvision.org/install_apt.html
  56 * Install dependencies:
  57     ```bash
  58     sudo apt-get install libleveldb-dev libsnappy-dev libopencv-dev libhdf5-serial-dev
  59     sudo apt-get install --no-install-recommends libboost-all-dev
  60     sudo apt-get install libgflags-dev libgoogle-glog-dev liblmdb-dev
  61     sudo apt-get install libopenblas-dev
  62     sudo apt-get install libatlas-base-dev
  63     ```
  64 * Download Caffe-Master from: https://github.com/BVLC/caffe
  65     ```bash
  66     git clone https://github.com/BVLC/caffe.git
  67     cd caffe
  68     cp Makefile.config.example Makefile.config
  69     ```
  70 * Adjust Makefile.config as necessary for your environment, for example:
  71     ```
  72     #CPU only version:
  73     CPU_ONLY := 1
  74
  75     #Add hdf5 and protobuf include and library directories (Replace $HOME with explicit /home/username dir):
  76     INCLUDE_DIRS := $(PYTHON_INCLUDE) /usr/local/include /usr/include/hdf5/serial/ $HOME/armnn-devenv/google/x86_64_pb_install/include/
  77     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/
  78     ```
  79 * Setup environment:
  80     ```bash
  81     export PATH=$HOME/armnn-devenv/google/x86_64_pb_install/bin/:$PATH
  82     export LD_LIBRARY_PATH=$HOME/armnn-devenv/google/x86_64_pb_install/lib/:$LD_LIBRARY_PATH
  83     ```
  84 * Compilation with Make:
  85     ```bash
  86     make all
  87     make test
  88     make runtest
  89     ```
  90     These should all run without errors
  91 * caffe.pb.h and caffe.pb.cc will be needed when building ArmNN's Caffe Parser
  92
  93 #### <a name="installBaarch">Build Boost library for arm64</a>
  94 * Build Boost library for arm64
  95     Download Boost version 1.64 from http://www.boost.org/doc/libs/1_64_0/more/getting_started/unix-variants.html
  96     Using any version of Boost greater than 1.64 will fail to build ArmNN, due to different dependency issues.
  97     ```bash
  98     tar -zxvf boost_1_64_0.tar.gz
  99     cd boost_1_64_0
 100     echo "using gcc : arm : aarch64-linux-gnu-g++ ;" > user_config.jam
 101     ./bootstrap.sh --prefix=$HOME/armnn-devenv/boost_arm64_install
 102     ./b2 install toolset=gcc-arm link=static cxxflags=-fPIC --with-filesystem --with-test --with-log --with-program_options -j32 --user-config=user_config.jam
 103     ```
 104
 105 #### <a name="buildCL">Build Compute Library</a>
 106 * Building the Arm Compute Library:
 107     ```bash
 108     git clone https://github.com/ARM-software/ComputeLibrary.git
 109     cd ComputeLibrary/
 110     scons arch=arm64-v8a neon=1 opencl=1 embed_kernels=1 extra_cxx_flags="-fPIC" -j8 internal_only=0
 111     ```
 112
 113 #### <a name="buildANN">Build ArmNN</a>
 114 * Compile ArmNN for arm64:
 115     ```bash
 116     git clone https://github.com/ARM-software/armnn.git
 117     cd armnn
 118     mkdir build
 119     cd build
 120     ```
 121
 122 * 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:
 123     ```bash
 124     #!/bin/bash
 125     CXX=aarch64-linux-gnu-g++ \
 126     CC=aarch64-linux-gnu-gcc \
 127     cmake .. \
 128     -DARMCOMPUTE_ROOT=$HOME/armnn-devenv/ComputeLibrary \
 129     -DARMCOMPUTE_BUILD_DIR=$HOME/armnn-devenv/ComputeLibrary/build/ \
 130     -DBOOST_ROOT=$HOME/armnn-devenv/boost_arm64_install/ \
 131     -DARMCOMPUTENEON=1 -DARMCOMPUTECL=1 -DARMNNREF=1 \
 132     -DCAFFE_GENERATED_SOURCES=$HOME/armnn-devenv/caffe/build/src \
 133     -DBUILD_CAFFE_PARSER=1 \
 134     -DPROTOBUF_ROOT=$HOME/armnn-devenv/google/x86_64_pb_install/ \
 135     -DPROTOBUF_LIBRARY_DEBUG=$HOME/armnn-devenv/google/arm64_pb_install/lib/libprotobuf.so.15.0.1 \
 136     -DPROTOBUF_LIBRARY_RELEASE=$HOME/armnn-devenv/google/arm64_pb_install/lib/libprotobuf.so.15.0.1
 137     ```
 138
 139 * 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:
 140     ```bash
 141     -DSAMPLE_DYNAMIC_BACKEND=1 \
 142     -DDYNAMIC_BACKEND_PATHS=$SAMPLE_DYNAMIC_BACKEND_PATH
 143     ```
 144 * Run the build
 145     ```bash
 146     make -j32
 147     ```
 148
 149 #### <a name="buildStandaloneBackend">Build Standalone Sample Dynamic Backend</a>
 150 * The sample dynamic backend is located in armnn/src/dynamic/sample
 151     ```bash
 152     mkdir build
 153     cd build
 154     ```
 155
 156 * 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:
 157     ```bash
 158     #!/bin/bash
 159     CXX=aarch64-linux-gnu-g++ \
 160     CC=aarch64-linux-gnu-gcc \
 161     cmake .. \
 162     -DCMAKE_CXX_FLAGS=--std=c++14 \
 163     -DBOOST_ROOT=$HOME/armnn-devenv/boost_arm64_install/ \
 164     -DBoost_SYSTEM_LIBRARY=$HOME/armnn-devenv/boost_arm64_install/lib/libboost_system.a \
 165     -DBoost_FILESYSTEM_LIBRARY=$HOME/armnn-devenv/boost_arm64_install/lib/libboost_filesystem.a \
 166     -DARMNN_PATH=$HOME/armnn-devenv/armnn/build/libarmnn.so
 167     ```
 168
 169 * Run the build
 170     ```bash
 171     make
 172     ```
 173
 174 #### <a name="unittests">Run Unit Tests</a>
 175 * Copy the build folder to an arm64 linux machine
 176 * Copy the libprotobuf.so.15.0.1 library file to the build folder
 177 * 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
 178 * cd to the build folder on your arm64 machine and set your LD_LIBRARY_PATH to its current location:
 179     ```
 180     cd build/
 181     export LD_LIBRARY_PATH=`pwd`
 182     ```
 183 * Create a symbolic link to libprotobuf.so.15.0.1:
 184     ```
 185     ln -s libprotobuf.so.15.0.1 ./libprotobuf.so.15
 186     ```
 187 * Run the UnitTests:
 188     ```
 189     ./UnitTests
 190     Running 567 test cases...
 191
 192     *** No errors detected
 193     ```
 194 #### <a name="troubleshooting">Troubleshooting and Errors:</a>
 195 #### Error adding symbols: File in wrong format
 196 * When building armNN:
 197     ```
 198     /usr/local/lib/libboost_log.a: error adding symbols: File in wrong format
 199     collect2: error: ld returned 1 exit status
 200     CMakeFiles/armnn.dir/build.make:4028: recipe for target 'libarmnn.so' failed
 201     make[2]: *** [libarmnn.so] Error 1
 202     CMakeFiles/Makefile2:105: recipe for target 'CMakeFiles/armnn.dir/all' failed
 203     make[1]: *** [CMakeFiles/armnn.dir/all] Error 2
 204     Makefile:127: recipe for target 'all' failed
 205     make: *** [all] Error 2
 206     ```
 207 * Boost libraries are not compiled for the correct architecture, try recompiling for arm64
 208 ##
 209 #### Virtual memory exhausted
 210 * When compiling the boost libraries:
 211     ```bash
 212     virtual memory exhausted: Cannot allocate memory
 213     ```
 214 * Not enough memory available to compile. Increase the amount of RAM or swap space available.
 215
 216 ##
 217 #### Unrecognized command line option '-m64'
 218 * When compiling the boost libraries:
 219     ```bash
 220     aarch64-linux-gnu-g++: error: unrecognized command line option ‘-m64’
 221     ```
 222 * Clean the boost library directory before trying to build with a different architecture:
 223     ```bash
 224     sudo ./b2 clean
 225     ```
 226 * It should show the following for arm64:
 227     ```bash
 228     - 32-bit                   : no
 229     - 64-bit                   : yes
 230     - arm                      : yes
 231     ```
 232
 233 ##
 234 #### Missing libz.so.1
 235 * When compiling armNN:
 236     ```bash
 237     /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)
 238     ```
 239
 240 * Missing arm64 libraries for libz.so.1, these can be added by adding a second architecture to dpkg and explicitly installing them:
 241     ```bash
 242     sudo dpkg --add-architecture arm64
 243     sudo apt-get install zlib1g:arm64
 244     sudo apt-get update
 245     sudo ldconfig
 246     ```
 247 * If apt-get update returns 404 errors for arm64 repos refer to section 5 below.
 248 * Alternatively the missing arm64 version of libz.so.1 can be downloaded and installed from a .deb package here:
 249       https://launchpad.net/ubuntu/wily/arm64/zlib1g/1:1.2.8.dfsg-2ubuntu4
 250     ```bash
 251     sudo dpkg -i zlib1g_1.2.8.dfsg-2ubuntu4_arm64.deb
 252     ```
 253 ##
 254 #### Unable to install arm64 packages after adding arm64 architecture
 255 * 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:
 256 * From stackoverflow:
 257 https://askubuntu.com/questions/430705/how-to-use-apt-get-to-download-multi-arch-library/430718
 258 * Open /etc/apt/sources.list with your preferred text editor.
 259
 260 * Mark all the current (default) repos as \[arch=<current_os_arch>], e.g.
 261     ```bash
 262     deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ xenial main restricted
 263     ```
 264 * Then add the following:
 265     ```bash
 266     deb [arch=arm64] http://ports.ubuntu.com/ xenial main restricted
 267     deb [arch=arm64] http://ports.ubuntu.com/ xenial-updates main restricted
 268     deb [arch=arm64] http://ports.ubuntu.com/ xenial universe
 269     deb [arch=arm64] http://ports.ubuntu.com/ xenial-updates universe
 270     deb [arch=arm64] http://ports.ubuntu.com/ xenial multiverse
 271     deb [arch=arm64] http://ports.ubuntu.com/ xenial-updates multiverse
 272     deb [arch=arm64] http://ports.ubuntu.com/ xenial-backports main restricted universe multiverse
 273     ```
 274 * Update and install again:
 275     ```bash
 276     sudo apt-get install zlib1g:arm64
 277     sudo apt-get update
 278     sudo ldconfig
 279     ```
 280 ##
 281 #### Undefined references to google::protobuf:: functions
 282 * When compiling armNN there are multiple errors of the following type:
 283     ```
 284     libarmnnCaffeParser.so: undefined reference to `google::protobuf:*
 285     ```
 286 * Missing or out of date protobuf compilation libraries.
 287     Use the command 'protoc --version' to check which version of protobuf is available (version 3.5.1 is required).
 288     Follow the instructions above to install protobuf 3.5.1
 289     Note this will require you to recompile Caffe for x86_64
 290
 291 ##
 292 #### Errors on strict-aliasing rules when compiling the Compute Library
 293 * When compiling the Compute Library there are multiple errors on strict-aliasing rules:
 294      ```
 295     cc1plus: error: unrecognized command line option ‘-Wno-implicit-fallthrough’ [-Werror]
 296      ```
 297 * Add Werror=0 to the scons command:
 298     ```
 299     scons arch=arm64-v8a neon=1 opencl=1 embed_kernels=1 extra_cxx_flags="-fPIC" -j8 internal_only=0 Werror=0
 300     ```