Red Hat Paravirtualized Xen Drivers for Windows(R)

These packages contains drivers for Microsoft Windows(R) operating systems
running as Xen guests on Red Hat Enterprise Linux.


Files:
------

README.txt                - This readme file
xenpv-win-32bit.exe       - Drivers for 32-bit Windows(R) Guests
xenpv-win-64bit.exe       - Drivers for 64-bit Windows(R) Guests
xenpv-win-32bit-debug.exe - Drivers for 32-bit Windows(R) Guests (debug)
xenpv-win-64bit-debug.exe - Drivers for 64-bit Windows(R) Guests (debug)


Driver Listing:
---------------

rhelscsi - This contains a paravirtualized SCSI Miniport driver that improves
           performance for accessing virtual disks.  This driver replaces the
           built in IDE driver on Windows guests.

rhelnet  - This contains a paravirtualized network driver to improve network
           performance.  This driver replaces the built-in network driver on
           Windows guests.


Supported Host Operating Systems:
---------------------------------

Red Hat Enterprise Linux 5.2 (x86_64 and i686)


Supported Guest Operating Systems:
----------------------------------

Windows(R) XP Service Pack 2 (x86)
Windows(R) XP (x64)
Windows(R) 2003 Server Service Pack 2 (x86 and x64)

Each of the above listed operating systems should have the latest hotfixes
and patches installed from Microsoft Windows(R) Update.

The drivers come in two different packages, depending on the guest operating
system's architecture type (32-bit or 64-bit).  32-bit Windows(R) operating 
systems should use the driver package with x86 in the file name.  64-bit 
Windows(R) operating systems should use the driver package with x64 in the
file name.


Known Issues:
-------------

* Booting to PV (tap:aio) disk devices is not presently supported.  The boot
  disk must be left as a non-PV (file/physical) device.  Secondary disks 
  installed on the guest may be either PV or non-PV.  The boot disk must be
  installed on the primary IDE channel as device 0 (target device in the
  domU configuration should be 'hda').

* After installation the rhelscsi device will be present but not enabled.
  The rhelnet device is only present when the rhelscsi device is enabled, so
  it will not be present until after rebooting.  The driver files for the 
  rhelnet device are present, but after rebooting the 'Add New Hardware Wizard'
  will appear prompting the user to install the rhelnet drivers.  Simply click
  through this dialog and the driver will be installed properly.

* If additional paravirtualized network devices are added after the PV drivers
  have been installed two new devices will appear in the Windows device manager:
  A Realtek NIC and a rhelnet NIC.  The Realtek NIC must be disabled in 
  Windows device manager for the rhelnet NIC to work correctly.

* After installation or uninstallation the installer will prompt for a reboot.
  Before the PV drivers will work correctly the guest must be rebooted.

* After the domain configuration file has been edited in libvirt, the domain
  must be restarted to pick up the changes.


Release Notes:
--------------
0.97.2 - Fixed save/restore functionality.

0.97.1 - Fixed issue that caused the drivers to need a second reboot on
         Windows XP platforms.  Now the drivers will properly work after 
         the first reboot following installation.

0.97 - Fixed issue that caused the drivers to fail on Windows(R) XP 32-bit
       systems.  Added support for hotplug add/remove of PV disks and NIC
       devices.

0.95 - Fix for issue where adding new PV disks causes the NIC device to 
       require re-installation.  Adding new PV disks now no longer forces a 
       NIC driver reinstall with the 'Add New Hardware Wizard'

0.94 - Fix for disk corruption issue when boot disk is a physical disk.
       The fix requires the rhelscsi driver to not activate until the
       first reboot following installation.  Because the rhelnet device
       is not present until after the rhelscsi device is enabled, this
       requires the rhelnet driver to be installed after rebooting.
       This is done via the 'Add New Hardware Wizard' dialog.

0.92 - Initial Build

Disabling/Enabling the Built Network and IDE Drivers:
-----------------------------------------------------

