Using The Device Simulation Framework For Software Simulation Of USB Devices

Using The Device Simulation Framework For Software Simulation Of USB Devices Peter Shier Architect Windows Device Experience Group Microsoft Corporation

Agenda • Vision and Architecture • Vision and goals • Architecture for device simulation • Programming a device simulator • USB Simulation • The DSF Object Model • The USB 2.0 Controller Simulator • Simulating USB Devices • Test strategies for USB device simulators

Vision • Enable easy software simulationof hardware to • Improve test coverage • Increase test automation • Reduce test cost • Develop drivers before hardware is available • Provide a higher quality product to customers • Enable partners to do the same

What Is DSF? • Architecture to enable simulationof hardware in software • Framework with code commonto simulation of all devices

IoCallDriver Parent bus driver (e.g., pci.sys) DFSRoot.sys Architecture User modeKernel mode Target Driver

IoCallDriver IoCallDriver IoCallDriver Architecture User modeKernel mode Target Driver Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys DFSKSvcs.lib Parent bus driver (e.g., pci.sys) DFSRoot.sys

Port access IoCallDriver IoCallDriver HW interrupts IoCallDriver Architecture User modeKernel mode Target Driver HW redir HW redir Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys DFSKSvcs.lib Parent bus driver (e.g., pci.sys) DFSRoot.sys

Port access Private IOCTLs IoCallDriver IoCallDriver HW interrupts IoCallDriver Private IOCTLs Architecture Framework object model (DSFUSvcs.dll) Framework client (DSFUSvcs.dll) User modeKernel mode Target Driver HW redir HW redir Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys DFSKSvcs.lib Parent bus driver (e.g., pci.sys) DFSRoot.sys

Device simulation script Device simulation script COM COM Device simulation object model (e.g., SoftEHCI.dll) COM Framework object model (DSFUSvcs.dll) Framework client (DSFUSvcs.dll) User modeKernel mode Target Driver HW redir HW redir Port access Private IOCTLs IoCallDriver IoCallDriver HW interrupts Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys IoCallDriver DFSKSvcs.lib Private IOCTLs Parent bus driver (e.g., pci.sys) DFSRoot.sys Architecture

IDE SCSI iSCSI 1394 USB Parallel Serial PS/2 ACPI Cardbus Secure Digital Bluetooth PCI Architecture

Generic Bus IDE SCSI iSCSI 1394 USB Parallel Serial PS/2 ACPI Cardbus Secure Digital Bluetooth PCI Architecture

Generic Storage Bus Generic Streaming Bus Generic HID Bus Generic System Bus Generic Bus IDE SCSI iSCSI 1394 PCI USB PS/2 Parallel ACPI Cardbus Secure Digital Bluetooth Serial Architecture

Disk Tape CDROM Still camera Video camera Speakers Mouse Keyboard Joystick Battery Thermal zone Power button Generic Storage Bus Generic Streaming Bus Generic HID Bus Generic System Bus Generic Bus IDE SCSI iSCSI 1394 USB Parallel Serial PS/2 ACPI Cardbus Secure Digital Bluetooth PCI Architecture

Bus Simulators • Simulators for standard hardware interfaces supplied by Microsoft • Expose common interfaces to generic bus • Expose interfaces to support device simulators and to directly test bus drivers

Device Simulators • Expose standard interfaces based on device family (storage, streaming, HID, printers, etc.) • Connect to compatible simulated buses • Expose a programming model to test applications

Programmability Of Simulators • Key success factor for automation • COM-based programming modelexported from device and bus simulators • Easy to use this model from a test application

Automation Goals • Enable creation of programming models that imitate real life • Promote skills development among manual testers • Reduce the programming knowledge needed to express the logic of a manual test when building an automated scenario • Document and automate valuable tester folklore

Example Test Script Set ExtHub = CreateObject("SOFTUSB.SoftUSBHub") USBCtrlr.Ports(1).HotPlug ExtHub.SoftUSBDevice Set LoopbackDev = CreateObject("SoftUSBLoopback.LoopbackDevice") ExtHub.Ports(1).HotPlug LoopbackDev.SoftUSBDevice

USB Simulation • DSF Object Model • Buses and Devices • EHCI Simulator • Generic USB Device • Class-specific USB Devices • Example Devices • Test strategies for USB device simulators

DSF DSFDevices Children DSFDevice DSFDevices The DSF Object Model • DSFDevice is the heart of the object model – represents a simulated device • DSFDevice.Children references a collectionof child devices (devices connected to a bus) • DSFDevice.Object(<GUID>) returns ancillary objects used to control the device

IDE SCSI iSCSI 1394 USB Parallel Serial PS/2 ACPI Cardbus Secure Digital Bluetooth PCI Buses • These are the simulated buses that support simulated devices • Simulated buses are developed by Microsoft • A simulated bus is represented by a DSFDevice object • A bus device must return a DSFBus object from DSFDevice.Object(IID_IDSFBus) • DSFBus.Name returns the bus name (e.g., “USB 2.0”) • The DSFBus object manages connection of devices to the bus • An application connects a device to a bus using DSFBus.HotPlug(DSFDevice) Generic Bus

