	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 Test on Realview-PB-A8 guest. For more info on Basic Test
refer <xvisor_source>/tests/arm32/realview-pb-a8/basic/README.

We need to add 2 images in boot partition of micro-SD card that is shipped with
BeagleBoard-xM:
 1) U-Boot compatible Xvisor binary (uvmm.bin). Newer u-boot enables MMU and 
    interrupts. These are disabled before booting linux when bootm command is 
    used, so a simple go command will not work. We add the u-boot header to 
    make it appear as a linux image.
 2) Patched guest binary 
    (Patched Realview-pb-a8 Basic Test image, arm_test.bin.patched)

Following steps to create these images and then boot Xvisor on Beagleboard-xM:

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

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

  [3. Configure Xvisor with Beagleboard (or OMAP3) host default settings]
  # make ARCH=arm omap3-beagle-defconfig 

  [4. Build Xvisor, 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 ARM Basic Test for Realview PB-A8 Guest, this creates arm_test.bin.patched]
  # make -C tests/arm32/realview-pb-a8/basic
  
  [7. Unplug micro-SD card from BeagleBoard-xM and plug it on your development machine]

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

  [9. Copy uvmm.bin to boot partition of micro-SD card]
  # cp uvmm.bin <path_to_mounted_boot_partition_of_micro_sd_card>

  [10. Copy arm_test.bin.patched to boot partition of micro-SD card]
  # cp build/tests/arm32/realview-pb-a8/basic/arm_test.bin.patched <path_to_mounted_boot_partition_of_micro_sd_card>/arm.bin

  (Note: If you want additional images like cmdlist, patched zImage, 
   rootfs.img etc. then you should copy these images to boot partition
   of micro-SD card after above step.)
  (Note: For more info on images required for linux on Realview-PB-A8 guest 
   refer to <xvisor_source>/tests/arm32/realview-pb-a8/linux/README.)

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

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

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

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

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

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

  [17. Copy Guest image from micro-SD card to SDRAM]
  OMAP3 beagleboard.org # fatload mmc 0 0x89000000 arm.bin

  (Note: If you want to load additional images like cmdlist, patched zImage, 
   rootfs.img, etc. from micro-SD card then load these images at address 
   0x89100000 or higher using fatload command of U-Boot after above step.)
  (Note: The default DTS used by Xvisor for BeagleBoard has one pre-configured
   Realview-PB-A8 guest. The NOR flash of the guest is 16 MB in size and is 
   mapped to 0x89000000 host physical address. The guest boots from start of 
   NOR flash so we put Basic Test arm.bin at start of NOR flash and rest of 
   the guest images like cmdlist, patched zImage, rootfs.img, etc. after it.)
  (Note: For e.g. if we want to load cmdlist, patched zImage and rootfs image
   into guest NOR flash then use:
   OMAP3 beagleboard.org # fatload mmc 0 0x890FF000 cmdlist
   OMAP3 beagleboard.org # fatload mmc 0 0x89100000 zImage
   OMAP3 beagleboard.org # fatload mmc 0 0x89400000 rootfs.img )

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

  [19. Kick Guest for starting Basic Test]
  XVisor# guest kick 0

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

  [21. Say 'hi' to ARM Basic Test]
  [guest0/uart0] arm-test# hi

  (Note: If you had linux images loaded in guest NOR flash then instead of 
   above step you can start booting linux,
   arm-test# copy 0x70400000 0x40100000 0x300000
   arm-test# copy 0x71000000 0x40400000 0x600000
   arm-test# start_linux 0x70400000 0x71000000 0x600000 
   OR
   arm-test# autoexec)

  [22. Say 'hello' to ARM Basic Test]
  [guest0/uart0] arm-test# hello

  [23. Check various commands of ARM Basic Test]
  [guest0/uart0] arm-test# help

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

  (Note: replace all <> brackets 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 2.02 or higher. 

By default, Xvisor for BeagleBoard supports Realview-PB-A8 guest so we will
show how to run Basic Test on Realview-PB-A8 guest. For more info on Basic Test
refer <xvisor_source>/tests/arm32/realview-pb-a8/basic/README.

We need to have 4 images to create the nand-flash image:
 a) X-loader for OMAP3 (2nd stage bootloader for OMAP3)
 b) U-Boot binary for OMAP3 (3rd stage bootloader)
 c) U-Boot compatible Xvisor binary (uvmm.bin). Newer U-Boot enables MMU and 
    interrupts. These are disabled before booting linux when bootm command is 
    used, so a simple go command will not work. We add the U-Boot header to 
    make it appear as a linux image.
 d) Patched guest binary 
    (Patched Realview pb-a8 Basic Test image, arm_test.bin.patched)

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

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

  (Note: Follow step 2 to get the prebuilt X-loader and U-Boot binaries, or 
   steps 3-4 to build those images from source)
  
  [2. Download X-loader and U-Boot binary]
  # wget http://qemu-omap3.googlecode.com/files/image-v0.01.tar.bz2
  # mkdir prebuilt-images/
  # tar -xvjf image-v0.01.tar.bz2 -C prebuilt-images/

  (Note: we would not need the uImage extracted in the above step)

  [3. Download and build X-loader from source - this creates x-load.bin.ift]
  # git clone git://gitorious.org/x-load-omap3/mainline.git
  # cd mainline
  # make omap3530beagle_config
  # make x-load.bin.ift
  # cd ..

  [4. Download and build U-Boot from source - this creates u-boot.bin]
  # git clone git://git.denx.de/u-boot.git
  # cd u-boot
  # make omap3_beagle_config
  # make omap3_beagle
  # cd ..

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

  [6. Configure Xvisor with Beagleboard (or OMAP3) host default settings]
  # make ARCH=arm omap3-beagle-defconfig 

  [7. Build Xvisor, this creates vmm.bin]
  # make

  [8. Add uboot header to vmm.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

  [9. Build ARM Basic Test for Realview PB-A8 Guest, this creates arm_test.bin.patched]
  # make -C tests/arm32/pb-a8/basic

  [10. Copy the X-loader and U-Boot binaries (from step 2 or 3-4) into Xvisor build-directory]
  # cp <path-to-x-loader-binary>/x-load.bin.ift <path-to-u-boot-binary>/u-boot.bin build/

  [11. Create a flat binary with all our binaries appended]
  # ./tools/scripts/memimg.py -a 0 -o build/beagle.img build/x-load.bin.ift@0x0 build/u-boot.bin@0x80000 build/uvmm.bin@0x280000 build/tests/arm32/pb-a8/basic/arm_test.bin.patched@0x380000

  (Note: If you want additional images like cmdlist, patched zImage, 
   rootfs image, etc. then you should above step to include them in 
   build/beagle.img. For instance cmdlist, patched zImage, and rootfs.img
   can be appended to build/beagle.img using following additional arguments
   <xvisor_source>/tests/arm32/pb-a8/linux/cmdlist@0x47F000
   <linux_build_dir>/arch/arm/boot/zImage@0x480000
   <linux_build_dir>/rootfs.img@0x780000 
   arguments appended to above step.)
  (Note: For more info on images required for linux on Realview-PB-A8 guest 
   refer to <xvisor_source>/tests/arm32/pb-a8/linux/README.)

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

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

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

  [15. Copy Guest image from nand-flash to SDRAM]
  OMAP3 beagleboard.org # nand read 0x89000000 0x380000 0x100000

  (Note: If you want to load additional images like cmdlist, patched zImage, 
   rootfs.img, etc. from NAND flash then load these images at address 0x89100000
   or higher using fatload command of U-Boot after above step.)
  (Note: The default DTS used by Xvisor for BeagleBoard has one pre-configured
   Realview-PB-A8 guest. The NOR flash of the guest is 16 MB in size and is 
   mapped to 0x89000000 host physical address. The guest boots from start of 
   NOR flash so we put Basic Test at start of NOR flash and rest of the guest
   images like cmdlist, patched zImage, rootfs.img, etc. after Basic Test arm.bin)
  (Note: For e.g. if we want to load cmdlist, patched zImage and rootfs image
   into guest NOR flash then use,
   OMAP3 beagleboard.org # nand read 0x890FF000 0x47F000 0x1000
   OMAP3 beagleboard.org # nand read 0x89100000 0x480000 0x300000
   OMAP3 beagleboard.org # nand read 0x89400000 0x780000 0x600000 )

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

  [16. Kick Guest for starting Basic Test]
  XVisor# guest kick 0

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

  [18. Say 'hi' to ARM Basic Test]
  [guest0/uart0] arm-test# hi

  (Note: If you had linux images loaded in guest NOR flash then instead of 
   then instead of above step you can start booting linux,
   arm-test# copy 0x70400000 0x40100000 0x300000
   arm-test# copy 0x71000000 0x40400000 0x600000
   arm-test# start_linux 0x70400000 0x71000000 0x600000
   OR
   arm-test# autoexec)

  [19. Say 'hello' to ARM Basic Test]
  [guest0/uart0] arm-test# hello

  [20. Check various commands of ARM Basic Test]
  [guest0/uart0] arm-test# help

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

  (Note: replace all <> brackets based on your workspace)

