Teledyne USB File Based Decode User Manual
2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622
CATC Request Definition (.req)
and Descriptor Definition (.dsc)
Files Reference Manual
October 16, 2001
COMPUTER ACCESS TECHNOLOGY CORPORATION
CATC Request Definition (.req) and Descriptor
Definition (.dsc) Files Reference Manual
Document Disclaimer
The information contained in this document has been carefully checked and is
believed to be reliable. However, no responsibility can be assumed for inaccuracies
that may not have been detected.
CATC reserves the right to revise the information presented in this document
without notice or penalty.
Trademarks and Servicemarks
CATC is a trademark of Computer Access Technology Corporation.
All other trademarks are property of their respective companies.
Copyright
Copyright 2001, Computer Access Technology Corporation (CATC). All rights
reserved.
This document may be printed and reproduced without additional permission, but
all copies should contain this copyright notice.
ii
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
TABLE OF CONTENTS
USB Request Definition (.req) Files . . . . . . . . . . 1
Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
GroupName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
GroupType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
GroupType=Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
GroupType=Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
GroupType=Vendor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
AllRequests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Request(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
EndpointData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Request definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Decoding Definition strings: wValue, wIndex, and Data . . . . . . . . . . . 7
WordValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
FormatValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Bitmap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Additional Request Keywords . . . . . . . . . . . . . . . . . . . . . . . 13
bmRequestType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Bytes(x, y). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Color(R,G,B) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Databytes(x, y) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Depends(...). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Endian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
HIBYTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
LOBYTE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
EndpointData Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
EndpointDirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
EndpointId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
EndpointType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
MaxPacketSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
MaxTransferSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
i
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
Nested Request Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
USB Descriptor Definition (.dsc) Files . . . . . . . 25
Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
DescriptorName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
DescriptorType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
DescriptorSubtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
ClassCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
SubclassCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
AllOffsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Offset(...). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Descriptor definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Decoding Definition Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
FormatValue, WordValue, and Bitmap . . . . . . . . . . . . . . . . . . . . 30
Additional Descriptor Keywords . . . . . . . . . . . . . . . . . . . . . 30
BCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
ii
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
USB REQUEST DEFINITION (.req)
F
ILES
Request definition (.req) files are used to configure decoding of class- or vendorspecific data of any protocol defined for USB. A .req file is a set of instructions that
contains definitions that describe, in USB-specific terms, how to take blocks of data
and break them into fields with consecutive decoding of each field. The data being
decoded can be data in a USB Device Request, or any formatted data that is sent on
an Interrupt or Bulk endpoint of a USB device.
The request definition files are text-based files that are identifiable by their .req extension. Customized decoding of USB requests is possible by editing files or
creating new definition files. This document describes the components of a .req file
and the format for writing or editing a .req file.
Please refer to the Universal Serial Bus Specification, version 1.1 for details about
USB protocol. The USB specification is available from the USB Implementers
Forum (USB-IF) at http://www.usb.org/.
Structure
A .req file has the following basic structure:
[Defines=
{
<Define_0>=<Define_Name_0>
<Define_1>=<Define_Name_1>
<Define_2>=<Define_Name_2>
...
}]
opt
GroupName=<name>
GroupType=<Standard, Class, or Vendor>
AllRequests=
{
<bRequest_0>=<bRequest_Name_0>
<bRequest_1>=<bRequest_Name_1>
<bRequest_2>=<bRequest_Name_2>
...
}
1
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
Request(<bRequest_0>)=
{
...
}
Request(<bRequest_1>)=
{
...
}
Request(<bRequest_2>)=
{
...
}
...
[EndpointData=
{
...
}]
opt
[EndpointData=
{
...
}]
opt
...
Entries
This section describes the basic entries that comprise a .req file.
Note: There must be no white space in between keywords and the equal sign (=) ;
for example: GroupName=. However, it is permissible to put white space
between values and the equal sign; e.g., GroupName= Class or
0x00 = RequestName. In the case of keywords that require parentheses fol-
lowed by an equal sign, there must not be white space on either side of the paren-
theses: Request(...)=.
Defines
The Defines keyword is an optional entry that is used to associate a numeric
value with a text string. Once the association is set up, those values can be referred
to by name in the request definitions. The Defines definition uses the following
format:
2
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
Defines=
{
<value>=<string>
}
The value should be set to the actual value, while string represents the name
of the unit. An example is found in the sample file Audio.req:
DEFINES={
0x01=TERMINAL_UNIT
0x05=TERMINAL_UNIT
0x09=TERMINAL_UNIT
0x0C=TERMINAL_UNIT
0x02=PROCESSING_UNIT
0x03=PROCESSING_UNIT
0x04=FEATURE_UNIT
0x06=FEATURE_UNIT
0x08=FEATURE_UNIT
0x0B=FEATURE_UNIT
0x07=MIXER_UNIT
0x0A=MIXER_UNIT
}
These units can now be referred to by name, instead of by number, in the request
definitions:
wIndex={
HIBYTE={
Depends(HIBYTE(wIndex))={
TERMINAL_UNIT={
FormatValue=Terminal ID 0x%02X
}
MIXER_UNIT={
FormatValue=Mixer Unit ID 0x%02X
}
SELECTOR_UNIT={
FormatValue=Selector Unit ID 0x%02X
}
FEATURE_UNIT={
FormatValue=Feature Unit 0x%02X
}
PROCESSING_UNIT={
FormatValue=Processing Unit ID 0x%02X
}
3
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
EXTENSION_UNIT={
FormatValue=Extension Unit ID 0x%02X
}
}
}
...
GroupName
The GroupName entry defines the name for the group of requests described in the
file. This name also appears in the SETUP field's request decoding context menu.
For example,
GroupName=Imaging Class
shows up in the context menu this way:
Figure 1: GroupName entry appears in SETUP context
menu
GroupType
The GroupType entry defines the type of requests in the file. There are three (3)
possible settings for the GroupType entry: GroupType=Standard,
GroupType=Class, and GroupType=Vendor.
GroupType=Standard
A set GroupType=Standard requests defines the standard USB requests. Note
that in the case of defining standard USB requests, there can be only one .req file.
CATC supplies the standard request definitions in the file standard.req.
GroupType=Class
GroupType=Class indicates that the file defines a set of class-specific USB
requests. This group type also requires a ClassCode entry, which specifies the
USB-assigned device class code. For example,
GroupType=Class
ClassCode=0x03
4
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
defines the Human Interface Device (HID) class code.
GroupType=Vendor
GroupType=Vendor indicates that the file defines a set of vendor-specific USB
requests. This group type also requires VendorID and ProductID entries.
These values are used to uniquely identify the Vendor Decoding group when it is
associated with Request Recipients in a trace file. The value for VendorID is the
assigned vendor ID. The value for ProductID doesn't actually have to match the
real product ID for the device. For example:
GroupType=Vendor
VendorID=0x0423
ProductID=0x000D
AllRequests
The AllRequests keyword is used to specify the bRequest values for all of
the requests described in the .req file. The AllRequests definition uses the
following format:
AllRequests=
{
<bRequest>=<RequestNameString>
...
}
The value bRequest is is the USB-assigned value, and is represented numerically.
RequestNameString is the textual representation of bRequest. It also rep-
resents the name of the request that will appear in the Request Decoding dialog. For
example:
AllRequests=
{
0x00=REQUEST_NAME_0
0x01=REQUEST_NAME_1
}
Note: it's not necessary for the numeric bRequest values to start from zero or to
increase sequentially. In addition, the numeric values may be in decimal or hexadecimal.
Request(...)
Request(...) defines a request listed in the AllRequests entry. Request
definitions follow the format
5
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
Request(<bRequest>)=
{
...
}
The bRequest value should match the numeric value assigned to the request in
the AllRequests entry. For example:
Request(0x00)=
{
...
}
Request(0x01)=
{
...
}
EndpointData
EndpointData defines endpoint data decoding.
The basic structure for an EndpointData definition is
EndpointData=
{
[Caption=<string>]
[EndpointType=<string>]
[EndpointDirection=IN or OUT]
[EndpointId=<value>]
opt
opt
opt
opt
MaxPacketSize=<integer>
MaxTransferSize=<integer>
Data=
{
...
}
}
For more information about EndpointData definitions, please see page 20.
Request definitions
The bulk of a .req file is composed of Request entries, which are the actual
request definitions. This section describes the contents and formatting of a
Request entry.
6
COMPUTER ACCESS TECHNOLOGY CORPORATION USB REQUEST DEFINITION (.REQ) FILES
Reference Manual
Decoding Definition strings: wValue, wIndex, and Data
A request definition may contain three optional decoding definition strings:
wValue, wIndex, and Data. wValue and wIndex define how the wValue and
wIndex fields of the request are decoded. Data specifies how Data fields are
decoded during the request's data stage. All three use the same definition format, as
follows:
<wValue, wIndex or Data>=
{
...
}
If one or more of the definition strings is omitted, then the Request Decoding
applies default decoding.
The contents of the decoding definitions can be built using one or more of these
three basic keywords: WordValue, FormatValue, and Bitmap.
WordValue
Use the WordValue keyword when the field has a defined set of possible values,
and each value has a different meaning. The entries are formatted as an enumerated
list, as follows:
WordValue=
{
<wValue_0>=<Value_Meaning_0>
<wValue_1>=<Value_Meaning_1>
...
}
The possible values for wValue are represented numerically. The meanings are
generally represented as text strings. WordValue entries work similarly to if-then
statements: if wValue matches a wValue value in the WordValue list, then the
meaning will appear in the wValue trace field. If the value of wValue doesn't
match a value in the list, then, by default, its numeric value will be displayed in the
wValue trace field. However, this default can also be overridden with a different
type of decoding -- a FormatValue entry (see “FormatValue” on page 8 for
details) or a Bitmap entry (see “Bitmap” on page 11 for more details).
The following example comes from the wValue entry of the hub.req
SetFeature request definition. The figure shows the output that results when
wValue is 0x0008.
WordValue={
0x0001=PORT_ENABLE
0x0002=PORT_SUSPEND
7
Loading...