1Full Build and Installation Example 2=================================== 3 4This document shows the entire build and installation procedure for ACRN 5on a Debian/Ubuntu based distribution via apt package management only. 6 7Prerequisites used in this example: 8 9- `Maxtang AXWL10 <http://www.maxtangpc.com/AXSeriesEmbeddedPCs/140.html>`__ Whiskey Lake based Industrial PC 10- `Ubuntu 22.04 LTS server (Jammy Jellyfish) <https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso>`__ 11 12Remark: This guide only serves as an example and may deviate in certain 13steps depending on the chosen distribution. It has also been 14successfully applied for: 15 16- `Intel NUC7i7DNHE <https://ark.intel.com/content/www/us/en/ark/products/130393/intel-nuc-kit-nuc7i7dnhe.html>`__ Kaby Lake based PC using `Debian 10 (Buster <https://cdimage.debian.org/cdimage/archive/10.12.0/amd64/iso-cd/debian-10.12.0-amd64-netinst.iso>`__ 17- `Siemens Simatic IPC227G <https://mall.industry.siemens.com/mall/en/WW/Catalog/Products/10416195>`__ Elkhart Lake based Industrial PC using `Debian 11 (Bullseye) <https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-11.3.0-amd64-netinst.iso>`__ 18- `TTTech MFN 100 <https://www.tttech-industrial.com/wp-content/uploads/TTTech-Industrial_MFN-100.pdf>`__ Apollo Lake based Industrial PC using `Ubuntu 20.04 LTS server (Focal Fossa) <https://releases.ubuntu.com/20.04/ubuntu-20.04.4-live-server-amd64.iso>`__ 19 20Table of Contents 21----------------- 22 231. `Basic installation on target <#basic-installation-on-target>`__ 242. `Build the ACRN kernel for the Service 25 VM <#build-the-acrn-kernel-for-the-service-vm>`__ 263. `Build & Deploy ACRN Debian 27 Packages <#build--deploy-acrn-debian-packages>`__ 284. `ACRN Package Reconfiguration <#acrn-package-reconfiguration>`__ 295. `ACRN Removal <#acrn-removal>`__ 30 31Basic installation on target 32---------------------------- 33 34- Use the install ISO for basic installation of your distribution 35- optional for Ubuntu: remove cloud-init and snap, reconfigure netplan to get faster boot times (we’re rebooting often!) 36- optional for Ubuntu: enable grub menu in ``/etc/default/grub``: 37 38 - Comment out ``GRUB_TIMEOUT_STYLE=hidden`` -> 39 ``#GRUB_TIMEOUT_STYLE=hidden`` 40 - Set a reasonable timeout: ``GRUB_TIMEOUT=0`` -> ``GRUB_TIMEOUT=3`` 41 - When finished update grub config: 42 43 :: 44 45 root@target:~# update-grub 46 47- optional: enable serial console for grub in ``/etc/default/grub`` 48 (can be used on otherwise headless systems): 49 50 - Add to or edit in ``/etc/default/grub``: 51 52 :: 53 54 GRUB_TERMINAL=“console serial” 55 GRUB_SERIAL_COMMAND=“serial –unit=0 –speed=115200 –word=8 –parity=no –stop=1” 56 57 - When finished update grub config: 58 59 :: 60 61 root@target:~# update-grub 62 63 - Remark: Choose an appropriate legacy serial port: ``–unit=0 <-> 64 ttyS0``, see `GRUB Manual <https://www.gnu.org/software/grub/manual/grub/html_node/Serial-terminal.html>`__ 65 66 - Verify by connecting a serial terminal to the target. On reboot 67 the grub menu should be displayed: 68 69 :: 70 71 GNU GRUB version 2.06 72 73 +----------------------------------------------------------------------------+ 74 |*Ubuntu | 75 | Advanced options for Ubuntu | 76 | UEFI Firmware Settings | 77 | | 78 | | 79 | | 80 | | 81 | | 82 | | 83 | | 84 | | 85 +----------------------------------------------------------------------------+ 86 87 Use the ^ and v keys to select which entry is highlighted. 88 Press enter to boot the selected OS, `e' to edit the commands 89 before booting or `c' for a command-line. ESC to return 90 previous menu. 91 92- optional: enable root ssh access on target and deploy your public 93 keys for easy install access 94 95- Prepare local APT repository for install: 96 97 :: 98 99 root@target:~# mkdir /apt 100 101Build the ACRN kernel for the Service VM 102---------------------------------------- 103 104Since we need at least the proper acrn kernel module providing the 105services needed, building the appropriate ACRN enabled kernel for the 106target’s service vm is required. 107 108Recommendation: Using a docker container to build the kernel keeps your 109development host clean and avoids polluting it with any additional 110packages. Nevertheless, if you are brave, you can do the following stuff 111on your development host directly! 112 113- Prepare working directory on the dev host: 114 115 :: 116 117 me@dev-host:~$ mkdir -p ~/acrn-work 118 me@dev-host:~$ cd ~/acrn-work 119 120- Shallow clone the latest acrn-kernel: 121 122 :: 123 124 me@dev-host:~/acrn-work$ git clone -b master --depth 1 https://github.com/projectacrn/acrn-kernel.git 125 126- Now, optionally fire up the build container and mount the work 127 directory: 128 129 :: 130 131 me@dev-host:~/acrn-work$ docker run -it --rm -v $(pwd):/acrn-work debian:bullseye-slim 132 133- Make sure you have the kernel build requirements installed: 134 135 :: 136 137 root@9af58fa7aeb2:/# apt-get update 138 root@9af58fa7aeb2:/# apt-get install -y libssl-dev build-essential bison flex dwarves kernel-wedge bc rsync kmod cpio git libelf-dev lz4 libncurses-dev 139 140- Prepare the kernel config: I add FB support here to be able to use 141 Linux virtual consoles ;-) 142 143 :: 144 145 root@9af58fa7aeb2:/# cd /acrn-work/acrn-kernel 146 root@9af58fa7aeb2:/acrn-work/acrn-kernel# cp kernel_config_service_vm .config 147 root@9af58fa7aeb2:/acrn-work/acrn-kernel# echo "CONFIG_FB=y" >> .config 148 root@9af58fa7aeb2:/acrn-work/acrn-kernel# echo "CONFIG_FRAMEBUFFER_CONSOLE=y" >> .config 149 root@9af58fa7aeb2:/acrn-work/acrn-kernel# echo "CONFIG_FRAMEBUFFER_CONSOLE_DETECT_PRIMARY=y" >> .config 150 root@9af58fa7aeb2:/acrn-work/acrn-kernel# make olddefconfig 151 152- Compile the kernel; this takes a while, maybe good time for a coffee 153 break? 154 155 :: 156 157 root@9af58fa7aeb2:/acrn-work/acrn-kernel# make -j $(nproc) deb-pkg 158 159 The resulting kernel packages are located in ``/acrn-work`` or 160 ``~/acrn-work`` on the development host, respectively. 161 162- Exit the helper container and copy the new kernel package to the 163 target: 164 165 :: 166 167 root@9af58fa7aeb2:/acrn-work/acrn-kernel# exit 168 me@dev-host:~/acrn-work$ scp ~/acrn-work/linux-image-*-acrn-service-vm_*.deb root@target:/apt/ 169 170- I recommend installing the new kernel immediately and reboot the 171 target although we have not yet deployed any ACRN packages. This 172 ensures/verifies you can go back to a non-acrn boot easily if 173 something fails: 174 175 :: 176 177 root@target:~# apt update -y 178 root@target:~# apt install -y /apt/linux-image-*-acrn-service-vm_*.deb 179 root@target:~# reboot 180 181- On target distributions with a newer default kernel than 5.10 182 (e.g.Ubuntu Jammy, Debian Sid) you have to choose the ACRN kernel 183 manually in grub menu, since always the newest kernel version is 184 selected as default: 185 186 - Choose ``Advanced options <..>`` first, then select the new ACRN 187 kernel: 188 189 :: 190 191 GNU GRUB version 2.06 192 193 +----------------------------------------------------------------------------+ 194 | Ubuntu, with Linux 5.15.0-27-generic | 195 | Ubuntu, with Linux 5.15.0-27-generic (recovery mode) | 196 |*Ubuntu, with Linux 5.10.106-acrn-service-vm | 197 | Ubuntu, with Linux 5.10.106-acrn-service-vm (recovery mode) | 198 | | 199 | | 200 | | 201 | | 202 | | 203 | | 204 | | 205 +----------------------------------------------------------------------------+ 206 207 Use the ^ and v keys to select which entry is highlighted. 208 Press enter to boot the selected OS, `e' to edit the commands 209 before booting or `c' for a command-line. ESC to return 210 previous menu. 211 212- Verify the correct kernel has been booted: 213 214 :: 215 216 root@target:~# uname -a 217 Linux target 5.10.106-acrn-service-vm #1 SMP PREEMPT Mon May 2 15:54:32 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux 218 219- **IMPORTANT** (for all distributions with newer kernel, i.e. >=5.12): 220 221 Linux kernel versions since 5.12 officially contain the ACRN 222 Hypervisor Service Module and are detected as *ACRN capable* if the 223 module is enabled. Nevertheless, the version of ACRN HSM provided in 224 upstream kernels is not (yet) compatible with ACRN 3.0 and thus will 225 fail! Please remove the distribution’s original kernel (5.15 in case 226 of Ubuntu jammy) to avoid any issues when booting such a kernel with 227 ACRN 3.x: 228 229 - Find out the exact version of the original image: 230 231 :: 232 233 root@target:~# dpkg -l 'linux-image*' 234 Desired=Unknown/Install/Remove/Purge/Hold 235 | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend 236 |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) 237 ||/ Name Version Architecture Description 238 +++-======================================-==========================-============-=======================================> 239 un linux-image <none> <none> (no description available) 240 ii linux-image-5.10.106-acrn-service-vm 5.10.106-acrn-service-vm-1 amd64 Linux kernel, version 5.10.106-acrn-ser> 241 ii linux-image-5.15.0-27-generic 5.15.0-27.28 amd64 Signed kernel image generic 242 ii linux-image-generic 5.15.0.27.30 amd64 Generic Linux kernel image 243 un linux-image-unsigned-5.15.0-27-generic <none> <none> (no description available) 244 245 - E.g., we find ``5.15.0-27-generic`` here, so purge all respective 246 packages (image, modules, …): 247 248 :: 249 250 root@target:~# apt purge '*5.15.0-27-generic*' 251 252 - Verify there is only the acrn-kernel installed now: 253 254 :: 255 256 root@target:~# dpkg -l 'linux-image*' 257 Desired=Unknown/Install/Remove/Purge/Hold 258 | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend 259 |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) 260 ||/ Name Version Architecture Description 261 +++-====================================-==========================-============-=========================================> 262 ii linux-image-5.10.106-acrn-service-vm 5.10.106-acrn-service-vm-1 amd64 Linux kernel, version 5.10.106-acrn-servi> 263 264 - Remark: Removing the distribution’s default kernel is not required 265 whenever the ACRN kernel is detected as the most recent kernel! 266 267Build & Deploy ACRN Debian Packages 268----------------------------------- 269 270- Clone acrn-hypervisor (with debian packaging commits included, once 271 the changes are merged) 272 273 :: 274 275 me@dev-host:~/acrn-work$ git clone -b master --depth 1 https://github.com/projectacrn/acrn-hypervisor.git 276 me@dev-host:~/acrn-work$ cd acrn-hypervisor 277 278- Build the ACRN Debian packages (for Ubuntu jammy in this example) 279 280 :: 281 282 me@dev-host:~/acrn-work/acrn-hypervisor$ rm -rf build/jammy DISTRO=jammy VENDOR=ubuntu debian/docker/acrn-docker-build.sh --git-ignore-branch 283 284 The ACRN Debian/Ubuntu packages are then located in 285 ~/acrn-work/acrn-hypervisor/build/jammy 286 287- Copy these packages to the target: 288 289 :: 290 291 me@dev-host:~/acrn-work/acrn-hypervisor$ scp build/jammy/* root@target:/apt/ 292 293- On target add the local apt repository and update the repository 294 cache: 295 296 :: 297 298 root@target:~# echo "deb [trusted=yes] file:/apt ./" > /etc/apt/sources.list.d/acrn-local.list 299 root@target:~# echo "deb-src [trusted=yes] file:/apt ./" >> /etc/apt/sources.list.d/acrn-local.list 300 root@target:~# apt update -y 301 302- Install ACRN and optionally its tools (for debugging and tracing 303 purposes). **Always select the correct board and scenario!** I 304 recommend to start with the ``shared`` scenario. 305 306 :: 307 308 root@target:~# DEBIAN_FRONTEND=readline apt install -y acrn-system acrn-tools 309 < .. skipped .. > 310 Configuring acrn-hypervisor 311 --------------------------- 312 313 Define the board ACRN will be running on. Selecting the wrong board might render your board unusable! 314 315 1. cfl-k700-i7 2. kontron-COMe-mAL10 3. nuc11tnbi5 4. nuc7i7dnh 5. simatic-ipc227g 6. tgl-vecow-spc-7100-Corei7 7. whl-ipc-i5 316 317 ACRN hypervisor board selection 7 318 319 Define the appropriate VM configuration (aka scenario) for the ACRN hypervisor. 320 321 1. partitioned 2. shared 3. hybrid 4. hybrid_rt 322 323 ACRN hypervisor scenario selection 2 324 325 < .. skipped .. > 326 root@target:~# reboot 327 328- ACRN should boot the service VM flawlessly! Verify ACRN started 329 properly: 330 331 :: 332 333 root@target:~# dmesg | grep Hypervisor 334 [ 0.000000] Hypervisor detected: ACRN 335 root@target:~# systemctl status acrnd acrn-lifemngr 336 ● acrnd.service - ACRN manager daemon 337 Loaded: loaded (/lib/systemd/system/acrnd.service; enabled; vendor preset: enabled) 338 Active: active (running) since Fri 2022-05-06 10:20:29 UTC; 2min 48s ago 339 Main PID: 570 (acrnd) 340 Tasks: 3 (limit: 36031) 341 Memory: 436.0K 342 CPU: 932ms 343 CGroup: /system.slice/acrnd.service 344 └─570 /usr/bin/acrnd -t 345 346 May 06 10:20:29 target systemd[1]: Started ACRN manager daemon. 347 348 ● acrn-lifemngr.service - ACRN lifemngr daemon 349 Loaded: loaded (/lib/systemd/system/acrn-lifemngr.service; enabled; vendor preset: enabled) 350 Active: active (running) since Fri 2022-05-06 10:20:29 UTC; 2min 48s ago 351 Main PID: 568 (acrn-lifemngr) 352 Tasks: 17 (limit: 36031) 353 Memory: 1.1M 354 CPU: 1.167s 355 CGroup: /system.slice/acrn-lifemngr.service 356 └─568 /usr/bin/acrn-lifemngr 357 358 May 06 10:20:29 target systemd[1]: Started ACRN lifemngr daemon. 359 360- Remarks: 361 362 - ``acrn-tools`` provides additional services: ``acrnlog``, 363 ``acrnprobe`` and ``usercrash``. ``acrnlog`` is only started 364 successfully if you specified a respective ``hvlog`` setting in 365 the ``bootargs`` of your scenario which then are added the 366 kernel’s parameters in the grub configuration. This is not the 367 case in this example (``whl-ipc-i5:shared``). 368 - To start a VM, the respective launch scripts are also provided in 369 ``/usr/share/acrn/launch-scripts/<board>/<scenario>``. Just 370 provide your VM image (e.g. YaaG.img) and use the respective 371 script! 372 - There is no networking bridge (acrn-br0) created automatically 373 during install, since this heavily depends on the network tools 374 used for the respective target distribution (e.g. netplan) and/or 375 the respective backend (NetworkManager, systemd-networkd, ..) and 376 might break your network setup. So, if needed, please configure 377 the required network items (e.g. acrn-br0) according to your 378 system needs! 379 380ACRN Package Reconfiguration 381---------------------------- 382 383To reconfigure the board/scenario settings use (here an example usable 384on a simple line terminal - ``DEBIAN_FRONTEND=readline``): 385 386:: 387 388 root@target:~# DEBIAN_FRONTEND=readline dpkg-reconfigure acrn-hypervisor 389 Configuring acrn-hypervisor 390 --------------------------- 391 392 Define the board ACRN will be running on. Selecting the wrong board might render your board unusable! 393 394 1. cfl-k700-i7 2. kontron-COMe-mAL10 3. nuc11tnbi5 4. nuc7i7dnh 5. simatic-ipc227g 6. tgl-vecow-spc-7100-Corei7 7. whl-ipc-i5 395 396 ACRN hypervisor board selection 7 397 398 Define the appropriate VM configuration (aka scenario) for the ACRN hypervisor. 399 400 1. partitioned 2. shared 3. hybrid 4. hybrid_rt 401 402 ACRN hypervisor scenario selection 2 403 404**Remember: Always choose the appropriate board/scenario!** 405 406ACRN Removal 407------------ 408 409If you want to remove ACRN from your system completely, use: 410 411:: 412 413 root@target:~# apt purge -y acrn-system acrn-tools; apt autoremove --purge 414 415Remember: The system still uses the ACRN specific kernel, so you 416eventually have to re-install the distribution’s default kernel, reboot 417and then remove the ACRN kernel: Here for the Ubuntu example: 418 419:: 420 421 root@target:~# apt install linux-image-generic 422 root@target:~# reboot 423 424Choose the new kernel in grub menu, again via 425``Advanced options <..>``): 426 427:: 428 429 GNU GRUB version 2.06 430 431 +----------------------------------------------------------------------------+ 432 |*Ubuntu, with Linux 5.15.0-27-generic | 433 | Ubuntu, with Linux 5.15.0-27-generic (recovery mode) | 434 | Ubuntu, with Linux 5.10.106-acrn-service-vm | 435 | Ubuntu, with Linux 5.10.106-acrn-service-vm (recovery mode) | 436 | | 437 | | 438 | | 439 | | 440 | | 441 | | 442 | | 443 +----------------------------------------------------------------------------+ 444 445 Use the ^ and v keys to select which entry is highlighted. 446 Press enter to boot the selected OS, `e' to edit the commands 447 before booting or `c' for a command-line. ESC to return 448 previous menu. 449 450Finally remove the unused acrn-kernel: 451 452:: 453 454 root@target:~# apt purge linux-image-*-acrn-service-vm 455 456This completes removing ACRN from your system. 457 458-- Helmut Buchsbaum <helmut.buchsbaum@opensource.tttech-industrial.com> 459Sat, 06 May 2022 18:21:44 +0200 460 461