Skip to content

Home

Jump to bottom
blochl edited this page Jun 21, 2015 · 35 revisions

Table of Contents

About VirtHCK

VirtHCK is a set of Bourne shell scripts for running Microsoft HCK (Hardware Certification Kit) tests for variety of Windows drivers. It creates isolated virtual network environment for HCK Studio (Controller) and HCK Client virtual machines (VMs) running on top of QEMU-KVM and allows to run all kind of HCK tests in automated manner.

VirtHCK Initial Setup

  1. Create QEMU VM for Studio (Controller).
  2. Create two QEMU VM for VM clients, use HCK-Client1 prefix for first client image and HCK-Client2 for second one.
  3. Checkout VirtHCK to your root directory.
  4. Create images/ directory in your root directory and move the images created in p.1 p.2 into it.
  5. Update STUDIO_IMAGE/CLIENT1_IMAGE/CLIENT2_IMAGE variables in hck_setup.cfg.
  6. Run VirtHCK Setup by: sudo ./VirtHCK/hck.sh.
  7. Install Microsoft HCK Studio and Clients software according to Microsoft documentation Windows HCK Getting Started and following Checklist for a new client VM chapter of this document.

Directory tree

  • VirtHCK/ - Directory of all scripts, supposed to run in Linux environment.
  • VirtHCK/guest_tools/ - Directory for scripts required for Windows guests.
  • images/ - Directory where VM's images should be located.

Scripts Description

  • VirtHCK/hck.sh [st] [c1] [c2]
Main script for VirtHCK environment start up, starts up one Studio and two Client VMs. When started, shows current VirtHCK environment configuration and monitors VMs stratup. Could be executed with parameters which specifies VMs to run:
  • st - Start HCK Studio VM
  • c1 - Start HCK Client 1 VM
  • c2 - Start HCK Client 2 VM
  • VirtHCK/hck_setup.cfg
VirtHCK Setup Configuration File required by scripts for environment configuration and VM start up parameters, should be configured accordingly to required HCK setup.
Below are listed important configurable variables in order of appearance:
  1. UNIQUE_ID=[1-60] - Unique ID for current VirtHCK setup, used for creation of most environment instances like: virtual network bridges, virtual NIC MAC addresses, virtual machine UUIDs. Its very important to set this variable with unique number for each running VirtHCK setup in order to avoid system collisions.
  2. QEMU_BIN=[qemu-kvm] - QEMU application name.
  3. TEST_DEV_TYPE=[network|storage|bootstorage] - Defines VM hardware configuration for VirtHCK Clients:
    1. network - Creates Client VM setup with two VirtIO NICs connected by dedicated virtual network bridge.
    2. storage - Creates Client VM setup with VirtIO block device configured as secondary storage adapter. Usually used forVirtIO Block Device adapter's drivers installation.
    3. bootstorage - Creates Client VM setup with single VirtIO storage adapder, VM processes boot from it.
  4. VIDEO_TYPE=[VNC|SPICE] - Sets RDC protocol for VirtHCK VMs.
  5. STUDIO_IMAGE/CLIENT1_IMAGE/CLIENT2_IMAGE - Virtual Machines image names
  6. CLIENT_CPUS=[2|4] - Amount of CPU cores for each client VM, amount of two is recommended, in order to reduce payload on host, but some HCK test suits require at least 4 cores.
  7. CLIENT_MEMORY=[1G|2G|...] - Sets client's VM physical memory size.
  8. WORLD_NET_DEVICE=[e1000|rtl8139|virtio-net-pci] - Set type of NIC for Studio/Client VM by which it connected to Internet.
  9. CTRL_NET_DEVICE=[e1000|rtl8139|virtio-net-pci] - Set type of NIC for Studio/Client VM by which it attached to internal network dedicated for Studio-Client interconnection.
  10. STUDIO_EXTRA/CLIENT1_EXTRA/CLIENT2_EXTRA - Variables used for extra VM settings, like CD-ROM attachment, alternate BIOS image path, etc.
  11. SHARE_ON_HOST - A directory on the host machine that will be available as an SMB share on the guest HCK Controller and can be made available on the guest HCK Clients as well, by placing a file named USE_SHARE in it. The default location is: VirtHCK/SMB_SHARE. Setting SHARE_ON_HOST to false will disable the SMB share on all guests.
    • Notice, that while very useful to have for installation and sharing purposes, it is better to disable this share on the clients before running the tests (especially the network-related ones). This is done by deleting the file named USE_SHARE in this directory, and shutting down the clients (on the next startup the share will be disabled on them, but still will be available on the Controller).
  • VirtHCK/run_hck_studio.sh
This script is executed from hck.sh and starts up Studio VM, which configured accordingly to settings from hck_setup.cfg.
  • VirtHCK/run_hck_client.sh
This script is executed from hck.sh and starts up Client VMs, which configured accordingly to settings from hck_setup.cfg.
  • VirtHCK/hck_ctrl_bridge_ifup.sh
This script is executed by QEMU, it creates virtual network bridge on host for HCK Studio-Client interconnection.
  • VirtHCK/hck_test_bridge_ifup.sh
This script is executed by QEMU, it creates virtual network bridge on host for HCK Network card test suite.
  • VirtHCK/hck_world_bridge_ifup.sh
This script is executed by QEMU, it creates virtual network bridge on host for HCK Studio VM in order to connect it to Internet.
  • VirtHCK/guest_tools/run_hck_studio.bat
