	Xvisor on BeagleBoard-xM (or OMAP3) using SD Booting

This section of readme explains how to build & run Xvisor on real hardware
BeagleBoard-xM using SD booting feature of OMAP3 SOC.

By default, Xvisor for BeagleBoard supports Realview-PB-A8 guest so we will
show how to run Basic Firmware (and/or Linux) on Realview-PB-A8 guest.

We need to add 2 images in boot partition of SD card that is shipped with
BeagleBoard-xM:
 1) U-Boot compatible Xvisor binary and DTBs (uvmm.bin).
 2) Disk image containing guest binaries (disk.img).

Following are the steps to create these images and then boot Xvisor on
Beagleboard-xM using U-Boot-2011.03 or higher:

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

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

  [3. Configure Xvisor for Beagleboard (or OMAP3)]
  # make ARCH=arm generic-v7-defconfig

  [4. Build Xvisor and DTBs, this creates vmm.bin]
  # make

  [5. Make U-Boot compatible uvmm.bin for use with bootm command]
  # mkimage -A arm -O linux -T kernel -C none -a 0x88000000 -e 0x88000000 -n Xvisor -d build/vmm.bin build/uvmm.bin

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

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

  [8. Configure Linux in build directory]
  # sed -i 's/0xff800000UL/0xff000000UL/' arch/arm/include/asm/pgtable.h
  # cp arch/arm/configs/realview_defconfig arch/arm/configs/tmp-realview-pb-a8_defconfig
  # <xvisor_source_directory>/tests/common/scripts/update-linux-defconfig.sh -p arch/arm/configs/tmp-realview-pb-a8_defconfig -f <xvisor_source_directory>/tests/arm32/realview-pb-a8/linux/linux_extra.config
  # make O=<linux_build_directory> ARCH=arm tmp-realview-pb-a8_defconfig

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

  [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. Extract patched Linux kernel image]
  # ${CROSS_COMPILE}objcopy -O binary <linux_build_directory>/vmlinux <linux_build_directory>/arch/arm/boot/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/common/busybox/README.md for creating rootfs.img using BusyBox)

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

  [14. Create disk image for Xvisor with Guest Linux and 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/realview-pb-a8
  # dtc -q -I dts -O dtb -o ./build/disk/images/arm32/realview-pb-a8-guest.dtb ./tests/arm32/realview-pb-a8/realview-pb-a8-guest.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 ./tests/arm32/realview-pb-a8/xscript/one_guest_pb-a8.xscript ./build/disk/boot.xscript
  # cp -f <linux_build_directory>/arch/arm/boot/Image ./build/disk/images/arm32/realview-pb-a8/Image
  # cp -f <linux_build_directory>/arch/arm/boot/dts/arm-realview-pba8.dtb ./build/disk/images/arm32/realview-pb-a8/arm-realview-pba8.dtb
  # cp -f <busybox_rootfs_directory>/rootfs.img ./build/disk/images/arm32/realview-pb-a8/rootfs.img
  # genext2fs -B 1024 -b 32768 -d ./build/disk ./build/disk.img
  OR
  [14. Create disk image for Xvisor with 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/realview-pb-a8
  # dtc -q -I dts -O dtb -o ./build/disk/images/arm32/realview-pb-a8-guest.dtb ./tests/arm32/realview-pb-a8/realview-pb-a8-guest.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/basic/nor_flash.list ./build/disk/images/arm32/realview-pb-a8/nor_flash.list
  # cp -f ./tests/arm32/realview-pb-a8/xscript/one_guest_pb-a8.xscript ./build/disk/boot.xscript
  # genext2fs -B 1024 -b 32768 -d ./build/disk ./build/disk.img

  [15. Make U-boot compatible initrd for use with bootm command]
  # mkimage -A arm -O linux -T ramdisk -a 0x89000000 -n "Xvisor ramdisk" -d build/disk.img build/udisk.img

  [16. Unplug SD card from BeagleBoard-xM and plug it on your development machine]

  [17. Mount boot partition (or partition 0) of SD card on your development machine]

  [18. Copy uvmm.bin, DTB, and disk image to boot partition of SD card]
  # cp -f build/uvmm.bin <path_to_mounted_boot_partition_of_sd_card>
  # cp -f build/arch/arm/board/generic/dts/ti/omap3-beagle-xm.dtb <path_to_mounted_boot_partition_of_sd_card>
  # cp -f build/udisk.img <path_to_mounted_boot_partition_of_sd_card>

  [19. Unmount boot partition (or partition 0) of SD card from your development machine]

  [20. Unplug SD card from your development machine and plug it back on BeagleBoard-xM]

  [21. Connect to serial port of BeagleBoard-xM using Putty or Minicom]

  [22. Power-up or Reset BeagleBoard-xM and press any key when U-Boot shows auto-boot count down]

  [23. Enabled MMC interface from U-Boot command line interface]
  OMAP3 beagleboard.org # mmc dev 0:0

  [24. Copy Xvisor from SD card to SDRAM]
  OMAP3 beagleboard.org # fatload mmc 0 0x80200000 uvmm.bin

  [25. Copy disk image from SD card to SDRAM]
  OMAP3 beagleboard.org # fatload mmc 0 0x8B000000 udisk.img

  [26. Copy DTB from SD card to SDRAM]
  OMAP3 beagleboard.org # fatload mmc 0 0x8A000000 omap3-beagle-xm.dtb

  [27. Jump into Xvisor after disabling MMU, interrupts, etc]
  OMAP3 beagleboard.org # bootm 0x80200000 0x8B000000 0x8A000000

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

  [29. Bind to virtual UART]
  XVisor# vserial bind guest0/uart0

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

  [31. 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)

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

  [33. 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)


	Xvisor on Linaro QEMU BeagleBoard (or OMAP3) using NAND Booting

This section of readme explains how to build & run Xvisor from nand-flash on
BeagleBoard emulated by QEMU Linaro.

By default, Xvisor for BeagleBoard supports Realview-PB-A8 guest so we will
show how to run Basic Firmware (and/or Linux) on Realview-PB-A8 guest.

We need to have 4 images to create the nand-flash image:
 1) X-loader for OMAP3 (2nd stage bootloader for OMAP3).
 2) U-Boot-2011.03 binary for OMAP3 (3rd stage bootloader).
 3) U-Boot compatible Xvisor binary and DTBs (uvmm.bin).
 4) Disk image containing guest binaries (disk.img).

