BuildGuideCrossCompilation.md

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