	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 on Realview-PB-A8 guest. For more info 
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 Firmware image, firmware.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 Basic Firmware for Realview-PB-A8 Guest, this creates firmware.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 firmware.bin.patched to boot partition of micro-SD card]
  # cp build/tests/arm32/realview-pb-a8/basic/firmware.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 Firmware 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 0x89600000 rootfs.img )

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

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

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

  [21. Say 'hi' to Basic Firmware]
  [guest0/uart0] basic# hi

  (Note: If you had linux images loaded in guest NOR flash then instead of 
   above step you can start booting linux,
   basic# copy 0x70008000 0x40100000 0x4F8000
   basic# copy 0x70500000 0x40600000 0x600000
   basic# start_linux 0x70008000 0x70500000 0x600000
   OR
   basic# autoexec)

  [22. Say 'hello' to Basic Firmware]
  [guest0/uart0] basic# hello

  [23. Check various commands of Basic Firmware]
  [guest0/uart0] basic# help

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

  (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. 

By default, Xvisor for BeagleBoard supports Realview-PB-A8 guest so we will
show how to run Basic Firmware on Realview-PB-A8 guest. For more info 
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 Firmware image, firmware.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 Basic Firmware for Realview-PB-A8 Guest, this creates firmware.bin.patched]
  # make -C tests/arm32/realview-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/realview-pb-a8/basic/firmware.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/realview-pb-a8/linux/cmdlist@0x47F000
   <linux_build_dir>/arch/arm/boot/zImage@0x480000
   <linux_build_dir>/rootfs.img@0x980000 
   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/realview-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]
  # 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 Firmware at start of NOR flash and rest of the 
   guest images like cmdlist, patched zImage, rootfs.img, etc. after Basic 
   Firmware 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 0x500000
   OMAP3 beagleboard.org # nand read 0x89600000 0x980000 0x600000 )

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

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

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

  [18. Say 'hi' to Basic Firmware]
  [guest0/uart0] basic# 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,
   basic# copy 0x70008000 0x40100000 0x4F8000
   basic# copy 0x70500000 0x40600000 0x600000
   basic# start_linux 0x70008000 0x70500000 0x600000
   OR
   basic# autoexec)

  [19. Say 'hello' to Basic Firmware]
  [guest0/uart0] basic# hello

  [20. Check various commands of Basic Firmware]
  [guest0/uart0] basic# help

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

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

