Documentation/setup-on-banana-pi-arm-board.md

   1 Setup on Banana Pi ARM board
   2 ============================
   3
   4 The Banana Pi is a cheap Raspberry-Pi-like ARM board with an Allwinner A20 SoC
   5 (dual-core Cortex-A7). It runs mainline Linux kernels and U-Boot and is
   6 comparably well hackable. Further information can be found on
   7 http://linux-sunxi.org.
   8
   9 In order to run Jailhouse, the Linux kernel version should be at least 3.19. The
  10 configuration used for continuous integration builds can serve as reference, see
  11 `ci/kernel-config-banana-pi`.
  12
  13 Meanwhile, an U-Boot release more recent than v2015.04 is required. Tested and
  14 known to work is release v2016.03. Note that, **since v2015.10, you need to
  15 disable CONFIG_VIDEO in the U-Boot config**, or U-Boot will configure the
  16 framebuffer at the end of the physical RAM where Jailhouse is located.
  17
  18 Below is a tutorial about setting up Jailhouse on a **BananaPi M1** board, and
  19 running [FreeRTOS-cell](https://github.com/siemens/freertos-cell) on the top of
  20 it. The tutorial is based on:
  21  - Ubuntu-14.04 on a x86-64 machine
  22  - BananaPi M1 board, running bananian-16.04
  23
  24
  25 Installation
  26 ------------
  27 Follow the instructions on [BananaPi official site](https://www.bananian.org/download)
  28 to build your sd-card.
  29
  30 Basically here are the steps,
  31 ```bash
  32 #On Ubuntu-14.04 (or any other machine),
  33 #HERE WE USE **BANANIAN** AS OUR BANANAPI'S OS
  34 $ wget https://dl.bananian.org/releases/bananian-latest.zip
  35 $ sudo apt-get update && sudo apt-get install unzip screen
  36 $ unzip ./bananian-latest.zip
  37 $ lsblk | grep mmcblk
  38
  39 # Write the image to sdcard, replace `mmcblk0` below with the device name
  40 # returned from `lsblk`
  41 $ sudo dd bs=1M if=~/bananian-*.img of=/dev/mmcblk0
  42
  43 #Insert the sd-card to BananaPi, connect it to our machine using ttl cable.
  44 #On Ubuntu,
  45 $ screen /dev/ttyUSB0 115200
  46
  47 #On BananaPi, login with root/pi, then expand the filesystem
  48 $ bananian-config
  49
  50 #Choose `y` for `Do you want to expand the root file system`.
  51 #Feel free to configure other stuff as well.
  52 ```
  53
  54
  55 Adjusting U-boot for kernel booting arguments.
  56 ---------------------------------------------
  57 Jailhouse needs to boot with certain Kernel arguments to reserve memory for
  58 other cells (using `mem=...`). We must adjust U-boot config file to boot with
  59 these arguments. The u-boot partition is not mounted by default. Thus, we need
  60 to mount it first. On bananian,
  61 ```bash
  62 $ mkdir /p1
  63 $ mount /dev/mmcblk0p1 /p1
  64 $ vi /p1/boot.cmd
  65 ```
  66 Append `mem=932M vmalloc=512M` on the end of line that starts with
  67 `setenv bootargs`. After editing, the file should look like:
  68 ```bash
  69 #-------------------------------------------------------------------------------
  70 # Boot loader script to boot with different boot methods for old and new kernel
  71 # Credits: https://github.com/igorpecovnik - Thank you for this great script!
  72 #-------------------------------------------------------------------------------
  73 if load mmc 0:1 0x00000000 uImage-next
  74 then
  75 # mainline kernel >= 4.x
  76 #-------------------------------------------------------------------------------
  77 setenv bootargs console=ttyS0,115200 console=tty0 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait mem=932M vmalloc=512M
  78 load mmc 0:1 0x49000000 dtb/${fdtfile}
  79 load mmc 0:1 0x46000000 uImage-next
  80 bootm 0x46000000 - 0x49000000
  81 #-------------------------------------------------------------------------------
  82 else
  83 # sunxi 3.4.x
  84 #-------------------------------------------------------------------------------
  85 setenv bootargs console=ttyS0,115200 console=tty0 console=tty1 sunxi_g2d_mem_reserve=0 sunxi_ve_mem_reserve=0 hdmi.audio=EDID:0 disp.screen0_output_mode=EDID:1680x1050p60 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait
  86 setenv bootm_boot_mode sec
  87 load mmc 0:1 0x43000000 script.bin
  88 load mmc 0:1 0x48000000 uImage
  89 bootm 0x48000000
  90 #-------------------------------------------------------------------------------
  91 fi
  92 ```
  93 After saving the file, create u-boot recognizable image `*.src` from `*.cmd`
  94 using mkimage
  95 ```bash
  96 $ apt-get update && apt-get install -y u-boot-tools
  97 $ cd /p1
  98 $ mkimage -C none -A arm -T script -d boot.cmd boot.scr
  99 ```
 100 See more on [disccusion](https://groups.google.com/forum/#!topic/jailhouse-dev/LzyOqEHvEk0)
 101 about why it's `mem=932M` instead of `mem=958M`.
 102
 103
 104 Cross Compiling Kernel for ARM on x86
 105 -------------------------------------
 106 Jailhouse need to be compiled with kernel objects. Thus we first need a copy of
 107 kernel source code and compile it.
 108
 109 Jailhouse requires Kernel Version >= 3.19. Here, we'll use Kernel version 4.3.3
 110 with patch provided by Bananian team.
 111
 112 We'll cross compile on a x86 machine for faster compilation. On the compiling
 113 machine,
 114 * Obtaining Kernel source code & patches for bananapi, and jailhouse
 115 ```bash
 116 $ sudo apt-get update && sudo apt-get install -y git
 117 $ cd ~
 118 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
 119 $ git clone https://github.com/Bananian/bananian.git
 120 $ git clone https://github.com/siemens/jailhouse.git
 121 ```
 122
 123 * Obtaining cross compiling tool-chain from [Linaro Official site](http://www.linaro.org/downloads/)
 124 ```bash
 125 #Download the recommended cross-toolchain from Linaro
 126
 127 $ cd ~
 128 $ wget https://releases.linaro.org/components/toolchain/binaries/latest-5/arm-linux-gnueabihf/gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf.tar.xz
 129 $ tar -xf gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf.tar.xz
 130
 131 #Update environment path
 132 $ export PATH=$PATH:$(pwd)/gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf/bin
 133 ```
 134
 135 * Apply patches and Setup config
 136 ```bash
 137 $ cd ~/linux-stable
 138 $ git checkout v4.3.3
 139 $ for i in ../bananian/kernel/4.3.3/patches/*; do patch -p1 < ; done
 140
 141 #Copy config from jailhouse/ci directory
 142 $ cp -av ../jailhouse/ci/kernel-config-banana-pi .config
 143
 144 $ sudo apt-get update && sudo apt-get install -y build-essential libncurses5 libncurses5-dev
 145 $ make ARCH=arm menuconfig
 146 #Enable FUSE under "File systems", needed for file transfer via sshfs
 147 ```
 148
 149 * Compile Kernel
 150 ```bash
 151 $ sudo apt-get update && sudo apt-get install -y u-boot-tools
 152 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j8 uImage modules dtbs LOADADDR=40008000
 153 ```
 154
 155
 156 Installing Kernel
 157 -----------------
 158 Here we choose to mount compiled kernel-source directory on BananaPi. Instead
 159 one can choose to transfer the directory that contains kernel source to
 160 BananaPi.
 161 ```bash
 162 #On Compiling machine,
 163 $ sudo apt-get update && sudo apt-get install -y sshfs
 164
 165 #On BananaPi,
 166 $ apt-get update && apt-get install -y sshfs make gcc
 167 $ mkdir ~/linux-src
 168 $ sshfs <remote user>@<remote ip address>:<linux source path> ~/linux-src
 169 $ cd ~/linux-src
 170 $ make modules_install
 171
 172 #Update U-boot partition
 173 $ mount /dev/mmcblk0p1 /boot
 174 $ mkdir /boot/dtb/
 175 $ cp -v arch/arm/boot/uImage /boot/uImage-next
 176 $ cp -v arch/arm/boot/dts/*.dtb /boot/dtb/
 177
 178 #now reboot
 179 $ reboot
 180 ```
 181
 182 Verify installation using `$ uname -r`, if the kernel is installed successfully,
 183 the bash command above should return `4.3.3-dirty`.
 184
 185
 186 Cross Compiling Jailhouse(w/ FreeRTOS-cell) for ARM on x86
 187 -----------------------------------------------------
 188 * Check the need of upgrading `make`.
 189 Jailhouse require make>=3.82 to build it, we might need to upgrade `make`.
 190 ```bash
 191 #On Compiling machine,
 192 $ make --version
 193
 194 #If make>=3.82, skip this part and continue with "Building Jailhouse"
 195 $ sudo apt-get update && sudo apt-get install -y checkinstall
 196 $ wget http://ftp.gnu.org/gnu/make/make-3.82.tar.bz2 -O ~/Downloads/make-3.82.tar.bz2
 197 $ cd ~ && tar -xf ~/Downloads/make-3.82.tar.bz2
 198 $ cd make-3.82
 199 $ ./configure --prefix=/usr
 200 $ make
 201 $ sudo checkinstall make install
 202 ```
 203
 204 * Building Jailhouse (mainly for FreeRTOR as a cell)
 205 ```bash
 206 #On Compiling Machine,
 207 $ sudo apt-get update && sudo apt-get install -y python-mako device-tree-compiler
 208 $ cd ~
 209 $ git clone https://github.com/siemens/freertos-cell
 210 $ cp -av ~/freertos-cell/jailhouse-configs/bananapi.c ~/jailhouse/configs/bananapi.c
 211 $ cp -av freertos-cell/jailhouse-configs/bananapi-freertos-demo.c ~/jailhouse/configs/
 212
 213 #Copy the configuration header file before building
 214 $ cp -av ~/jailhouse/ci/jailhouse-config-banana-pi.h ~/jailhouse/hypervisor/include/jailhouse/config.h
 215 $ cd ~/jailhouse
 216 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- KDIR=../linux-stable
 217 ```
 218
 219 * Build FreeRTOS-cell
 220 ```bash
 221 $ cd ~/freertos-cell
 222 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- KDIR=../linux-stable
 223 ```
 224
 225
 226 Installing Jailhouse
 227 --------------------
 228 Here we mount `/` of BananaPi on `~/bpi_root` on our compiling Machine,
 229 ```bash
 230 #On Compiling Machine,
 231 $ mkdir ~/bpi_root
 232 $ sshfs root@<bananapi_ip_addr>:/ ~/bpi_root
 233 $ cd ~/jailhouse
 234 $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
 235      KDIR=../linux-stable DESTDIR=~/bpi_root install
 236 ```
 237
 238
 239 Testing Jailhouse On BananaPi
 240 -----------------------------
 241 To test jailhouse on BananaPi, we would need the `*.cell` file where could be
 242 located in the cross-compiled `jailhouse` & `freertos-cell` directory.
 243
 244 Here we transfer these two directory from the compiling machine to BananaPi
 245 using sftp.
 246 ```bash
 247 #On Compiling Machine,
 248 $ cd ~ && tar -zcf jailhouse-compiled.tar.gz jailhouse freertos-cell
 249 $ sftp root@<bananapi_ip_addr>
 250 sftp > put jailhouse-compiled.tar.gz
 251 sftp > quit
 252
 253 #On BananaPi,
 254 $ cd ~ && tar -xf jailhouse-compiled.tar.gz
 255 $ modprobe jailhouse
 256
 257 #If nothing goes wrong, you should see jailhouse using a `$ lsmod`
 258 $ jailhouse enable ~/jailhouse/configs/bananapi.cell
 259 $ jailhouse cell create ~/jailhouse/configs/bannapi-freertos-demo.cell
 260 $ jailhouse cell load FreeRTOS ~/freertos-cell/freertos-demo.bin
 261 $ jailhouse cell start FreeRTOS
 262
 263 #Jailhouse and FreeRTOS cell has been started, you should able to get some
 264 #output from the FreeRTOS demo application on the second serial interface of
 265 #BananaPi.
 266
 267 #After making sure all things works well, turn off jailhouse using command below
 268 $ jailhouse cell shutdown FreeRTOS
 269 $ jailhouse cell destroy FreeRTOS
 270 $ jailhouse disable
 271 $ rmmod jailhouse
 272 ```
 273
 274
 275 References
 276 ----------
 277 1. https://github.com/cyng93/jailhouse/blob/master/README.md
 278 2. https://github.com/siemens/freertos-cell/blob/master/README.md
 279 3. https://groups.google.com/forum/#!topic/jailhouse-dev/LzyOqEHvEk0
 280 4. https://fossapc.hackpad.com/Jailhouse-on-Banana-Pi-with-FreeRTOS-as-Cell-EZaCw8OEynM
 281 5. https://embedded2015.hackpad.com/ep/pad/static/P8aM30iQ3hm
 282 6. https://paper.dropbox.com/doc/Banana-Pi-and-jailhouse-6CoZ4Cgyom22Gy3uH9g7e