This installer automatically disables the built in network driver and device
0 on the primary IDE channel at the end of a successful installation.  The
boot disk must be a file or physical device and must be device 0 on the
primary IDE channel.  This is done by indicating that the target device for
the disk is 'hda'.

During uninstall of the drivers these devices are automatically re-enabled.
If for some reason the devices need to be enabled/disabled manually, the
installer provides two tools located at C:\Program Files\RedHat\XenPV that
can be used for this.

set-ide.exe - This utility enables or disables IDE devices
devcon.exe  - This utility can be used to disable the network driver

To disable device 0 on the primary IDE channel, run:

  set-ide.exe primary_ide_channel 0 disable

To re-enable device 0 on the primary IDE channel, run:

  set-ide.exe primary_ide_channel 0 enable

The set-ide command requires a reboot to take effect.

To disable the non-PV network driver, run:

  devcon.exe disable "PCI\VEN_10EC&DEV_8139"

To re-enable the non-PV network driver, run:

  devcon.exe enable "PCI\VEN_10EC&DEV_8139"

The enable/disable of the network device takes effect immediately, so a
reboot is not necessary following these commands.

In order for the PV network driver and disk driver to function correctly,
the non-PV network driver and device 0 on the primary IDE channel must be 
disabled.


Disable/Enable Red Hat PV Disk Driver:
--------------------------------------

The installer automatically enables the PV disk driver during the install.
During uninstallation the driver is removed but the device node will still
remain in the Windows(R) device manager after rebooting.  The device node
will appear with the name "PCI Device".

This will cause the "Add New Hardware Wizard" to appear.  This wizard can 
be exited by selecting the Cancel button.

To permanently disable the PV disk driver after an uninstall of the driver
package, scripts are provided in the C:\Program Files\RedHat\XenPV 
directory:

disableRedHatSCSIDriver.bat - This disables the PV disk driver
enableRedHatSCSIDriver.bat  - This enables the PV disk driver

After running the disable script the "PCI Device" in the device manager
will show up with a red X, indicating that it is disabled.

Before re-installing the drivers the device should be re-enabled using the
enableRedHatSCSIDriver.bat script.  Make sure that the red X is gone from
the device node before attempting to re-install the drivers using the
installer package.


Enabling the Paravirtualized Drivers for the Domain:
----------------------------------------------------

The PV disk and network devices must be enabled in the domain configuration
files.  The method of enabling these devices differs between the versions
of RHEL used.  In RHEL5.2 the configuration files are edited through libvirt
using the virsh utility.

By default the PV network driver is enabled in libvirt domain configuration
files.  Only the disk sections of the configuration file need to be
modified.

NOTE: In RHEL 5.2 only use the libvirt commands (virsh, virt-manager) to 
manipulate guest domains.  Use of the xm commands in RHEL5.2 may result in
the PV drivers not being enabled correctly.

Use the virsh tool from the command line to export a domain's configuration
like this:

# virsh dumpxml <domain> > config.xml

In the config.xml file look for sections like this:

    <disk type='file' device='disk'>
      <driver name='file'/>
      <source file='/var/lib/xen/images/disk2.img'/>
      <target dev='hdb'/>
    </disk>

And change them as follows:

    <disk type='file' device='disk'>
      <driver name='tap' type='aio'/>
      <source file='/var/lib/xen/images/disk2.img'/>
      <target dev='xvdb'/>
    </disk>

After editing the file, recreate the domain with:

# virsh define config.xml

NOTE: Only edit the disk entries for secondary disks.  Leave the primary boot
disk as a file disk device.  Booting to tap:aio disks is not yet supported.


Hotplugging PV Disks:
---------------------

Paravirtualized disks can be hotplugged using the virsh command, as follows:

virsh attach-disk --driver tap --subdriver aio <domain> <disk image file> <device node>

For example:

virsh attach-disk --driver tap --subdriver aio wxp32 /var/lib/xen/images/wxp32-2.img /dev/xvdb

To detach a disk dynamically, use the following command:

virsh detach-disk <domain> <device node>

For example:

virsh detach-disk wxp32 /dev/xvdb


