		Linux-3.0.4 on 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

The Linux-3.0.4 version of Linux already contains a support for Realivew
PB-A8 Board. We can use this kernel unmodified to run it as a xvisor guest.
We have provided a patch for linux-3.0.4 kernel but that is for disabling
devices (which we don't emulate in xvisor) and for supportting early printk.
We have also provided a Realview PB-A8 defconfig for linux-3.0.4 kernel
for ease in building kernel. To obtain Linux-3.0.4 sources visit the 
following site: http://www.kernel.org

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

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

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

  [3. Configure Xvisor with Realview PB-A8 default settings]
  # make ARCH=arm pb-a8-defconfig 
  (Note: pb-a8-defconfig will select device tree configuration with only one preconfigured guest. For enabling two preconfigured guest use "make ARCH=arm menuconfig" after the above step to change the device tree configuration for two guests)

  [4. Build Xvisor]
  # make

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

  [6. Copy patch to Linux-3.0.4 source directory]
  # cp tests/arm32/pb-a8/linux-3.0.4/linux-3.0.4_realview_pba8.patch <linux-3.0.4_source_directory>

  [7. Copy defconfig to Linux-3.0.4 build directory]
  # cp tests/arm32/pb-a8/linux-3.0.4/linux-3.0.4_realview_pba8_defconfig <linux-3.0.4_build_directory>/.config

  [8. Copy defconfig to Busybox-1.19.2 source directory]
  # cp tests/arm32/pb-a8/linux-3.0.4/busybox-1.19.2_defconfig <busybox-1.19.2_source_directory>/.config

  [9. GoTo Linux-3.0.4 source directory]
  # cd <linux-3.0.4_source_directory>

  [10. Patch Linux-3.0.4 source]
  # patch -p1 <./linux-3.0.4_realview_pba8.patch

  [11. Configure Linux-3.0.4 in build directory]
  # make O=<linux-3.0.4_build_directory> ARCH=arm oldconfig

  [12. Build Linux-3.0.4 in build directory]
  # make O=<linux-3.0.4_build_directory> ARCH=arm zImage

  [13. Patch Linux-3.0.4 kernel to replace sensitive non-priviledged instructions]
  # <xvisor_source_directory>/arch/arm/cpu/arm32/elf2cpatch.py -f <linux-3.0.4_build_directory>/vmlinux .text.head .init .text | <xvisor_source_directory>/build/tools/cpatch/cpatch32 <linux-3.0.4_build_directory>/vmlinux 0

  [14. Build Linux-3.0.4 in build directory to reflect changes in kernel image]
  # make O=<linux-3.0.4_build_directory> ARCH=arm zImage

  [15. Patch Linux-3.0.4 compressed kernel to replace sensitive non-priviledged instructions]
  # <xvisor_source_directory>/arch/arm/cpu/arm32/elf2cpatch.py -f <linux-3.0.4_build_directory>/arch/arm/boot/compressed/vmlinux .text.head .init .text | <xvisor_source_directory>/build/tools/cpatch/cpatch32 <linux-3.0.4_build_directory>/arch/arm/boot/compressed/vmlinux 0

  [16. Create final compressed kernel image]
  # $(CROSS_COMPILE)objcopy -O binary <linux-3.0.4_build_directory>/arch/arm/boot/compressed/vmlinux <linux-3.0.4_build_directory>/arch/arm/boot/zImage

  [17. GoTo Busybox-1.19.2 source directory]
  # cd <busybox-1.19.2_source_directory>

  [18. Configure Busybox-1.19.2 source]
  # make oldconfig

  [19. Build Busybox-1.19.2 RootFS]
  # make install

  [20. Change ownership of installed RootFS]
  # sudo chown -R root:root ./_install

  [21. Create RootFS image]
  # fakeroot /bin/bash -c "genext2fs -b 3096 -N 1024 -D <xvisor_source_directory>/tests/arm32/pb-a8/linux-3.0.4/busybox-1.19.2_dev.txt -d ./_install <linux-3.0.4_build_directory>/rootfs.img"

  [22. GoTo Linux-3.0.4 build directory]
  # cd <linux-3.0.4_build_directory>

  [23. Create xvisor_linux-3.0.4_qemu.img for running it on QEMU]
  # <xvisor_source_directory>/tools/scripts/memimg.py -a 0x70010000 -o xvisor_linux-3.0.4_qemu.img <xvisor_source_directory>/build/vmm.bin@0x70010000 <xvisor_source_directory>/build/tests/arm32/pb-a8/basic/arm_test.bin.patched@0x70800000 ./arch/arm/boot/zImage@0x70900000 ./rootfs.img@0x70C00000
  (Note: If we have two preconfigured guests then we will have to add images for second guest. This can be done by appending following arguments to the above command: "<xvisor_source_directory>/build/tests/arm32/pb-a8/basic/arm_test.bin.patched@0x71000000 ./arch/arm/boot/zImage@0x71100000 ./rootfs.img@0x71400000")

  [24. Launch QEMU 0.14.xx or higher]
  # qemu-system-arm -M realview-pb-a8 -display none -serial stdio -kernel ./xvisor_linux-3.0.4_qemu.img

  [25. Kick Guest0 for starting Basic Test]
  XVisor# guest kick 0

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

  [27. Copy zImage binary from NOR flash to DDR]
  [guest0/uart0] arm-test# copy 0x70400000 0x40100000 0x200000

  [28. Copy roofs.img binary from NOR flash to DDR]
  [guest0/uart0] arm-test# copy 0x71000000 0x40400000 0x400000

  [29. Start linux kernel]
  [guest0/uart0] arm-test# start_linux 0x70400000 0x71000000 0x400000

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

  [31. 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 0.14.xx or higher. 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 change ordering of the above step based on your workspace)

