Using The Device Simulation Framework For Software Simulation Of USB Devices Peter Shier Architect...

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


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





Target Driver


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




Target Driver


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




Target Driver


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


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


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.

Using The Device Simulation Framework For Software Simulation Of USB Devices Peter Shier Architect...

Documents

Transcript of Using The Device Simulation Framework For Software Simulation Of USB Devices Peter Shier Architect...