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