This script should be executed on Windows Studio guest in order to start HCK Studio. It disconnects guest from Internet before HCK Studio run and connects again after Studio exit. Update adapter name parameter accordingly to Device Manager name for WORLD_NET_DEVICE adapter from run_hck_studio.hck.
  • VirtHCK/guest_tools/enable_world_network.bat
This script could be executed on Windows Studio guest in order to enable Internet connection during HCK Studio run. Update adapter name parameter accordingly to Device Manager name for WORLD_NET_DEVICE adapter from run_hck_studio.hck.
  • VirtHCK/guest_tools/install_cert.bat TestCert.cer
This script should be run with Administrator priveleges and helps to install test certificate on Client VM, it requires certificate file and certmgr.exe console application from WinDDK/WDK in script's directory, certmgr.exe is usually located in:­­­
  • C:\Program Files (x86)\Windows Kits\8.0\bin\x86 - for 32-bit OS
  • C:\Program Files (x86)\Windows Kits\8.0\bin\x64 - for 64-bit OS

Checklist for a new studio VM

  1. Install a VMs with Windows 2008R2 OS (with min. 1 GB of RAM).
  2. Set IP address for control adapter - 192.168.100.1. Also possibly IPv6: 2001:470:27:37e::1
  3. Disable windows firewall.
  4. Make all network connections work/private.
  5. Disable windows update.
  6. Disable screen savers, auto-locking etc.
  7. Rename control network adapter Control.
  8. Rename computer to HCK-STUDIO.
  9. Activate OS.
  10. Install HCK according to MS recommendations http://msdn.microsoft.com/en-us/library/windows/hardware/jj123537.aspx
  11. Download the HCK Filters from here: https://msdn.microsoft.com/en-us/library/windows/hardware/hh998024.aspx, extract the UpdateFilters.sql file from the downloaded .cab archive, put it under the C:\Program Files (x86)\Windows Kits\[version]\Hardware Certification Kit\Controller directory ([version] = HCK version) and run the updatefilters.exe file there.
  12. Pack and put to archive directory.

Checklist for a new client VM

  1. Install a pair of VMs with target OS (VMs to be installed separately, not copied).
  2. Minimal amount of RAM should be 4 GB.
  3. Set IP addresses for control adapters (Client 1 - 192.168.100.2, Client 2 - 192.168.100.3). Possibly, set IPv6 addresses as well (Client 1 - 2001:470:27:37e::2, Client 2 - 2001:470:27:37e::3).
  4. Rename control network adapter to MessageDevice (this specific name is important for LAN device tests!).
  5. Disable windows firewall.
  6. Make all network connections work/private.
  7. Disable windows update.
  8. Disable screen savers, auto-locking etc.
  9. Enable automatic reboot and kernel memory dump on bugcheck.
  10. Activate computers (Uncomment the variable WORLD_NET_IFACE in the run_hck_client.sh script to give client machines access to the Internet).
  11. Rename computers (Client 1 - CL1-~OS~, Client 2 - CL2-~OS~). Instead of the suggested reboot, shut the machines down, and run hck.sh again, so that the machines will have internet access for activation. Do not forget to comment back WORLD_NET_IFACE in run_hck_client.sh afterward, and re-run again before testing.
  12. Install HCK client SW from \\HCK-STUDIO\HCKInstall\Client\setup.exe
  13. Install test signing certificates (64-bit OSes) by script guest_tools/install_cert.bat.
  14. Install the drivers for the device being tested.
  15. Run at least one test and verify it passes (Important: at this stage HCK creates additional users and configures automatic login, make sure this stage passes before moving to further steps).
  16. Map \\HCK-STUDIO\Share as a network drive (Z:).
  17. Create device manager icon on desktop.
  18. Pack and put to archive directory.

VirtHCK Setup Automation and Remote Testing

It is possible to automate the setup of the machines and to run the tests remotely, or from the host machine. For more information, please read the documentation of RemoteHCK: https://github.com/daynix/VirtHCK/tree/master/guest_tools/RemoteHCK.

Test Requirements and Recommendations

  1. Set UNSAFE_CACHE=on for fast VM installation from iso. Note, if host fail during installation with UNSAFE_CACHE=on it might end with corrupted VM image.
storage:
  1. VM Client image should be at least 30GB.
  2. HCK "Crashdump Support Test" requires Client VM internet connection in order to load debug symbols from Microsoft Symbol Server (http://msdl.microsoft.com/download/symbols).
  3. If "Disk Stress" or/and "Disk Verification" tests fails with Performance counters warnings on Client. Update registry performance counters values, run in admin command prompt next two commands:
   lodctr /r
   lodctr /q
  1. If "DP WLK - Hot-Add - Device Test" fails with "Interface GUID_DEVINTERFACE_BUSENUM_TOASTER is not registered" error see this link for resolution: https://social.msdn.microsoft.com/Forums/windowsdesktop/en-US/e129f9aa-6804-4927-a322-cb9ae8f354fa/dp-wlk-hotadd-device-test-verify-driver-support-for-hotadd-cpu-test-fails-on-server2012r2?forum=whck
Windows 8 and Windows 2012 crashes during S4:
Don't for get to install MS updates: https://support.microsoft.com/en-us/kb/2823506?wa=wsignin1.0 https://support.microsoft.com/en-us/kb/2822241
Clone this wiki locally