ACPI PCI Bluetooth Cardbus PS/2 Serial Secure Digital USB 1394 iSCSI SCSI IDE Parallel Storage Audio Video Cameras HID System Generic Bus Simulation Device Classes • A device class is a set of related devices e.g., HID, storage, printers, audio, video, etc. • Devices of a class connect to a bus without knowing how the bus connects to the host system • A protocol translator converts device class transactions to underlying bus transactions

User modeKernel mode Upper stack – hidusb, usbstor, usbprint, etc. usbhub.sys usbhub.sys usbhub.sys SoftEHCI.sys DFSKSvcs.sys IoCallDriver IoCallDriver PCI.sys The USB2.0 Bus Simulator SoftEHCI • Simulates an EHCI (USB 2.0) controller • Loads as a lower filter on the USB EHCI miniport (usbehci.sys) • The EHCI minport “believes” it is talking to hardware

ACPI PCI IDE SCSI iSCSI 1394 USB Parallel Serial PS/2 Bluetooth Cardbus Secure Digital Battery Button CD Disk Lid Keyboard Mouse System Storage Printer Audio Digi Cam DV Cam Speakers Cameras Printers Video HID Generic Bus Simulated Devices • A simulated device uses a protocol translator to connect to a bus • The test application creates an instance of a device, creates a protocol translator, and connects them together; it then connects the protocol translator to the bus • Example • Create a keyboard • Create a HID protocol translator object for USB • Connect the keyboard to the HID protocol translator • Create a USB controller (this is the bus) • Connect the HID protocol translator to the USB controller

SoftEHCI Object Model SoftEHCI RootHubPortsCollection RootHubPort SoftUSB Device Children Children SoftUSB Device

SoftUSB Object Model SoftUSB Device SoftUSBConfiguration Configurations SoftUSBInterface Interfaces EndPoints Strings Soft USBString SoftUSBEndpoint EndPoint 0

SoftUSB Hub Object Model SoftUSBHub Ports SoftUSBHubPort SoftUSBDevice

SoftUSBDevice Object • One per-simulated USB device • Implements the USB device protocol • Client is typically a protocol translator (ex. HID) but could also bea USB device simulator (ex. USB widget with its own device class) • Configured by client according to the USB device class specification • Bus transactions move to and from SoftUSBEndpoint objects • Clients move data in and out of endpoints • Clients can pre-load endpoints with lots of data for performance-sensitive processing (e.g., isochronous) or handle discrete read/write events • Non-standard device requests can be handled as events from SoftUSBDevice.Endpoint0

External Hub Simulator • Implemented as USB device simulator • Can behave as a 1.x or 2.0 hub • 2.0 hub supports 1.x or 2.0 devices (i.e. implements split transactions) • Hubs and devices can be connected before connection to controller (Simulates plugging a complex device tree into a hub)

SampleBulk Loopback Device • SoftUSBDevice supports pairing of endpoints for loopback • Makes it possible to implement a loopback device simulator in VBScript • Script creates SoftUSBDevice and related objects, configures them, and calls DSF.HotPlug to connect it to the controller

Bulk Loopback SimulatorIn VBScript Set UsbDev = CreateObject("SOFTUSB.SoftUSBDevice") Set Configuration = CreateObject("SOFTUSB.SoftUSBConfiguration") Set Interface = CreateObject("SOFTUSB.SoftUSBInterface") Set BulkINEndpoint = CreateObject("SOFTUSB.SoftUSBEndpoint") Set BulkOUTEndpoint = CreateObject("SOFTUSB.SoftUSBEndpoint") BulkINEndpoint.EndpointAddress = &H81 ' Endpoint #1, IN BulkINEndpoint.Attributes = &H02 ' Bulk data endpoint BulkINEndpoint.MaxPacketSize = 1024 BulkOUTEndpoint.EndpointAddress = &H02 ' Endpoint #2, OUT BulkOUTEndpoint.Attributes = &H02 ' Bulk data endpoint BulkOUTEndpoint.MaxPacketSize = 1024 Set BulkOUTEndpoint.LoopbackEndpoint = BulkINEndpoint Interface.InterfaceNumber = 0 Interface.AlternateSetting = 0 Interface.Endpoints.Add BulkINEndpoint Interface.Endpoints.Add BulkOUTEndpoint Configuration.ConfigurationValue = 1 Configuration.Interfaces.Add Interface UsbDev.Configurations.Add Configuration Set StringProd = CreateObject("SOFTUSB.SoftUSBString") StringProd.Value = "Simulated USB Bulk Loopback Device" UsbDev.Strings.Add StringProd, 1 UsbDev.Vendor = &H045E ' vendor ID: 045E=Microsoft UsbDev.Product = &H1234 ' product ID UsbDev.ProductDesc = 1 ' Index of string descriptor describing product Set DSF = CreateObject(“DSF.DSF”) Set Bus = DSF.HotPlug, UsbDev.DSFDevice, “USB2.0” WScript.StdOut.WriteLine "Press Enter to terminate simulation" x = WScript.StdIn.ReadLine Bus.Unplug UsbDev.DSFDevice

