		Xvisor on QEMU (2.5) i.MX25 PDK Host

Note: This requires an up to date (at least 2.5) version of Qemu.

This readme explains how to build & run Xvisor for i.MX25 PDK on QEMU (2.5).

By default, Xvisor for i.MX25 PDK supports VersatilePB guest so we will
show how to run Basic Firmware on VersatilePB guest. For more info refer,
<xvisor_source>/tests/arm32/versatilepb/basic/README.

Please follow the steps below to build & run Basic Firmware on VersatilePB
guest with Xvisor running on QEMU i.MX25 PDK Host:

  [1. Build environment for Xvisor]
  # export CROSS_COMPILE=arm-linux-gnueabi-

  [2. GoTo Xvisor source directory]
  # cd <xvisor_source_directory>

  [3. Initialize Xvisor submodules]
  # git submodule init
  # git submodule update
  (Note: This is required to be done only once in freshly cloned xvisor source)

  [4. Configure Xvisor with Generic-v5 default settings]
  # make ARCH=arm generic-v5-defconfig

  [5. Build Xvisor and DTBs]
  # make

  [6. Build Basic Firmware]
  # make -C tests/arm32/versatilepb/basic

  [7. Copy defconfig to Linux build directory]
  # cp tests/arm32/versatilepb/linux/linux-<linux_version>_defconfig <linux_build_directory>/.config

  [8. GoTo Linux source directory]
  # cd <linux_source_directory>

  [9. Configure Linux in build directory]
  # sed -i 's/0xff800000UL/0xff000000UL/' arch/arm/include/asm/pgtable.h
  # make O=<linux_build_directory> ARCH=arm oldconfig

  [10. Build Linux in build directory]
  # make O=<linux_build_directory> ARCH=arm Image dtbs

  [11. Patch Linux kernel to replace sensitive non-priviledged instructions]
  # <xvisor_source_directory>/arch/arm/cpu/arm32/elf2cpatch.py -f <linux_build_directory>/vmlinux | <xvisor_source_directory>/build/tools/cpatch/cpatch32 <linux_build_directory>/vmlinux 0

  [12. Extract patched Linux kernel image]
  # ${CROSS_COMPILE}objcopy -O binary <linux_build_directory>/vmlinux <linux_build_directory>/arch/arm/boot/Image

  [13. Create BusyBox RAMDISK to be used as RootFS for Linux kernel]
  (Note: For subsequent steps, we will assume that your RAMDISK is located at <busybox_rootfs_directory>/rootfs.img)
  (Note: Please refer tests/common/busybox/README.md for creating rootfs.img using BusyBox)

  [14. GoTo Xvisor source directory]
  # cd <xvisor_source_directory>

  [15. Create disk image for Xvisor containing Guest Linux + Guest Basic Firmware]
  # mkdir -p ./build/disk/tmp
  # mkdir -p ./build/disk/system
  # cp -f ./docs/banner/roman.txt ./build/disk/system/banner.txt
  # cp -f ./docs/logo/xvisor_logo_name.ppm ./build/disk/system/logo.ppm
  # mkdir -p ./build/disk/images/arm32/versatilepb
  # ./build/tools/dtc/bin/dtc -I dts -O dtb -o ./build/disk/images/arm32/versatilepb.dtb ./tests/arm32/versatilepb/versatilepb.dts
  # cp -f ./build/tests/arm32/versatilepb/basic/firmware.bin.patched ./build/disk/images/arm32/versatilepb/firmware.bin
  # cp -f ./tests/arm32/versatilepb/linux/nor_flash.list ./build/disk/images/arm32/versatilepb/nor_flash.list
  # cp -f ./tests/arm32/versatilepb/linux/cmdlist ./build/disk/images/arm32/versatilepb/cmdlist
  # cp -f ./tests/arm32/versatilepb/xscript/one_guest_versatilepb.xscript ./build/disk/boot.xscript
  # cp -f <linux_build_directory>/arch/arm/boot/Image ./build/disk/images/arm32/versatilepb/Image
  # cp -f <linux_build_directory>/arch/arm/boot/dts/versatile-pb.dtb ./build/disk/images/arm32/versatilepb/versatile-pb.dtb
  # cp -f <busybox_rootfs_directory>/rootfs.img ./build/disk/images/arm32/rootfs.img
  # genext2fs -B 1024 -b 32768 -d ./build/disk ./build/disk.img
  OR
  [15. Create disk image for Xvisor containing only Guest Basic Firmware]
  # mkdir -p ./build/disk/tmp
  # mkdir -p ./build/disk/system
  # cp -f ./docs/banner/roman.txt ./build/disk/system/banner.txt
  # cp -f ./docs/logo/xvisor_logo_name.ppm ./build/disk/system/logo.ppm
  # mkdir -p ./build/disk/images/arm32/versatilepb
  # ./build/tools/dtc/bin/dtc -I dts -O dtb -o ./build/disk/images/arm32/versatilepb.dtb ./tests/arm32/versatilepb/versatilepb.dts
  # cp -f ./build/tests/arm32/versatilepb/basic/firmware.bin.patched ./build/disk/images/arm32/versatilepb/firmware.bin
  # cp -f ./tests/arm32/versatilepb/basic/nor_flash.list ./build/disk/images/arm32/versatilepb/nor_flash.list
  # cp -f ./tests/arm32/versatilepb/xscript/one_guest_versatilepb.xscript ./build/disk/boot.xscript
  # genext2fs -B 1024 -b 32768 -d ./build/disk ./build/disk.img

  [16. Launch QEMU]
  # qemu-system-arm -M imx25-pdk -m 512M -display none -serial stdio -kernel build/vmm.bin -dtb build/arch/arm/board/generic/dts/freescale/imx25-pdk.dtb -initrd build/disk.img

  [17. Kick Guest0 for starting Basic Firmware]
  XVisor# guest kick guest0

  [18. Bind to virtual UART0 of Linux Guest]
  XVisor# vserial bind guest0/uart0

  [19. Try few commands of Basic firmware or goto next step]
  [guest0/uart0] basic# hi
  [guest0/uart0] basic# hello
  [guest0/uart0] basic# help

  [20. Copy linux from NOR flash to RAM and start linux booting from RAM]
  [guest0/uart0] basic# autoexec
  (Note: "autoexec" is a short-cut command for executing commands from NOR flash)
  (Note: The <xvisor_source_directory>/tests/arm32/versatilepb/linux/cmdlist file
   which we have added to guest NOR flash contains set of commands for booting
   linux from NOR flash)

  [21. Wait for Linux prompt to come-up and then try out some commands]
  [guest0/uart0] / # ls

  [22. Enter character seqence 'ESCAPE+x+q" return to Xvisor prompt]
  [guest0/uart0] / #

  (Note: replace all <> brackets based on your workspace)
  (Note: some of the above steps will need to be adapted for other
   types of ARM host)
  (Note: for more info on your desired ARM host refer docs/arm/)
  (Note: you are free to change the ordering of above steps based
   on your workspace)
