Using The Device Simulation Using The Device Simulation Framework For Software Framework For Software Simulation Of USB DevicesSimulation Of USB Devices
Peter ShierPeter ShierArchitectArchitectWindows Device Experience GroupWindows Device Experience GroupMicrosoft CorporationMicrosoft Corporation
AgendaAgenda
Vision and ArchitectureVision and ArchitectureVision and goalsVision and goals
Architecture for device simulationArchitecture for device simulation
Programming a device simulatorProgramming a device simulator
USB SimulationUSB SimulationThe DSF Object ModelThe DSF Object Model
The USB 2.0 Controller SimulatorThe USB 2.0 Controller Simulator
Simulating USB DevicesSimulating USB Devices
Test strategies for USB device simulatorsTest strategies for USB device simulators
VisionVision
Enable easy software simulationEnable easy software simulationof hardware toof hardware to
Improve test coverageImprove test coverage
Increase test automationIncrease test automation
Reduce test costReduce test cost
Develop drivers before hardware is availableDevelop drivers before hardware is available
Provide a higher quality product to customersProvide a higher quality product to customers
Enable partners to do the sameEnable partners to do the same
What Is DSF?What Is DSF?
Architecture to enable simulationArchitecture to enable simulationof hardware in softwareof hardware in software
Framework with code commonFramework with code commonto simulation of all devicesto simulation of all devices
ArchitectureArchitecture
Target Driver
IoC
allD
rive
r
User modeUser modeKernel modeKernel mode
Parent bus driver (e.g., pci.sys)DFSRoot.sys
ArchitectureArchitecture
DFSRoot.sysParent bus driver (e.g., pci.sys)
Target Driver
Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys
DF
SK
Svc
s.li
b
IoC
allD
rive
rIo
Cal
lDri
ver
IoC
allD
rive
r
User modeUser modeKernel modeKernel mode
ArchitectureArchitecture
User modeUser modeKernel modeKernel mode
DFSRoot.sysParent bus driver (e.g., pci.sys)
Target Driver
Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys
DF
SK
Svc
s.li
b
HW redir HW redir
Po
rt a
cces
s
HW
in
terr
up
ts
IoC
allD
rive
rIo
Cal
lDri
ver
IoC
allD
rive
r
ArchitectureArchitecture
User modeUser modeKernel modeKernel mode
DFSRoot.sysParent bus driver (e.g., pci.sys)
Target Driver
Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys
DF
SK
Svc
s.li
b
HW redir HW redir
Po
rt a
cces
s
HW
in
terr
up
ts
IoC
allD
rive
rIo
Cal
lDri
ver
IoC
allD
rive
r
Framework object model (DSFUSvcs.dll)
Framework client (DSFUSvcs.dll)
Pri
vate
IO
CT
Ls
Pri
vate
IO
CT
Ls
ArchitectureArchitecture
User modeUser modeKernel modeKernel mode
DFSRoot.sysParent bus driver (e.g., pci.sys)
Target Driver
Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys
DF
SK
Svc
s.li
b
HW redir HW redir
Po
rt a
cces
s
HW
in
terr
up
ts
IoC
allD
rive
rIo
Cal
lDri
ver
IoC
allD
rive
r
Device simulation object model (e.g., SoftEHCI.dll)
Framework object model (DSFUSvcs.dll)
Framework client (DSFUSvcs.dll)
CO
M
Device simulation script
CO
M
CO
M
Device simulation script
Pri
vate
IO
CT
Ls
Pri
vate
IO
CT
Ls
ArchitectureArchitecture
User modeUser modeKernel modeKernel mode
DFSRoot.sysParent bus driver (e.g., pci.sys)
Target Driver
Device simulator driver(e.g., SoftEHCI.sys) DFSKSvcs.sys
DF
SK
Svc
s.li
b
HW redir HW redir
Po
rt a
cces
s
HW
in
terr
up
ts
IoC
allD
rive
rIo
Cal
lDri
ver
IoC
allD
rive
r
Device simulation object model (e.g., SoftEHCI.dll)
Framework object model (DSFUSvcs.dll)
Framework client (DSFUSvcs.dll)
CO
M
Device simulation script
CO
M
CO
M
Device simulation script
Pri
vate
IO
CT
Ls
Pri
vate
IO
CT
Ls
ArchitectureArchitectureID
E
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
ArchitectureArchitectureID
E
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
Generic Bus
ArchitectureArchitecture
Generic Storage Bus Generic Streaming Bus Generic HID Bus Generic System Bus
IDE
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
Generic Bus
ArchitectureArchitecture
Generic Storage Bus
Disk Tape CDROM Still camera
Video camera Speakers Mouse Keyboard Joystick Battery Thermal
zonePower button
Generic Streaming Bus Generic HID Bus Generic System Bus
IDE
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
Generic Bus
Bus SimulatorsBus Simulators
Simulators for standard hardware Simulators for standard hardware interfaces supplied by Microsoftinterfaces supplied by Microsoft
Expose common interfaces to generic busExpose common interfaces to generic bus
Expose interfaces to support device Expose interfaces to support device simulators and to directly test bus driverssimulators and to directly test bus drivers
Device SimulatorsDevice Simulators
Expose standard interfaces based on Expose standard interfaces based on device family (storage, streaming, HID, device family (storage, streaming, HID, printers, etc.)printers, etc.)
Connect to compatible simulated busesConnect to compatible simulated buses
Expose a programming model to Expose a programming model to test applicationstest applications
Programmability Of SimulatorsProgrammability Of Simulators
Key success factor for automationKey success factor for automation
COM-based programming modelCOM-based programming modelexported from device and bus simulatorsexported from device and bus simulators
Easy to use this model from a Easy to use this model from a test applicationtest application
Automation GoalsAutomation Goals
Enable creation of programming models Enable creation of programming models that imitate real lifethat imitate real life
Promote skills development among Promote skills development among manual testersmanual testers
Reduce the programming knowledge Reduce the programming knowledge needed to express the logic of a manual needed to express the logic of a manual test when building an automated scenariotest when building an automated scenario
Document and automate valuable Document and automate valuable tester folkloretester folklore
Example Test ScriptExample 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 SimulationUSB Simulation
DSF Object ModelDSF Object Model
Buses and DevicesBuses and Devices
EHCI SimulatorEHCI Simulator
Generic USB DeviceGeneric USB Device
Class-specific USB DevicesClass-specific USB Devices
Example DevicesExample Devices
Test strategies for USB device simulatorsTest strategies for USB device simulators
The DSF Object ModelThe DSF Object Model
DSFDevice is the heart of the object model – DSFDevice is the heart of the object model – represents a simulated devicerepresents a simulated device
DSFDevice.Children references a collectionDSFDevice.Children references a collectionof child devices (devices connected to a bus)of child devices (devices connected to a bus)
DSFDevice.Object(<GUID>) returns ancillary DSFDevice.Object(<GUID>) returns ancillary objects used to control the deviceobjects used to control the device
ChildrenChildren
DSF
DSFDevices
DSFDevice
DSFDevices
BusesBuses
These are the simulated buses that support simulated devicesThese are the simulated buses that support simulated devices
Simulated buses are developed by Microsoft Simulated buses are developed by Microsoft
A simulated bus is represented by a DSFDevice objectA simulated bus is represented by a DSFDevice object
A bus device must return a DSFBus object from A bus device must return a DSFBus object from DSFDevice.Object(IID_IDSFBus)DSFDevice.Object(IID_IDSFBus)
DSFBus.Name returns the bus name (e.g., “USB 2.0”)DSFBus.Name returns the bus name (e.g., “USB 2.0”)
The DSFBus object manages connection of devices to the busThe DSFBus object manages connection of devices to the bus
An application connects a device to a bus using An application connects a device to a bus using DSFBus.HotPlug(DSFDevice)DSFBus.HotPlug(DSFDevice)
IDE
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
Generic Bus
Simulation Device ClassesSimulation Device Classes
A device class is a set of related devices A device class is a set of related devices e.g., HID, storage, printers, audio, video, etc.e.g., HID, storage, printers, audio, video, etc.
Devices of a class connect to a bus without Devices of a class connect to a bus without knowing how the bus connects to the host systemknowing how the bus connects to the host system
A protocol translator converts device class transactions A protocol translator converts device class transactions to underlying bus transactions to underlying bus transactions
IDE
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
Generic Bus
Storage Audio HID SystemVideo Cameras
The USB2.0 Bus Simulator The USB2.0 Bus Simulator SoftEHCISoftEHCI
Simulates an EHCI Simulates an EHCI (USB 2.0) controller(USB 2.0) controller
Loads as a lower Loads as a lower filter on the USB filter on the USB EHCI miniport EHCI miniport (usbehci.sys)(usbehci.sys)
The EHCI minport The EHCI minport “believes” it is “believes” it is talking to hardwaretalking to hardware
IoC
allD
rive
rIo
Cal
lDri
ver
User modeKernel mode
PCI.sys
Upper stack – hidusb, usbstor, usbprint, etc.
SoftEHCI.sys DFSKSvcs.sys
usbhub.sys
usbhub.sys
usbhub.sys
Simulated DevicesSimulated Devices
A simulated device uses a protocol translator to connect to a busA simulated device uses a protocol translator to connect to a bus
The test application creates an instance of a device, creates a protocol The test application creates an instance of a device, creates a protocol translator, and connects them together; it then connects the protocol translator translator, and connects them together; it then connects the protocol translator to the bus to the bus
Example Example Create a keyboardCreate a keyboard
Create a HID protocol translator object for USBCreate a HID protocol translator object for USB
Connect the keyboard to the HID protocol translatorConnect the keyboard to the HID protocol translator
Create a USB controller (this is the bus)Create a USB controller (this is the bus)
Connect the HID protocol translator to the USB controllerConnect the HID protocol translator to the USB controller
IDE
SC
SI
iSC
SI
1394
US
B
Par
alle
l
Ser
ial
PS
/2
AC
PI
Car
db
us
Sec
ure
Dig
ital
Blu
eto
oth
PC
I
Generic Bus
Storage
Disk CD
Audio
Speakers
Video
DV Cam
HID
Keyboard Mouse
Cameras
Digi Cam
Printers
Printer
System
Button Lid Battery
SoftEHCI Object ModelSoftEHCI Object Model
SoftEHCI
RootHubPortsCollection
ChildrenChildren
RootHubPort
SoftUSB Device
SoftUSB Device
SoftUSB Object ModelSoftUSB Object Model
SoftUSB Device
Configurations
Strings
EndPoint 0
SoftUSBConfiguration
Soft USBString
InterfacesSoftUSBInterface
EndPoints
SoftUSBEndpoint
SoftUSB Hub Object ModelSoftUSB Hub Object Model
SoftUSBHub
Ports
SoftUSBHubPort
SoftUSBDevice
SoftUSBDevice ObjectSoftUSBDevice Object
One per-simulated USB deviceOne per-simulated USB device
Implements the USB device protocolImplements the USB device protocol
Client is typically a protocol translator (ex. HID) but could also beClient is typically a protocol translator (ex. HID) but could also bea USB device simulator (ex. USB widget with its own device class)a USB device simulator (ex. USB widget with its own device class)
Configured by client according to the USB device class specificationConfigured by client according to the USB device class specification
Bus transactions move to and from SoftUSBEndpoint objectsBus transactions move to and from SoftUSBEndpoint objects
Clients move data in and out of endpointsClients move data in and out of endpoints
Clients can pre-load endpoints with lots of data for performance-Clients can pre-load endpoints with lots of data for performance-sensitive processing (e.g., isochronous) or handle discrete sensitive processing (e.g., isochronous) or handle discrete read/write eventsread/write events
Non-standard device requests can be handled as events from Non-standard device requests can be handled as events from SoftUSBDevice.Endpoint0 SoftUSBDevice.Endpoint0
External Hub SimulatorExternal Hub Simulator
Implemented as USB device simulatorImplemented as USB device simulator
Can behave as a 1.x or 2.0 hubCan behave as a 1.x or 2.0 hub
2.0 hub supports 1.x or 2.0 devices 2.0 hub supports 1.x or 2.0 devices (i.e. implements split transactions)(i.e. implements split transactions)
Hubs and devices can be connected Hubs and devices can be connected before connection to controller (Simulates before connection to controller (Simulates plugging a complex device tree into a hub)plugging a complex device tree into a hub)
SampleSampleBulk Loopback DeviceBulk Loopback Device
SoftUSBDevice supports pairing of SoftUSBDevice supports pairing of endpoints for loopback endpoints for loopback
Makes it possible to implement a loopback Makes it possible to implement a loopback device simulator in VBScriptdevice simulator in VBScript
Script creates SoftUSBDevice and related Script creates SoftUSBDevice and related objects, configures them, and calls objects, configures them, and calls DSF.HotPlug to connect it to the controllerDSF.HotPlug to connect it to the controller
Bulk Loopback SimulatorBulk Loopback SimulatorIn VBScriptIn VBScriptSet 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 Alternative Loopback Device In C++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 SimulatorUSB Keyboard Simulator
Keyboard simulator exposes an object model Keyboard simulator exposes an object model that enables a client test app to simulate key that enables a client test app to simulate key press and releasepress 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_F1SoftKbd.PressKey KEY_F1
SoftKbd calls kbd->HIDMapper to report key pressSoftKbd calls kbd->HIDMapper to report key press
Kbd->HIDMapper creates HID report and calls HID Kbd->HIDMapper creates HID report and calls HID protocol translator for USB protocol translator for USB
HID protocol translator places HID report in interrupt-IN HID protocol translator places HID report in interrupt-IN endpoint’s data queueendpoint’s data queue
When SoftEHCI next processes that endpoint in the When SoftEHCI next processes that endpoint in the periodic schedule it will receive an ACK from the periodic schedule it will receive an ACK from the endpoint, complete the outstanding IN transaction, endpoint, complete the outstanding IN transaction, and simulate a h/w interruptand simulate a h/w interrupt
The USB miniport’s ISR retrieves the data from the The USB miniport’s ISR retrieves the data from the transaction buffer and completes the outstanding URBtransaction buffer and completes the outstanding URBto the upper stack (->usbhub->hidusb->hid stack etc)to the upper stack (->usbhub->hidusb->hid stack etc)
Guidelines For Writing USB Guidelines For Writing USB Device SimulatorsDevice Simulators
Design an object model for test applications. Make itDesign an object model for test applications. Make itIntuitiveIntuitive – express manual testing in words – express manual testing in words
Easy to learn and useEasy to learn and use – leverage skills of inexperienced coders – leverage skills of inexperienced codersto write teststo write tests
Go beyond the obviousGo beyond the obvious – look for fault injection opportunities – look for fault injection opportunitiesby studying your target driver codeby studying your target driver code
Choose any implementation language that supportsChoose any implementation language that supportsCOM (Native or managed, even VBScript)COM (Native or managed, even VBScript)
Either create a DSF-supplied device class object (e.g., Either create a DSF-supplied device class object (e.g., The USB SoftHIDProtocolXlator) or create and configure The USB SoftHIDProtocolXlator) or create and configure a SoftUSBDevice object for your private device classa SoftUSBDevice object for your private device class
For private classes, add code to move data in and For private classes, add code to move data in and out of the SoftUSBEndpoint objectsout of the SoftUSBEndpoint objects
Test Strategies Using Test Strategies Using Device SimulatorsDevice Simulators
Examine your manual tests Examine your manual tests Which cases could be eliminated by automated simulator cases?Which cases could be eliminated by automated simulator cases?
Which cases must always be manual because they areWhich cases must always be manual because they areCommon user integration scenariosCommon user integration scenarios
Potential electrical and timing issues that can’t be reliably simulated?Potential electrical and timing issues that can’t be reliably simulated?
Examine your codeExamine your codeWhat is your code and What is your code and datadata coverage today? coverage today?
Create simulator test cases to cover the missing areasCreate simulator test cases to cover the missing areas
Examine your processExamine your processCreate a build verification testCreate a build verification test
Create a regression suite that can run in 1 day or lessCreate a regression suite that can run in 1 day or less
Create a smaller regression suite that driver devs can run at their desksCreate 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 limitsCreate 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 As you free up resources through automation, use them to write new automated cases and to execute more complex manual integration scenariosand to execute more complex manual integration scenarios
Add automated test cases as new features are added to the driver. Best practice – write Add automated test cases as new features are added to the driver. Best practice – write the test cases the test cases beforebefore the feature code is written and then have the driver dev gradually the feature code is written and then have the driver dev gradually build up the code to pass the testsbuild up the code to pass the tests
Test Strategies UsingTest Strategies UsingUSB Device SimulatorsUSB Device Simulators
Look for fault injection opportunities inLook for fault injection opportunities inData format - the data your simulator puts into the endpoint that is eventuallyData format - the data your simulator puts into the endpoint that is eventuallyread by your target driverread by your target driver
Data sequencing – does your driver expect things to happen in a specific order?Data sequencing – does your driver expect things to happen in a specific order?
Event timing – where does your driver handle timeouts? (Where should it?)Event timing – where does your driver handle timeouts? (Where should it?)
Device configuration – how does your driver handle a missing endpoint or interface?Device configuration – how does your driver handle a missing endpoint or interface?
Packet usage – does your driver handle data arriving in varied packet sizes?Packet usage – does your driver handle data arriving in varied packet sizes?
Look for stress opportunities inLook for stress opportunities inDevice connection/disconnection – do it in a loop!Device connection/disconnection – do it in a loop!
Data rates – stuff the endpoint with data so that reads are constantly completingData rates – stuff the endpoint with data so that reads are constantly completing
Multiple devices – can your driver handle 100 widgets at the same time?Multiple devices – can your driver handle 100 widgets at the same time?
Don’t spend time testing the lower USB stack (usbehci, usbport, usbhub) –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 we do that at Microsoft. Test cases that stress those drivers should be directly related to your devicedirectly related to your device
USB Keyboard SimulatorUSB Keyboard Simulator
Call To ActionCall To Action
Attend the DSF hands-on labAttend the DSF hands-on lab
Run the sample simulators in the WDKRun the sample simulators in the WDK
Develop a simulator for your USB deviceDevelop a simulator for your USB device
Add fault injection to your simulatorAdd fault injection to your simulator
Create automated test suites using Create automated test suites using the simulatorthe simulator
DocumentationDocumentation““Other Tools” section of the WDK DocsOther Tools” section of the WDK Docs
Related SessionsRelated SessionsDEV010DEV010 Best Practices for Testing Best Practices for Testing Windows DriversWindows Drivers
DEV100DEV100 Using the Windows Device Using the Windows Device Testing FrameworkTesting Framework
E-mail questions to:E-mail questions to:DSFSupp @ Microsoft.comDSFSupp @ Microsoft.com
Additional ResourcesAdditional Resources
© 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.