Alternative Loopback Device In C++ STDMETHODIMP CLoopbackDevice::OnWriteTransfer ( BYTE DataToggle, BYTE *pbDataBuffer, ULONG cbDataBuffer, BYTE *pbStatus ) { HRESULT hr = m_piINEndpoint->QueueINData(pbDataBuffer, cbDataBuffer, USB_ACK, SOFTUSB_FOREVER)); *pbStatus = USB_ACK; return hr; }

USB Keyboard Simulator • Keyboard simulator exposes an object model that enables a client test app to simulate key press and release • Set SoftKbd = CreateObject("INPUTKBD.SoftKeyboard") • Set KbdMapper = CreateObject("SOFTHID.SoftHIDInputKbdMapper") • Set ProtocolXlator = CreateObject("SOFTHIDUSBK.SoftHIDProtocolXlator") • KbdMapper.AttachKbd SoftKbd • KbdMapper.AttachProtocolXlator ProtocolXlator • Set DSF = CreateObject(“DSF.DSF”) • Set Bus = DSF.HotPlug ProtocolXlator.DSFDevice, “USB2.0” • SoftKbd.PressKey KEY_F1 • Bus.Unplug ProtocolXlator.DSFDevice

SoftKbd.PressKey KEY_F1 • SoftKbd calls kbd->HIDMapper to report key press • Kbd->HIDMapper creates HID report and calls HID protocol translator for USB • HID protocol translator places HID report in interrupt-IN endpoint’s data queue • When SoftEHCI next processes that endpoint in the periodic schedule it will receive an ACK from the endpoint, complete the outstanding IN transaction, and simulate a h/w interrupt • The USB miniport’s ISR retrieves the data from the transaction buffer and completes the outstanding URBto the upper stack (->usbhub->hidusb->hid stack etc)

Guidelines For Writing USB Device Simulators • Design an object model for test applications. Make it • Intuitive – express manual testing in words • Easy to learn and use – leverage skills of inexperienced codersto write tests • Go beyond the obvious – look for fault injection opportunitiesby studying your target driver code • Choose any implementation language that supportsCOM (Native or managed, even VBScript) • Either create a DSF-supplied device class object (e.g., The USB SoftHIDProtocolXlator) or create and configure a SoftUSBDevice object for your private device class • For private classes, add code to move data in and out of the SoftUSBEndpoint objects

Test Strategies Using Device Simulators • Examine your manual tests • Which cases could be eliminated by automated simulator cases? • Which cases must always be manual because they are • Common user integration scenarios • Potential electrical and timing issues that can’t be reliably simulated? • Examine your code • What is your code and data coverage today? • Create simulator test cases to cover the missing areas • Examine your process • Create a build verification test • Create a regression suite that can run in 1 day or less • Create a smaller regression suite that driver devs can run at their desks • Create a stress suite that pushes your driver to its perf and robustness limits • As you free up resources through automation, use them to write new automated cases and to execute more complex manual integration scenarios • Add automated test cases as new features are added to the driver. Best practice – write the test cases before the feature code is written and then have the driver dev gradually build up the code to pass the tests

Test Strategies UsingUSB Device Simulators • Look for fault injection opportunities in • Data format - the data your simulator puts into the endpoint that is eventuallyread by your target driver • Data sequencing – does your driver expect things to happen in a specific order? • Event timing – where does your driver handle timeouts? (Where should it?) • Device configuration – how does your driver handle a missing endpoint or interface? • Packet usage – does your driver handle data arriving in varied packet sizes? • Look for stress opportunities in • Device connection/disconnection – do it in a loop! • Data rates – stuff the endpoint with data so that reads are constantly completing • Multiple devices – can your driver handle 100 widgets at the same time? • Don’t spend time testing the lower USB stack (usbehci, usbport, usbhub) –we do that at Microsoft. Test cases that stress those drivers should be directly related to your device

USB Keyboard Simulator

Call To Action • Attend the DSF hands-on lab • Run the sample simulators in the WDK • Develop a simulator for your USB device • Add fault injection to your simulator • Create automated test suites using the simulator

Additional Resources • Documentation • “Other Tools” section of the WDK Docs • Related Sessions • DEV010 Best Practices for Testing Windows Drivers • DEV100 Using the Windows Device Testing Framework • E-mail questions to: DSFSupp @ Microsoft.com

© 2006 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

Using The Device Simulation Framework For Software Simulation Of USB Devices