Updates and Common Questions Asked by Simulation Developers

Peter ShierArchitectWindows Devices and Storage Technologiespshier@microsoft.com

Agenda

• Interface association descriptors• Choosing polled or event-driven data transfer• Implementing event sinks for multiple endpoints• Implementing mass storage simulation• Testing selective suspend• Using endpoint diagnostics• Using managed code with simulations

Interface Association Descriptors

• DSF enables specifying an IAD• Create a SAFEARRAY of VT_UI1 and fill it with the binary

content of your IAD• Call ISoftUSBConfiguration::put_DeviceSpecificDescriptor to

add it to your descriptor set.• See http://msdn.microsoft.com/en-us/library/bb201470.aspx

for more info and code sample

Choosing Polled or Event-Driven Data Transfer

• Control (device requests): event driven typically easiest unless data volume and frequency are high

• Bulk: use event-driven if volume and frequency allow• Interrupt: event driven is best• Isochronous: must use polled

Implementing Event Sinks for Multiple Endpoints

• Define an event sink class that implements ISoftUSBEndpointEvents

• Add a public Init function that takes a pointer to your main simulator class and the ISoftUSBEndpoint interface

• Add public functions to your simulator class for each event you need to handle. • Parameters should be same as event plus the ISoftUSBEndpoint

interface pointer (or anything you want to identify the source endpoint)

• Event handlers just call into the simulator class to report the event.• Add a Terminate function to the event sink class so that it can

remove its event sink on the endpoint and release its back pointer to the simulator class.

Implementing Mass Storage Simulation

• This is not trivial but it has been done and works well.• The USB portions are not too hard but the bus-independent storage portion

can be a large body of code depending on how much you need to implement.• Overview:

• Implement as an in-proc COM object• Use event-driven transfers on bulk endpoints if possible. If not then use dedicated

thread to keep data moving.• Use a worker thread to execute storage commands• Communicate with worker thread from endpoint data handling threadevents that

will occur in arbitrary thread• If using a file as backing store then use overlapped I/O with

FILE_FLAG_NO_BUFFERING • Use a sparse array for simulating large volumes.

• We have some design details available. Send email to dsfsupp@microsoft.com if you’d like a copy.

Testing Selective Suspend

• DSF implements selective suspend on root hub and external hub ports.

• If the driver implements selective suspend then DSF will respond to it.

• SoftUSBDevice.State changes to SoftUSBDeviceStateSuspended when device is suspended.

• There is no event for this. To test whether your device suspends:• Stop submitting I/O to device• Poll SoftUSBDevice.State at some reasonable frequency (e.g. 200ms)

for a period that matches the driver’s idle detection to check that the device suspends in a timely manner.

• For a device-initiated resume call SoftUSBDevice.Resume

Using Endpoint Diagnostics

• Connect test machine to kernel debugger• Alternatively use a Virtual PC for your test machine

• In Vista, at the debugger command line enter:• ed nt!kd_default_mask 8

• In your test app (C++) call:• ISoftUSBEndpoint::QueryInterface(__uuidof(IDSFDebug), …)• IDSFDebug::SetObjectFlags(SOFTUSBENDPOINT_OBJECTFLAGS, <trace flags>)

• In your test app (script) call:• SoftUSBEndpoint.SetObjectFlags 100, <trace flags>

• Trace flags available:• SOFTUSBENDPOINT_TRACETRANSFERINPUT• SOFTUSBENDPOINT_TRACETRANSFEROUPUT• SOFTUSBENDPOINT_TRACETRANSFERINPUTANDOUPUT• SOFTUSBENDPOINT_TRACEOUTLISTOVERFLOW

• More info at http://msdn.microsoft.com/en-us/library/aa938720.aspx

Using Managed Code with Simulators

• Simulators should be written in C++• Simulators can expose interfaces that are usable from

managed code• Write test apps in managed code

Resources

• DSF on MSDN:• Under Win32 and COM Development/Windows Driver Kit/Other

Tools. Currently at http://msdn.microsoft.com/en-us/library/bb981657.aspx

• Tech support questions:• dsfsupp@microsoft.com