Using The Device Simulation Framework For Software Simulation

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 simulation of 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 simulation of hardware in software Framework with code common to simulation of all devices

Architecture User mode Kernel mode Io. Call. Driver Target Driver Parent bus driver (e. g. , pci. sys) DFSRoot. sys

Architecture User mode Kernel mode Parent bus driver (e. g. , pci. sys) Io. Call. Driver DFSKSvcs. sys Io. Call. Driver Device simulator driver (e. g. , Soft. EHCI. sys) DFSKSvcs. lib Io. Call. Driver Target Driver DFSRoot. sys

Architecture User mode Kernel mode Target Driver Parent bus driver (e. g. , pci. sys) Io. Call. Driver DFSKSvcs. sys Io. Call. Driver DFSKSvcs. lib Device simulator driver (e. g. , Soft. EHCI. sys) Io. Call. Driver HW redir HW interrupts Port access HW redir DFSRoot. sys

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

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

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

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

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

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

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

Bus 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 model exported 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 Ext. Hub = Create. Object("SOFTUSB. Soft. USBHub") USBCtrlr. Ports(1). Hot. Plug Ext. Hub. Soft. USBDevice Set Loopback. Dev = Create. Object("Soft. USBLoopback. Device") Ext. Hub. Ports(1). Hot. Plug Loopback. Dev. Soft. USBDevice

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

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

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. Hot. Plug(DSFDevice) PCI Bluetooth Secure Digital Cardbus ACPI PS/2 Serial Parallel USB 1394 i. SCSI IDE 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 Storage Audio Video Cameras HID System PCI Bluetooth Secure Digital Cardbus ACPI PS/2 Serial Parallel USB 1394 i. SCSI IDE Generic Bus

The USB 2. 0 Bus Simulator Soft. EHCI User mode Kernel mode Upper stack – hidusb, usbstor, usbprint, etc. usbhub. sys Io. Call. Driver usbhub. sys Soft. EHCI. sys DFSKSvcs. sys Io. Call. Driver 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 PCI. sys

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 CD Speakers DV Cam Digi Cam Audio Video Cameras Storage Keyboard Mouse HID Printer Button Printers Lid Battery System PCI Bluetooth Secure Digital Cardbus ACPI PS/2 Serial Parallel USB 1394 SCSI IDE Generic Bus i. SCSI Disk

Soft. EHCI Object Model Soft. EHCI Root. Hub. Ports Collection Root. Hub. Port Soft. USB Device Children Soft. USB Device

Soft. USB Object Model Soft. USB Device Configurations Soft. USB Configuration Interfaces Strings End. Point 0 Soft USB String Soft. USB Interface End. Points Soft. USB Endpoint

Soft. USB Hub Object Model Soft. USBHub Ports Soft. USBHub. Port Soft. USBDevice

Soft. USBDevice Object One per-simulated USB device Implements the USB device protocol Client is typically a protocol translator (ex. HID) but could also be a 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 Soft. USBEndpoint objects Clients move data in and out of endpoints Clients can pre-load endpoints with lots of data for performancesensitive processing (e. g. , isochronous) or handle discrete read/write events Non-standard device requests can be handled as events from Soft. USBDevice. Endpoint 0

External Hub Simulator Implemented as USB device simulator Can behave as a 1. x or 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)

Sample Bulk Loopback Device Soft. USBDevice supports pairing of endpoints for loopback Makes it possible to implement a loopback device simulator in VBScript creates Soft. USBDevice and related objects, configures them, and calls DSF. Hot. Plug to connect it to the controller

Bulk Loopback Simulator In VBScript Set Usb. Dev = Create. Object("SOFTUSB. Soft. USBDevice ") Set Configuration = Create. Object("SOFTUSB. Soft. USBConfiguration ") Set Interface = Create. Object("SOFTUSB. Soft. USBInterface ") Set Bulk. INEndpoint = Create. Object("SOFTUSB. Soft. USBEndpoint ") Set Bulk. OUTEndpoint = Create. Object("SOFTUSB. Soft. USBEndpoint ") Bulk. INEndpoint. Address = &H 81 ' Endpoint #1, IN Bulk. INEndpoint. Attributes = &H 02 ' Bulk data endpoint Bulk. INEndpoint. Max. Packet. Size = 1024 Bulk. OUTEndpoint. Address = &H 02 ' Endpoint #2, OUT Bulk. OUTEndpoint. Attributes = &H 02 ' Bulk data endpoint Bulk. OUTEndpoint. Max. Packet. Size = 1024 Set Bulk. OUTEndpoint. Loopback. Endpoint = Bulk. INEndpoint Interface. Number = 0 Interface. Alternate. Setting = 0 Interface. Endpoints. Add Bulk. INEndpoint Interface. Endpoints. Add Bulk. OUTEndpoint Configuration. Value = 1 Configuration. Interfaces. Add Interface Usb. Dev. Configurations. Add Configuration Set String. Prod = Create. Object("SOFTUSB. Soft. USBString ") String. Prod. Value = "Simulated USB Bulk Loopback Device" Usb. Dev. Strings. Add String. Prod, 1 Usb. Dev. Vendor = &H 045 E ' vendor ID: 045 E=Microsoft Usb. Dev. Product = &H 1234 ' product ID Usb. Dev. Product. Desc = 1 ' Index of string descriptor describing product Set DSF = Create. Object(“DSF. DSF ”) Set Bus = DSF. Hot. Plug, Usb. Dev. DSFDevice , “USB 2. 0” WScript. Std. Out. Write. Line "Press Enter to terminate simulation" x = WScript. Std. In. Read. Line Bus. Unplug Usb. Dev. DSFDevice

Alternative Loopback Device In C++ STDMETHODIMP CLoopback. Device: : On. Write. Transfer ( BYTE Data. Toggle, BYTE *pb. Data. Buffer, ULONG cb. Data. Buffer, BYTE *pb. Status ) { HRESULT hr = m_pi. INEndpoint->Queue. INData(pb. Data. Buffer, cb. Data. Buffer, USB_ACK, SOFTUSB_FOREVER)); *pb. Status = 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 Soft. Kbd = Create. Object("INPUTKBD. Soft. Keyboard") Set Kbd. Mapper = Create. Object("SOFTHID. Soft. HIDInput. Kbd. Mapper") Set Protocol. Xlator = Create. Object("SOFTHIDUSBK. Soft. HIDProtocol. Xlator") Kbd. Mapper. Attach. Kbd Soft. Kbd. Mapper. Attach. Protocol. Xlator Set DSF = Create. Object(“DSF. DSF”) Set Bus = DSF. Hot. Plug Protocol. Xlator. DSFDevice, “USB 2. 0” Soft. Kbd. Press. Key KEY_F 1 Bus. Unplug Protocol. Xlator. DSFDevice

Soft. Kbd. Press. Key KEY_F 1 Soft. Kbd 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 Soft. EHCI 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 URB to 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 coders to write tests Go beyond the obvious – look for fault injection opportunities by studying your target driver code Choose any implementation language that supports COM (Native or managed, even VBScript) Either create a DSF-supplied device class object (e. g. , The USB Soft. HIDProtocol. Xlator) or create and configure a Soft. USBDevice object for your private device class For private classes, add code to move data in and out of the Soft. USBEndpoint 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 Using USB Device Simulators Look for fault injection opportunities in Data format - the data your simulator puts into the endpoint that is eventually read 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 DEV 010 Best Practices for Testing Windows Drivers DEV 100 Using the Windows Device Testing Framework E-mail questions to: DSFSupp @ Microsoft. com

© 2006 Microsoft Corporation. All rights reserved. Microsoft, 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.