====== XEN HVM Guest Support ======
  * Student: Bei Guan (bguan@)
  * Mentor: Justin T. Gibbs (gibbs@)

===== Project description =====

This project optimizes the I/O performance of %%FreeBSD%% as a Xen HVM %%DomU%%. It provides a USB front-end driver and a SCSI front-end driver to %%FreeBSD%% Xen HVM %%DomU%%. With these drivers, %%FreeBSD%% %%DomU%% can access the USB and SCSI devices provided by Xen instead of that emulated by QEMU. It improves the performance of reading and writing data to the devices.

With the GENERIC config, %%FreeBSD%% Xen %%DomU%% accesses to the USB device by Qemu-dm USB passthrough supported by Xen. It needs to specify "usb=1" and "usbdevice='host:xxxx:yyyy'" in the %%DomU%%'s config file. It doesn't require backed driver in Dom0 and front driver in %%DomU%%. However, this method is low performance. A USB front-end driver is part of the Xen para-virtualization mechanism. It forwards the USB I/O request from the %%DomU%% to the USB back-end driver in Dom0, and then the back-driver dispatches the request to the native USB device driver, which will access to the physical USB device and give the response to the USB back-end driver. At last, USB front-end driver can receive the result of the device request. This mechanism is known as PVUSB. PVUSB will replace the device emulated by Qemu and extremely improve the performance of USB I/O access.

The SCSI device access in %%FreeBSD%% %%DomU%% is supported through device emulated by QEMU currently. The project is very similar to the USB front-end driver. The para-virtualized SCSI driver is also known as PVSCSI. It can be used by a Xen PV or HVM guest to passthrough the SCSI device, such as tape drives, scanners, printers and CD drives. PVSCSI works like the PVUSB. The front-end driver forwards the SCSI device I/O request from the %%DomU%% to SCSI back-end driver in Dom0. And then, it receives the result from the SCSI device forwarded by back-end driver

===== Approach to solving the problem =====

We break the problem into smaller parts that we will solved.

  - Define the data structures and function interfaces of USB/SCSI front-end driver.
  - Provide a USB/SCSI front-end driver to %%FreeBSD%% %%DomU%% configured with XENHVM to replace the emulated device provided by Xen Qemu.
  - Provide some test cases to show the USB/SCSI front-end driver works well. Provide some data to show the performance improvement for %%FreeBSD%% accessing to the USB devices and SCSI devices, such as reading and writing operations.

===== Deliverables =====

Features to implement in this project.
  * Submit the USB/SCSI front-end driver code for testing.
  * Release the USB/SCSI front-end driver for both 32bit and 64bit %%FreeBSD%% Xen %%DomU%%.
  * Submit the experience result for the performance improvement.
  * Submit some related document.

===== Milestones =====

An initiatory milestones are made here. We will adjust it according to the progress of this project in reality.

  * June 17: Start of coding 
  * July 7: Submit the USB front-end driver code for testing.
  * July 21: Release the USB front-end driver for both 32bit and 64bit %%FreeBSD%% Xen %%DomU%% and the experience result for the performance improvement.
  * July 29-August 2: Mid-term Evaluations 
  * August 4: Submit the SCSI front-end driver code for testing.
  * August 18: Release the SCSI front-end driver for both 32bit and 64bit %%FreeBSD%% Xen %%DomU%% and the experience result for the performance improvement.
  * August 19 - September 10: Finish all the above work, if necessary. And provide the related documentation.
  * September 16: End of coding (soft) 
  * September 23: End of coding (hard) 

The USB front-end driver is still under development in later several months.

===== Test Plan =====

A rough test plan is made as the following.
a) Test for USB Front-End Driver
  - Test the driver can be loaded when the %%FreeBSD%% %%DomU%% boots with XENHVM kernel.
  - Test it can write and read the USB disk in the %%FreeBSD%% %%DomU%%.
  - Use a benchmark to test the write/read speed for accessing to the USB disk.

b) Test for SCSI Front-End Driver
  - Test the driver can be loaded when the %%FreeBSD%% %%DomU%% boots with XENHVM kernel.
  - Test it can write and read the CD drive in the %%FreeBSD%% %%DomU%%.
  - Use a benchmark to test the write/read speed for accessing to the CD derives.

===== The Code =====

  * [[https://socsvn.freebsd.org/socsvn/soc2013/bguan/|Code repository is available here]]
  * [[https://socsvn.freebsd.org/socsvn/soc2013/bguan/head/sys/dev/xen/usbfront/|Main USB front code is under here]]

===== Useful links =====
  * %%FreeBSD%% Part [[http://svn.freebsd.org/base/release/9.1.0/sys/|FreeBSD Source Code]]

  * Xen Part [[http://wiki.xen.org/wiki/Xen_USB_Passthrough|Xen USB Passthrough]]\\  [[http://wiki.xen.org/wiki/Paravirtualized_SCSI|Xen SCSI Passthrough]]

  * USB Related [[http://www.usb.org/developers/docs/|USB Specification]]\\