The steps to create these images and boot Xvisor on Beagleboard QEMU are as
follows:

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

  [2. Download and build U-Boot-2011.03 from source - this creates u-boot.bin]
  # wget ftp://ftp.denx.de/pub/u-boot/u-boot-2011.03.tar.bz2
  # tar -xvf u-boot-2011.03.tar.bz2
  # cd u-boot-2011.03
  # make omap3_beagle_config
  # make
  # cd ..

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

  [4. Configure Xvisor for Beagleboard (or OMAP3)]
  # make ARCH=arm generic-v7-defconfig

  [5. Build Xvisor and DTBs, this creates vmm.bin]
  # make

  [6. Add uboot header to vmm.bin for use with bootm command]
  # mkimage -A arm -O linux -T kernel -C none -a 0x80008000 -e 0x80008000 -n Xvisor -d build/vmm.bin build/uvmm.bin

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

  [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
  # cp arch/arm/configs/realview_defconfig arch/arm/configs/tmp-realview-pb-a8_defconfig
  # <xvisor_source_directory>/tests/common/scripts/update-linux-defconfig.sh -p arch/arm/configs/tmp-realview-pb-a8_defconfig -f <xvisor_source_directory>/tests/arm32/realview-pb-a8/linux/linux_extra.config
  # make O=<linux_build_directory> ARCH=arm tmp-realview-pb-a8_defconfig

  [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 with Guest Linux and 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/realview-pb-a8
  # dtc -q -I dts -O dtb -o ./build/disk/images/arm32/realview-pb-a8-guest.dtb ./tests/arm32/realview-pb-a8/realview-pb-a8-guest.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 ./tests/arm32/realview-pb-a8/xscript/one_guest_pb-a8.xscript ./build/disk/boot.xscript
  # cp -f <linux_build_directory>/arch/arm/boot/Image ./build/disk/images/arm32/realview-pb-a8/Image
  # cp -f <linux_build_directory>/arch/arm/boot/dts/arm-realview-pba8.dtb ./build/disk/images/arm32/realview-pb-a8/arm-realview-pba8.dtb
  # cp -f <busybox_rootfs_directory>/rootfs.img ./build/disk/images/arm32/realview-pb-a8/rootfs.img
  # genext2fs -B 1024 -b 32768 -d ./build/disk ./build/disk.img
  OR
  [15. Create disk image for Xvisor with 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/realview-pb-a8
  # dtc -q -I dts -O dtb -o ./build/disk/images/arm32/realview-pb-a8-guest.dtb ./tests/arm32/realview-pb-a8/realview-pb-a8-guest.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/basic/nor_flash.list ./build/disk/images/arm32/realview-pb-a8/nor_flash.list
  # cp -f ./tests/arm32/realview-pb-a8/xscript/one_guest_pb-a8.xscript ./build/disk/boot.xscript
  # genext2fs -B 1024 -b 32768 -d ./build/disk ./build/disk.img

  [16. Make U-boot compatible initrd for use with bootm command]
  # mkimage -A arm -O linux -T ramdisk -a 0x81000000 -n "Xvisor ramdisk" -d build/disk.img build/udisk.img

  [17. Create a flat binary with all our binaries appended]
  # ./tools/scripts/memimg.py -a 0 -o build/beagle.img docs/arm/omap3-beagle-x-load-1.5.0.bin.ift@0x0 <path-to-u-boot-binary>/u-boot.bin@0x80000 build/uvmm.bin@0x280000 ./build/arch/arm/board/generic/dts/ti/omap3-beagle.dtb@0x680000 build/udisk.img@0x700000

  [18. Build the beagleboard nand-flash image from the flat binary created]
  # ./tools/bbflash/bb_nandflash.sh build/beagle.img build/beagle-nand.bin ./build/tools/bbflash/bb_nandflash_ecc

  [19. Launch QEMU Linaro]
  # qemu-system-arm -M beagle -m 512M -drive file=build/beagle-nand.bin,if=mtd -display none -serial stdio -s

  [20. Copy Xvisor from nand-flash to SDRAM]
  OMAP3 beagleboard.org # nand read 0x80200000 0x280000 0x200000

  [21. Copy disk image from nand-flash to SDRAM]
  OMAP3 beagleboard.org # nand read 0x84000000 0x700000 0x1000040

  [22. Copy Xvisor DTB from nand-flash to SDRAM]
  OMAP3 beagleboard.org # nand read 0x80800000 0x680000 0x10000

  [23. Jump into Xvisor after disabling MMU, interrupts, etc]
  OMAP3 beagleboard.org # bootm 0x80200000 0x84000000 0x80800000

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

  [25. Bind to virtual UART]
  XVisor# vserial bind guest0/uart0

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

  [27. 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)

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

  [29. 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)
