Starting with version 4.20, the USB Protocol Suite introduces Trainer facilities for Device Emulation. They include instructions for initializing the device emulation and defining a set of descriptors for the Device Framework Handler, which automatically handles all Standard USB device requests. These instructions are applicable only when the Trainer operation mode is set to Device Emulation.
Starting with version 4.35 the USB Protocol Suite introduces Drive Emulation. The AddDrive instruction allows to emulate a BOT (and later UASP) drive. When connected to a system, the Trainer comes up then as an uninitialized drive. It has to be initialized and formatted, then files can be copied to it / from it as long as the Voyager system stays powered up. During this the Trainer Drive Emulation can be disconnected from the USB3 system and connected back or to a different USB3 system and the files on the Drive Emulator will stay intact.
Note: Refer to the UseAssignedAddress setting, which is applicable only to Device Emulation.
StartDeviceFrameworkHandler Instruction
This instruction starts or stops the Device Framework Handler task on the Trainer
StartDeviceFrameworkHandler( start/stop )
StartDeviceFrameworkHandler has the following instruction parameters:
start/stop: Specifies if the Device Framework Handler task has to be started (1) or stopped (zero). Default value is 1.
Examples
# Device emulation
Main
{
# Start the handler task at the beginning of the script.
StartDeviceFrameworkHandler()
…
# Stop the handler task temporarily.
StartDeviceFrameworkHandler( 0 )
# Process some standard requests by script.
…
# Start the automatic task again.
StartDeviceFrameworkHandler()
}
InitDevice Instruction
This instruction initializes operation of Device Emulation for a device. The device is placed in the USB Default state.
InitDevice( clear descriptors, device index )
InitDevice has the following instruction parameters:
-
clear descriptors: Specifies if all previously added descriptors for this device have to be removed (1) or kept (zero). Default value is 1.
-
device index: Specifies the zero-based index of the device to initialize. Default value is 0. Note: Current version supports only one emulated device.
Examples
# Device emulation
Main
{
# Start the handler task at the beginning of the script.
StartDeviceFrameworkHandler()
# Initialize device to default state and clear all descriptors.
InitDevice()
# Add all required descriptors.
…
# At some point, device emulator is connected to the host and
# enumerated.
…
# Re-initialize device, but keep the descriptors.
InitDevice( 0 )
# Emulate disconnection and reconnection.
SetLinkState( RX_DETECT )
}
AddDescriptor Instruction
This instruction adds a descriptor structure to the descriptor list for a device. The descriptor alias is used by the device Framework Handler task when automatically responding to GET_DESCRIPTOR USB requests.
AddDescriptor( type, index, request type, recipient, language id, bRequest, device index )
{
DescriptorData
{
Data = ...
}
}
AddDescriptor has the following instruction parameters:
-
type: Descriptor Type as defined by the USB specification. Default value is 0.
-
index: Descriptor Index as defined by the USB specification. Default value is 0.
-
request type: Request type as defined by the USB specification for the request used to retrieve the descriptor. Default value is 0, for Standard type.
-
recipient: Request recipient as defined by the USB specification for the request used to retrieve the descriptor. Default value is 0, for Device.
-
language id: Language ID as defined by the USB specification, for String descriptors only. Default value is 0.
-
bRequest: bRequest value as defined by the USB specificationfor the request used to retrieve the descriptor. Default value is 6, for standard GET_DESCRIPTOR request.
-
device index: Specifies the zero-based index of the device for which to add descriptor. Default value is 0. Note: Current version supports only one emulated device.
The instruction accepts the data for the descriptor itself as a Packet structure variable with an array of data. The structure has to be declared in the script, as shown in the example below.
Examples
# Device emulation
# Include file with descriptor structures and constant definitions
%include "Generation\Include\DeviceRequestConstants.ginc"
# Define data structure to be used with AddDescriptor.
Packet DescriptorData
{
Data : *
}
Main
{
# Start the handler task at the beginning of the script.
StartDeviceFrameworkHandler()
# Initialize device to default state and clear all descriptors.
InitDevice()
# Add required descriptors.
$DeviceDescriptorPayLoad = DeviceDescriptor
$DeviceDescriptorPayLoad
{
Length = 0x12
DescriptorType = DEVICE_DESC
bcdUSB = 0x0300
DeviceClass = 0x00
DeviceSubClass = 0x00
DeviceProtocol = 0x00
MaxPacketSize0 = 0x200
dVendor = 0x0423
dProduct = 0x0001
bcdDevice = 0x0002
Manufacturer = 0x01
Product = 0x02
SerialNumber = 0x03
NumConfigurations = 1
}
AddDescriptor( DEVICE_DESC, 0 )
{
DescriptorData
{
Data = $DeviceDescriptorPayLoad
}
}
…
# - String descriptor for Manufacturer
AddDescriptor( STRING_DESC, 1, 0, 0, 0x0409 )
{
DescriptorData
{
# "LeCroy Corporation"
Data = { 28 03 4C 00 65 00 43 00 72 00 6F 00 79 00 20 00
43 00 6F 00 72 00 70 00 6F 00 72 00 70 00 61 00
74 00 69 00 6F 00 6E 00 }
}
}
…
}
WaitForDeviceRequest Instruction
This instruction allows synchronizing the execution of the automatic Device Framework Handler with the rest of the script. A typical device emulation script includes a portion that starts and configures the Device Framework Handler and a portion that adds some script code to handle communication with the driver/application when they load. The second portion needs to wait and allow the Device Framework Handler, which only deals with Standard device requests, to handle the system and initial driver enumeration.
This instruction can be used to wait for a specific Standard request that is sent at the end of the standard driver enumeration. In this case, no additional processing is required for this request, as it is handled by the Device Framework Handler. Alternatively, the script can be waiting for the first Class- or Vendor-specific request sent by the driver. In this case, the Setup stage for the request is automatically acknowledged, but data and status stage needs processing by the script itself.
WaitForDeviceRequest( bRequest, wIndex, wValue, bmRequestType, device index )
WaitForDeviceRequest has the following instruction parameters:
-
bRequest: Default value is 0xFFFFFFFF (“Don’t care”).
-
wIndex: Default value is 0xFFFFFFFF (“Don’t care”).
-
wValue: Default value is 0xFFFFFFFF (“Don’t care”).
-
bmRequestType: Default value is 0xFFFFFFFF (“Don’t care”).
-
device index: Specifies the zero-based index of the device to initialize. Default value is 0. Note: Current version supports only one emulated device.
For an example of the usage for this instruction, please refer to the DeviceEmulation2.usb3g mass storage sample file provided with the USB Protocol Suite software.
AddDrive Instruction
This instruction sets up Drive Emulation for the device that is being emulated.
AddDrive( protocol, last lba, cmd ep num, stat ep num, data out ep num, data in ep num, block size, drive index, device index )
{
DriveData
{
Data = ...
}
}
AddDrive has the following instruction parameters:
-
protocol: Mass Storage protocol supported by the Drive Emulator. Can be either 0x50 for the BOT protocol or 0x62 for the UASP protocol. All other values are reserved.Default value is 0x50 for the BOT protocol.Note:only BOT protocol is supported in this release.
-
last lba: The value of Last LBA as returned by the drive as part of READ CAPACITY SCSI command. Combined with the block size, determines the capacity of the drive. Default value is 0 (so, a non-zero value has to be set when calling this instruction). Maximum allowed drive capacity in this release is 256 MB, which results in0x80000 maximum for this parameter assuming block size of 512 bytes.
-
cmd ep num:The number of the Command (and Data-Out in case of the BOT protocol) endpoint for the drive. Default value is 0, so it must be assigned a non-zero value. Should match the value provided in the Endpoint descriptor for the corresponding interface.
-
stat ep num:The number of the Status (and Data-In in case of the BOT protocol) endpoint for the drive. Default value is 0, so it must be assigned a non-zero value. Should match the value provided in the Endpoint descriptor for the corresponding interface.
-
dataout ep num:The number of the Data-Outendpoint for the drive. Doesn’t have to be specified in case of the BOT protocol. Default value is 0, so it must be assigned a non-zero value. Should match the value provided in the Endpoint descriptor for the corresponding interface.
-
data in ep num:The number of the Data-In endpoint for the drive. Doesn’t have to be specified in case of the BOT protocol. Default value is 0, so it must be assigned a non-zero value. Should match the value provided in the Endpoint descriptor for the corresponding interface.
-
block size: Logical block length in bytes. Combined with the last lba parameter defines the drive capacity. Default value is 512.
-
drive index: Specifies the zero-based index of the drive that is being emulated, so it can be referenced in the future.Default value is 0. Note: Current version supports only one emulated drive/device.
-
device index: Specifies the zero-based index of the device for which the drive is being emulated. Default value is 0. Note: Current version supports only one emulated device.
The instruction accepts the Standard Inquiry Data for the drive as a Packet structure variable with an array of data. The structure has to be declared in the script.
For an example of using the AddDrive instruction, refer to the DriveEmulation.usb3g sample script included with the USB Protocol Suite.