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