docs/0_Getting_Started/2_Building_AGL_Image/5_1_x86_Emulation_and_Hardware.md

   1 ---
   2 title: Building for x86 (Emulation and Hardware)
   3 ---
   4
   5 Building an image for emulation allows you to simulate your
   6 image without actual target hardware.
   7
   8 This section describes the steps you need to take to build the
   9 AGL demo image for emulation using either Quick EMUlator (QEMU) or
  10 VirtualBox, and later the same image can be used to boot any hardware.
  11
  12 ## 1. Making Sure Your Build Environment is Correct
  13
  14 The
  15 "[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)"
  16 section presented generic information for setting up your build environment
  17 using the `aglsetup.sh` script.
  18 If you are building the AGL demo image for emulation, you need to specify some
  19 specific options when you run the script:
  20
  21 **Qt based IVI demo :**
  22
  23 ```sh
  24 $ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-demo agl-devel
  25 $ echo '# reuse download directories' >> $AGL_TOP/site.conf
  26 $ echo 'DL_DIR = "$HOME/downloads/"' >> $AGL_TOP/site.conf
  27 $ echo 'SSTATE_DIR = "$AGL_TOP/sstate-cache/"' >> $AGL_TOP/site.conf
  28 $ ln -sf $AGL_TOP/site.conf conf/
  29 ```
  30
  31 **HTML5 based IVI demo :**
  32
  33 ```sh
  34 $ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-demo agl-devel agl-profile-graphical-html5
  35 $ echo '# reuse download directories' >> $AGL_TOP/site.conf
  36 $ echo 'DL_DIR = "$HOME/downloads/"' >> $AGL_TOP/site.conf
  37 $ echo 'SSTATE_DIR = "$AGL_TOP/sstate-cache/"' >> $AGL_TOP/site.conf
  38 $ ln -sf $AGL_TOP/site.conf conf/
  39 ```
  40
  41 The "-m" option specifies the "qemux86-64" machine.
  42 The list of AGL features used with script are appropriate for development of
  43 the AGL demo image suited for either QEMU or VirtualBox.
  44
  45 ## 2. Using BitBake
  46
  47 Start the build using the `bitbake` command.
  48
  49 **NOTE:** An initial build can take many hours depending on your
  50 CPU and and Internet connection speeds.
  51 The build also takes approximately 100G-bytes of free disk space.
  52
  53 **Qt based IVI demo :**
  54 The target is `agl-demo-platform`.
  55
  56 ```sh
  57 $ time bitbake agl-demo-platform
  58 ```
  59
  60 By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`:
  61
  62 ```sh
  63 <build_directory>/tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.vmdk.xz
  64
  65 $ export IMAGE_NAME=agl-demo-platform-qemux86-64.vmdk.xz
  66 ```
  67
  68 **HTML5 based IVI demo :**
  69 The target is `agl-demo-platform-html5`.
  70
  71 ```sh
  72 $ time bitbake agl-demo-platform-html5
  73 ```
  74
  75 By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`:
  76
  77 ```sh
  78 <build_directory>/tmp/deploy/images/qemux86-64/agl-demo-platform-html5-qemux86-64.vmdk.xz
  79
  80 $ export IMAGE_NAME=agl-demo-platform-html5-qemux86-64.vmdk.xz
  81 ```
  82
  83 ## 3. Deploying the AGL Demo Image
  84
  85 Deploying the image consists of decompressing the image and then
  86 booting it using either QEMU, VirtualBox or physical system.
  87
  88 **3.1 QEMU**
  89
  90 Depending on your Linux distribution, use these commands to install QEMU:
  91
  92 If you built your image with bitbake, you can now just use the ``runqemu`` wrapper, after sourcing `agl-init-build-env` inside the build-dir :
  93
  94 For this example :
  95
  96 ```sh
  97 $ source $AGL_TOP/master/qemux86-64/agl-init-build-env
  98 ```
  99
 100 In general :
 101
 102 ```sh
 103 $ source $AGL_TOP/<release-branch-name>/<build-dir>/
 104 ```
 105
 106 And further use `runqemu` to boot the image :
 107
 108 ```sh
 109 $ runqemu tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.qemuboot.conf kvm serialstdio slirp publicvnc audio
 110 ```
 111
 112 If you need to run it outside of the bitbake environment or need special settings for
 113 hardware pass-through using `qemu` :
 114
 115
 116 **NOTE:** if you have created an AGL crosssdk, it will contain a
 117 QEMU binary for the build host.
 118 This SDK QEMU binary does not support graphics.
 119 Consequently,  you cannot use it to boot the AGL image and
 120 need to call your host's qemu binary instead.
 121
 122 **NOTE:** the VM images need UEFI in the emulator to boot. Thus you need
 123 to install the necessary files with below commands (ovmf).
 124
 125 If your build host is running
 126 [Arch Linux](https://www.archlinux.org/), use the following commands:
 127
 128 ```sh
 129 sudo pacman -S qemu ovmf
 130 export OVMF_PATH=/usr/share/ovmf/x64/OVMF_CODE.fd
 131 ```
 132
 133 If your build host is running Debian or Ubuntu, use the following commands:
 134
 135 ```sh
 136 sudo apt-get install qemu-system-x86 ovmf
 137 export OVMF_PATH=/usr/share/ovmf/OVMF.fd
 138 ```
 139
 140 If you build host is running Fedora, use the following commands:
 141
 142 ```sh
 143 sudo yum install qemu qemu-kvm edk2-ovmf
 144 export OVMF_PATH=/usr/share/edk2/ovmf/OVMF_CODE.fd
 145 ```
 146
 147 **Note:**
 148
 149 Once QEMU is installed, boot the image with KVM support:
 150
 151 ```sh
 152 qemu-system-x86_64 -enable-kvm -m 2048 \
 153     -bios ${OVMF_PATH} \
 154     -hda ${IMAGE_NAME} \
 155     -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt \
 156     -vga virtio -show-cursor \
 157     -device virtio-rng-pci \
 158     -serial mon:stdio -serial null \
 159     -soundhw hda \
 160     -net nic \
 161     -net user,hostfwd=tcp::2222-:22
 162 ```
 163
 164 **NOTE:** KVM may not be supported within a virtualized environment such as
 165 VirtualBox. This is indicated by the qemu command above giving the error
 166 message `Could not access KVM kernel module: No such file or directory` or
 167 the kernel log output contains the error message `kvm: no hardware support`.
 168 The image can be booted in such an environment by removing `-enable-kvm` from
 169 the qemu command line, however this will result in lower perfromance within
 170 the AGL demo.
 171
 172 **3.2 VirtualBox**
 173
 174 Once VirtualBox is installed, follow these steps to boot the image:
 175
 176   1. Install and set up [Virtual Box](https://www.virtualbox.org/wiki/Linux_Downloads).
 177
 178   2. Extract the vmdk file :
 179
 180     ```sh
 181     cd tmp/deploy/images/qemux86-64
 182     xz -d ${IMAGE_NAME}
 183     ```
 184
 185   3. Configure virtual box for AGL :
 186     - Click on `New` or `Add`.
 187     - Enter Name as `agl-demo`.
 188     - Type as `Linux`.
 189     - Version as `Other Linux (64-bit)`, click on `Next`.
 190     ![vbox-step-1](images/vbox-1.png)
 191     - Select Memory size. Recommended is `2048 MB`, click on `Next`.
 192     ![vbox-step-2](images/vbox-2.png)
 193     - Click on `Use an existing virtual hard disk file`, and select the extracted `agl-demo-platform-qemux86-64.vmdk.xz` or `<html5-image?>` file, click on `Create`.
 194     ![vbox-step-3](images/vbox-3.png)
 195     - Go to `Settings`, and into `System`. Select `Chipset : IHC9`. Check on `Enable EFI (special OSes only)` and click on `OK`.
 196     ![vbox-step-4](images/vbox-4.png)
 197     - Go to `Storage`, and change the attribute to `Type : AHCI` and click on `OK`.
 198     ![vbox-step-5](images/vbox-5.png)
 199     - Click on `Start`.
 200     - For troubleshooting, you can refer [here](https://lists.automotivelinux.org/g/agl-dev-community/message/8474).
 201
 202 **3.3 x86 physical system**
 203
 204   **NOTE :** UEFI enabled system is required.
 205
 206   1. Extract the image into USB drive :
 207
 208     ```sh
 209     $ cd tmp/deploy/images/qemux86-64
 210     $ lsblk
 211     $ sudo umount <usb_device_name>
 212     $ xzcat agl-demo-platform-qemux86-64.wic.xz | sudo dd of=<usb_device_name> bs=4M
 213     $ sync
 214     ```
 215
 216   2. Boot from USB drive on the x86 system.