docs/1_Getting_Started/2_Building_AGL_Image/A_Virtio.md

   1 ---
   2 title: Building for virtio
   3 ---
   4
   5 Virtio is a standartized interface for implementing virtual I/O devices:
   6
   7 * Russell, Rusty. "virtio: towards a de-facto standard for virtual I/O devices." ACM SIGOPS Operating Systems Review 42.5 (2008): 95-103.
   8
   9 This section describes the steps you need to take to build the AGL demo image
  10 for virtio "platform". Later, the same image can be run on various emulators or
  11 hypervisors that provide virtio devices, for example, QEMU aarch64 emulation on
  12 PC, QEMU/KVM aarch64 virtualization on AGL Reference Hardware, etc.
  13
  14 Below, AGL minimal image and Qt based IVI demo are used as example, but
  15 similiarly one can run HTML5 based demos, cluster demo, or other AGL images.
  16
  17 ## 1. Making Sure Your Build Environment is Correct
  18
  19 The
  20 "[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)"
  21 section presented generic information for setting up your build environment
  22 using the `aglsetup.sh` script.
  23 If you are building the AGL demo image for virtio platform, you need to specify
  24 some specific options when you run the script:
  25
  26 ```sh
  27 $ source meta-agl/scripts/aglsetup.sh -m virtio-aarch64 -b build-virtio-aarch64 agl-demo
  28 ```
  29
  30 The "-m" option specifies the "virtio-aarch64" machine.
  31
  32 The "-b" option sets custom build directory instead of default "build".
  33
  34 The "-f" option might be added to override previously available configuration.
  35 By default, if there were already configuration files in build directory, they
  36 will not be overriden, as result, aglsetup.sh might not have desired effect.
  37
  38 ## 2. Using BitBake
  39
  40 This section shows the `bitbake` command used to build the AGL image.
  41
  42 Start the build using the `bitbake` command.
  43
  44 **AGL minimal image :**
  45 The target is `agl-image-minimal`.
  46
  47 ```sh
  48 $ bitbake agl-image-minimal
  49 ```
  50
  51 **Qt Based IVI demo :**
  52 The target is `agl-demo-platform`.
  53
  54 ```sh
  55 $ bitbake agl-demo-platform
  56 ```
  57
  58 ## 3. Deploying the AGL Demo Image
  59
  60 This subsection describes AGL virtio-aarch64 image deployment under virtio
  61 platform provided by QEMU aarch64 emulator on PC, or QEMU/KVM hypervisor on AGL
  62 Reference Hardware board.
  63
  64 **3.1 QEMU on PC**
  65
  66 If shell from which AGL was built is closed, or new shell is opened, then it is
  67 needed to re-initialize build environment:
  68
  69 ```sh
  70 $ source $AGL_TOP/build-virtio-aarch64/agl-init-build-env
  71 ```
  72
  73 And further use `runqemu` to boot the image :
  74
  75 ```sh
  76 $ runqemu
  77 ```
  78
  79 **3.2 QEMU/KVM on AGL Reference Hardware**
  80
  81 Follow these steps to run virtual AGL on bare-metal AGL (AGL-in-AGL) on AGL Reference Hardware board:
  82
  83   1. Partition eMMC or SD-Card to have two partitions, at least 1 GiB each.
  84     Actually, can be less but just rounded up to have a nice number.
  85
  86   2. Flash AGL minimal image root file system to the second partition on SD-Card
  87     or eMMC.
  88
  89   3. Build AGL minimal image for AGL Reference Hardware.
  90
  91     ```sh
  92     source meta-agl/scripts/aglsetup.sh -m h3ulcb -b build-h3ulcb agl-refhw-h3
  93     ```
  94
  95     In `build-h3ulcb/conf/local.conf` add
  96
  97     ```
  98     AGL_DEFAULT_IMAGE_FSTYPES = "ext4"
  99     IMAGE_INSTALL_append = "qemu"
 100     ```
 101
 102     CAUTION: Calling aglsetup.sh with "-f" flag will remove above modification
 103     in "local.conf", so they will be needed to be re-applied.
 104
 105     Build image:
 106
 107     ```sh
 108     bitbake agl-image-minimal
 109     ```
 110
 111     Add virtio kernel to the AGL Reference Hardware Linux rootfs:
 112
 113     ```sh
 114     cp build-virtio-aarch64/tmp/deploy/images/virtio-aarch64/Image build-h3ulcb/tmp/work/h3ulcb-agl-linux/agl-image-minimal/1.0-r0/rootfs/linux2
 115     bitbake agl-image-minimal -c image_ext4 -f
 116     bitbake agl-image-minimal -c image_complete
 117     ```
 118
 119     Flash root file system to the first partition on SD-Card or eMMC.
 120
 121   4. Boot AGL Reference Hardware board using Linux located on the first partition of SD-Card or eMMC.
 122
 123   5. Run QEMU from Linux 1 command line
 124
 125     ```sh
 126     qemu-system-aarch64 \
 127       -machine virt \
 128       -cpu cortex-a57 \
 129       -m 2048 \
 130       -serial mon:stdio \
 131       -global virtio-mmio.force-legacy=false \
 132       -drive id=disk0,file=/dev/mmcblk0p2,if=none,format=raw \
 133       -device virtio-blk-device,drive=disk0 \
 134       -object rng-random,filename=/dev/urandom,id=rng0 \
 135       -device virtio-rng-device,rng=rng0 \
 136       -nographic \
 137       -kernel /linux2
 138       -append 'root=/dev/vda rw mem=2048M'
 139     ```
 140
 141     NOTE: mmcblk0p2 above is used for when root file system is flashed on eMMC.
 142     In case of SD-Card, mmcblk1p2 has to be used.
 143
 144   6. It is possible to exit from QEMU using monitor commands. Enter "Ctrl+a h" for help.
 145
 146 Know issue: to enable hardware virtualization using KVM, option `-enable-kvm`
 147 could be added to QEMU command line, but it fails with:
 148
 149 ```
 150 qemu-system-aarch64: kvm_init_vcpu failed: Invalid argument
 151 ```