		Linux on Xvisor Realview-PB-A8 Guest

Linux is a computer operating system which is based on free and open source
software. the underlying source code can be used, freely modified, and
redistributed, both commercially and non-commercially, by anyone under
licenses such as the GNU General Public License. For more information on
Linux read the wiki page http://en.wikipedia.org/wiki/Linux

Linux already contains a support for Realview-PB-A8 Board. We can use
this kernel unmodified to run it as a xvisor guest. We have also provide
Realview-PB-A8 defconfig for various linux kernel versions for ease in
building kernel. To obtain Linux kernel sources visit the following
url: http://www.kernel.org

Follow the steps below to build & run Linux kernel with Busybox RootFS on
Realview-PB-A8 Guest with Xvisor running on QEMU Realview-PB-A8 Host:

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

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

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

  [4. Build Xvisor & DTBs]
  # make; make dtbs

  [5. Build Basic Firmware]
  # make -C tests/arm32/realview-pb-a8/basic

  [6. Copy defconfig to Linux build directory]
  # cp tests/arm32/realview-pb-a8/linux/linux-<linux_version>_realview_pba8_defconfig <linux_build_directory>/.config

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

  [8. Configure Linux in build directory]
  # make O=<linux_build_directory> ARCH=arm oldconfig

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

  [10. 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

  [11. Build Linux in build directory to reflect changes in kernel image]
  # make O=<linux_build_directory> ARCH=arm Image

  [12. 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/arm32/common/busybox/README for creating rootfs.img using BusyBox)

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

  [14. Create disk image for Xvisor]
  # mkdir -p ./build/disk/images/arm32/realview-pb-a8
  # ./build/tools/dtc/dtc -I dts -O dtb -o ./build/disk/images/arm32/realview-pb-a8.dtb ./tests/arm32/realview-pb-a8/realview-pb-a8.dts
  # cp -f ./build/tests/arm32/realview-pb-a8/basic/firmware.bin.patched ./build/disk/images/arm32/realview-pb-a8/firmware.bin
  # cp -f ./tests/arm32/realview-pb-a8/linux/nor_flash.list ./build/disk/images/arm32/realview-pb-a8/nor_flash.list
  # cp -f ./tests/arm32/realview-pb-a8/linux/cmdlist ./build/disk/images/arm32/realview-pb-a8/cmdlist
  # cp -f <linux_build_directory>/arch/arm/boot/Image ./build/disk/images/arm32/realview-pb-a8/Image
  # cp -f <busybox_rootfs_directory>/rootfs.img ./build/disk/images/arm32/rootfs.img
  # genext2fs -B 1024 -b 16384 -d ./build/disk ./build/disk.img

  [15. Create qemu.img for running it on QEMU]
  # ./tools/scripts/memimg.py -a 0x70010000 -o build/qemu.img build/vmm.bin@0x70010000 build/disk.img@0x71000000

  [16. Launch QEMU 1.7.xx or higher]
  # qemu-system-arm -M realview-pb-a8 -m 256M -display none -serial stdio -kernel build/qemu.img -dtb build/arch/arm/board/generic/dts/realview/pb-a8/one_guest_pb-a8.dtb

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

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

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

  (Note: replace all <> brackets based on your workspace)
  (Note: the above steps assumes Xvisor running on Realview-PB-A8 host
   emulated by QEMU. For other types of ARM host some of the above steps
   will need to be adapted for that specfic ARM host. 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)

