|
Controlling a Device
Before we go into detail,
we need to look at how the host recognises and installs a device
when you plug it in. We need to do this in general terms without
getting bogged down with the detail.
When you plug a USB device
in, the host becomes aware (because of the pullup resistor on one
data line), that a device has been plugged in.
|
|
|
The host now signals
a USB Reset to the device, in order that it should start in a known
state at the end of the reset. In this state the device responds
to the default address 0. Until the device has been reset the host
prevents data from being sent downstream from the port. It will
only reset one device at a time, so there is no danger of two devices
responding to address 0.
The host will now send
a request to endpoint 0 of device address 0 to find out its maximum
packet size. It can discover this by using the Get Descriptor (Device)
command. This request is one which the device must respond to even
on address 0.
Typically (i.e. with
Windows) the host will now reset the device again. It then sends
a Set Address request, with a unique address to the device at address
0. After the request is completed, the device assumes the new address.
(And at this point the host is now free to reset other recently
plugged-in devices.)
Typically the host will
now begin to quiz the device for as many details as it feels it
needs. Some requests involved here are:
- Get Device Descriptor
- Get Configuration
Descriptor
- Get String Descriptor
At the moment the device
is in an addressed but unconfigured state, and is only allowed to
respond to standard requests.
Once the host feels it
has a clear enough picture of what the device is, it will load a
suitable device driver.
The device driver will
then select a configuration for the device, by sending a Set Configuration
request to the device.
The device is now in
the configured state, and can start working as the device it was
designed to be. From now on it may respond to device specific requests,
in addition to the standard requests which it must continue to support.
|
|
|
We can now see that there
is a set of requests which a device must respond to, and need to
look at the detailed means by which the requests are conveyed.
We saw in the last chapter
that data is transfered in 4 different types of transfer:
- Control Transfers
- Interrupt Transfers
- Bulk Transfers
- Isochronous Transfers
The only transfer type
available before the device has been configured is the Control Transfer.
The only endpoint available at this time is the bidirectional Endpoint
0.
|
|
|
Configurations, Interfaces,
and Endpoints.
The device contains a
number of descriptors (as shown to the right) which help to define
what the device is capable of. We will examine these descriptors
further down the page. For the moment we need to have an idea what
the configurations, interfaces and endpoints are and how they fit
together.
A
device can have more than one configuration, though only
one at a time, and to change configuration the whole device would
have to stop functioning. Different configurations might be used,
for example, to specify different current requirements, as the current
required is defined in the configuration descriptor.
However it is not common
to have more than one configuration. Windows standard drivers will
always select the first configuration so there is not a lot of point.
A device can have one
or more interfaces. Each interface can have a number of endpoints
and represents a functional unit belonging to a particular class.
Each endpoint
is a source or sink of data.
For example a VOIP phone
might have one audio class interface with 2 endpoints for transferring
audio in each direction, plus a HID interface with a single IN interrupt
endpoint, for a built in keypad.
It is also possible to
have alternative versions of an interface, and this is more common
than multiple configurations. In the VOIP phone example, the audio
class interface might offer an alternative with a different audio
rate. It is possible to switch an interface to an alternate while
the device remains configured.
|
|
|
|
The SETUP Packet
The Standard requests
are all conveyed using control transfers to endpoint 0. Remember
that a control transfer starts with a SETUP transaction which conveys
8 bytes. These 8 bytes define the request from the host.
The structure of bmRequestType
makes it easy to use it to switch on when your firmware is trying
to interpret the setup request. Essentially, when the SETUP arrives,
you need to branch to the handler for the particular request, so
for example bits 6:5 allow you to distinguish the mandatory standard
commands, from any class or vendor commands you may have implemeted
for you particular device.
Switching on bit 7 allows
you to deal with IN and OUT direction requests in separate areas
of the code.
|
|
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bmRequestType
|
1
|
Bitmap
|
D7
Data direction |
0
- Host-to-device
1
- Device-to-host |
D6:5
Type |
0
= Standard
1 = Class
2 = Vendor
3 = Reserved |
D4:0
Recipient |
0
= Device
1 = Interface
2 = Endpoint
3 = Other
4-31 = Reserved |
|
1
|
bRequest
|
1
|
Value
|
Specific
Request
|
2
|
wValue
|
2
|
Value
|
Use
varies according to request
|
4
|
wIndex
|
2
|
Index
or Offset
|
Use
varies according to request
|
6
|
wLength
|
2
|
Count
|
Number
of bytes to transfer if there is a data stage
|
The meaning of the 8
bytes of the SETUP transaction data, which are divided into five
named fields.
|
|
Here is a table which
contains all the standard requests which a host can send. The first
5 columns are the SETUP transaction fields in order, and the last
column describes any accompanying data stage data which will have
the length wLength.
bmRequestType
|
bRequest
|
wValue
|
wIndex
|
wLength
|
Data
|
00000000b
00000001b
00000010b
|
CLEAR_FEATURE
(1)
|
Feature
Selector
|
Zero
Interface
Endpoint
|
Zero
|
None
|
10000000b
|
GET_CONFIGURATION
(8)
|
Zero
|
Zero
|
One
|
Configuration
Value
|
10000000b
|
GET_DESCRIPTOR
(6)
|
Descriptor
Type (H) and Descriptor Index (L)
|
Zero
or Language ID
|
Descriptor
Length
|
Descriptor
|
10000001b
|
GET_INTERFACE
(10)
|
Zero
|
Interface
|
One
|
Alternate
Interface
|
10000000b
10000001b
10000010b
|
GET_STATUS
(0)
|
Zero
|
Zero
Interface
Endpoint
|
Two
|
Device,
Interface or Endpoint Status
|
00000000b
|
SET_ADDRESS
(5)
|
Device
Address
|
Zero
|
Zero
|
None
|
00000000b
|
SET_CONFIGURATION
(9)
|
Configuration
Value
|
Zero
|
Zero
|
None
|
00000000b
|
SET_DESCRIPTOR
(7)
|
Descriptor
Type (H) and Descriptor Index (L)
|
Zero
or Language ID
|
Descriptor
Length
|
Descriptor
|
00000000b
00000001b
00000010b
|
SET_FEATURE
(3)
|
Feature
Selector
|
Zero
Interface
Endpoint
|
Zero
|
None
|
00000001b
|
SET_INTERFACE
(11)
|
Alternate
Setting
|
Interface
|
Zero
|
None
|
10000010b
|
SYNCH_FRAME
(12)
|
Zero
|
Endpoint
|
Two
|
Frame
Number
|
|
GET_DESCRIPTOR
It is probable that this
request (with the descriptor type set to Device) will be
the first that will be received after USB reset. The host needs
to know the max packet length in use by the control endpoint and
this information is available in the 8th byte of the device descriptor.
Typically when the host
is Windows, the device will receive the request with the required
length wLength set to 64. The host will then input 1 packet,
and then reset the device again. Whatever the value of the max packet
length, the host now has the value of the 8th byte and knows what
the packet size is for all future control transfers.
The second reset is probably
to guarantee that the device does not get confused after not being
allowed to complete the transmission of all 18 bytes of the device
descriptor.
|
|
Descriptor
Types
|
Value
|
Comments
|
Device
|
1
|
|
Configuration
|
2
|
Request
for this also returns OTG, interface and endpoint descriptors
|
String
|
3
|
Qualified
by an index to specify which string is required
|
Interface
|
4
|
Not
directly accessible
|
Endpoint
|
5
|
Not
directly accessible
|
Device
Qualifier
|
6
|
Only
for high speed capable devices
|
Other
Speed Configuration
|
7
|
Only
for high speed capable devices
|
Interface
Power
|
8
|
Obsolete
|
On-The-Go
(OTG)
|
9
|
Not
directly accessible
|
Table
of wValues use in Get Descriptor requests to select the required
descriptor.
|
Device Descriptor
This descriptor will
most likely be the first one fetched by the host. We should point
out some important features.
bLength and bDescriptorType
All descriptors start
with a single byte specifying the descriptor's length, and this
is always followed by a single byte defining the descriptor type.
bcdUSB
The only valid version
numbers are 0x0100 (USB1.0), 0x0110 (USB1.1) and 0x0200 (USB2.0).
If you design a new device it should be identified as USB2.0 because
that is the current specification.
bDeviceClass, bDeviceSubClass
and bDeviceProtocol
This triplet of values
is used to describe the class of the device in various ways as defined
in the various class specification documents from the USB-IF.
idVendor, idProduct
and bcdDevice
The combination of idVendor
and idProduct (also known as the VID and PID) must be unique for
the device. This means that the VID you use must be one issued by
the USB-IF and which you have the right to use. You can either buy
a VID from the USB-IF, or you may be able to acquire the right to
use a VID from another manufacturer together with a particular PID
which they have issued to you. If you use a VID/PID combination
which is already in use then you will probably have major problems
with your product in the field.
|
|
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bLength
|
1
|
Number
|
Size
of this descriptor in bytes
|
1
|
bDescriptorType
|
1
|
Constant
|
DEVICE
descriptor type (= 1)
|
2
|
bcdUSB
|
2
|
BCD
|
USB
Spec release number
|
4
|
bDeviceClass
|
1
|
Class
|
Class
code assigned by USB-IF |
00h
means each interface defines its own class |
FFh
means vendor-defined class |
Any
other value must be a class code |
|
5
|
bDeviceSubClass
|
1
|
SubClass
|
SubClass
Code assigned by USB-IF
|
6
|
bDeviceProtocol
|
1
|
Protocol
|
Protocol
Code assigned by USB-IF
|
7
|
bMaxPacketSize0
|
1
|
Number
|
Max
packet size for endpoint 0.
Must be 8, 16, 32 or 64
|
8
|
idVendor
|
2
|
ID
|
Vendor
ID - must be obtained from USB-IF
|
10
|
idProduct
|
2
|
ID
|
Product
ID - assigned by the manufacturer
|
12
|
bcdDevice
|
2
|
BCD
|
Device
release number in binary coded decimal
|
14
|
iManufacturer
|
1
|
Index
|
Index
of string descriptor describing manufacturer - set to 0 if
no string
|
15
|
iProduct
|
1
|
Index
|
Index
of string descriptor describing product - set to 0 if no string
|
16
|
iSerialNumber
|
1
|
Index
|
Index
of string descriptor describing device serial number - set
to 0 if no string
|
17
|
bNumConfigurations
|
1
|
Number
|
Number
of possible configurations
|
Device
Descriptor
|
SET_ADDRESS
After the host has determined
the max packet size for endpoint 0, it is in a position to begin
normal communications with the device. As mentioned above, there
may be a second reset from the host. The host now needs to issue
a SET_ADDRESS request to the device, so that each device on the
bus has a unique address to respond to.
SET_ADDRESS is a simple,
outward direction request in a control transfer with no data stage.
The only useful information carried in the SETUP packet is the required
address.
When implementing this
request in firmware, you should note the following. All other requests
must be actioned before the status stage in completed. But in the
case of SET_ADDRESS, you should not change the device address until
after the status stage. The status stage will not succeed
unless the device is still responding to address 0 while it is taking
place. The device then has 2ms to get ready to respond to the new
address.
|
|
When
are requests valid?
The device
can be in one of three states which determine whether a particular
request is valid at the time.
The states
are:
Default
After
reset but before receiving Set Address.
In the
Default state, the only valid requests are Get Descriptor,
and Set Address.
Addressed
After
the device has been assigned an address via Set Address.
Now the
device must recognise the following additional requests:
- Set
Configuration
- Get
Configuration
- Set
Feature
- Clear
Feature
- Get
Status
- Set
Descriptor (optional)
Configured
After
the host has sent Set Configuration with a non-zero value,
to select a configuration. The device is now operational.
In the
Configured state, only Set Address is not a valid request.
Three further requests are restricted to Configured state
only:
- Get
Interface
- Set
Interface
- Synch
Frame
Note
that this was only a brief overview. The specification gives
more detailed information, which you should read when implementing
a USB device. |
|
Other Information Gathering
Commands
The host is likely to
start using the GET_DESCRIPTOR request mentioned above, to fetch
other information describing the device. A major piece of this information
is the configuration descriptor.
|
|
The actual descriptor
which is fetched by a GET_DESCRIPTOR request is determined
by the high byte of the wValue word in the SETUP data.
So the request
we call here 'Get Descriptor (Configuration)' is simply a
Get Descriptor request with the high byte of wValue
set to 2.
|
|
Get Descriptor (Configuration)
The Get Descriptor (Configuration)
warrants special explanation, because the request results in not
just a Configuration Descriptor being returned, but also some or
all of a number of other descriptors:
- Interface Descriptor
- Endpoint Descriptor
- OTG Descriptor
- Class-specific Descriptors
- Vendor-specific Descriptors
A Get Configuration Descriptor
fetches the descriptors for just one configuration depending on
the descriptor index in wValue of the SETUP packet. Most devices
only have one configuration, because built-in Windows drivers always
select the first configuration.
The diagram opposite
shows a typical set of Descriptors which is fetched. It starts with
the configuration descriptor, and the vertical position shows the
correct sequence, with the interfaces being dealt with in turn,
each one followed by its own endpoints.
The position of class
descriptors is defined in the appropriate class specification, and
of course vendors descriptor positions would be up to the vendor
concerned.
An OTG descriptor position
is not defined but typically appears immediately after the configuration
descriptor.
|
|
|
Configuration Descriptor
The configuration descriptor
format is shown to the right.
The wTotalLegth value
is important because it tells the host how many bytes are contained
in this descriptor and all the descriptors which follow.
bNumInterfaces describes
how many interfaces this configuration supports.
|
|
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bLength
|
1
|
Number
|
Size
of this descriptor in bytes
|
1
|
bDescriptorType
|
1
|
Constant
|
CONFIGURATION
descriptor type (= 2)
|
2
|
wTotalLength
|
2
|
Number
|
Total
number of bytes in this descriptor and all the following descriptors.
|
4
|
bNumInterfaces
|
1
|
Number
|
Number
of interfaces supported by this configuration
|
5
|
bConfigurationValue
|
1
|
Number
|
Value
used by Set Configuration to select this configuration
|
6
|
iConfiguration
|
1
|
Index
|
Index
of string descriptor describing configuration - set to 0 if
no string
|
7
|
bmAttributes
|
1
|
Bitmap
|
D7:
Must be set to 1
D6: Self-powered
D5: Remote Wakeup
D4...D0:
Set to 0
|
8
|
bMaxPower
|
1
|
mA
|
Maximum
current drawn by device in this configuration. In units of
2mA. So 50 means 100 mA.
|
Configuration
Descriptor
|
Interface Descriptor
The interface descriptor
format is shown to the right.
bAlternateSetting needs
some explanation. An interface can have more than one variant, and
these variants can be switched between, while other interfaces are
still in operation.
For the first (and default)
alternative bAlternateSetting is always 0.
To have a second interface
variant, the default interface descriptor would be followed by its
endpoint descriptors, which would then be followed by the alternative
interface descriptor and then its endpoint descriptors.
bInterfaceClass, bInterfaceSubClass
and bInterfaceProtocol
By defining the class,
subclass and protocol in the interface, it is possible to have interfaces
with different classes in the same device. This is referred to as
a composite device.
|
|
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bLength
|
1
|
Number
|
Size
of this descriptor in bytes |
1
|
bDescriptorType
|
1
|
Constant
|
INTERFACE
descriptor type (= 4) |
2
|
bInterfaceNumber
|
1
|
Number
|
Number
identifying this interface. Zero-based value. |
3
|
bAlternateSetting
|
1
|
Number
|
Value
used to select this alternate setting for this interface. |
4
|
bNumEndpoints
|
1
|
Number
|
Number
of endpoints used by this interface. Doesn't include control
endpoint 0. |
5
|
bInterfaceClass
|
1
|
Class
|
Class
code assigned by USB-IF |
00h
is a reserved value |
FFh
means vendor-defined class |
Any
other value must be a class code |
|
6
|
bInterfaceSubClass
|
1
|
SubClass
|
SubClass
Code assigned by USB-IF |
7
|
bInterfaceProtocol
|
1
|
Protocol
|
Protocol
Code assigned by USB-IF |
8
|
iInterface
|
1
|
Index
|
Index
of string descriptor describing interface - set to 0 if no string |
Interface
Descriptor
|
Endpoint Descriptor
The endpoint descriptor
format is shown to the right.
|
|
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bLength
|
1
|
Number
|
Size
of this descriptor in bytes |
1
|
bDescriptorType
|
1
|
Constant
|
ENDPOINT
descriptor type (= 5) |
2
|
bEndpointAddress
|
1
|
Endpoint
|
The address
of this endpoint within the device.
D7: Direction
0 = OUT, 1 = IN
D6-D4:
Set to 0
D3-D0:
Endpoint number
|
3
|
bmAttributes
|
1
|
Bitmap
|
D1:0
Transfer Type |
00
= Control
01 = Isochronous
10 = Bulk
11 = Interrupt |
The
following only apply to isochronous endpoints. Else set
to 0. |
D3:2
Synchronisation Type |
00
= No Synchronisation
01 = Asynchronous
10 = Adaptive
11 = Synchronous |
D5:4
Usage Type |
00
= Data endpoint
01 = Feedback endpoint
10 = Implicit feedback Data endpoint
11 = Reserved |
D7:6
Reserved |
Set
to 0 |
|
4
|
wMaxPacketSize
|
2
|
Number
|
Maximum
packet size this endpoint can send or receive when this configuration
is selected |
6
|
bInterval
|
1
|
Number
|
Interval
for polling endpoint for data transfers. Expressed in frames
(ms) for low/full speed or microframes (125us) for high speed.
|
Endpoint
Descriptor
|
Get Descriptor (String)
There are several strings
which a host may request. The strings defined in the device descriptor
are:
- Manufacturer String
- Product String
- Serial Number String
These strings are optional.
If not supported, the corresponding index in the device descriptor
will be 0. Otherwise the host may use the specified index in a Get
Descriptor (String) request to fetch the descriptor.
Get Descriptor (String),
with a descriptor index of 0 in the low byte of wValue, is used
to fetch a special string language descriptor. This contains a series
of 2-byte sized language specifiers. In theory, if the language
of your choice is supported in this list, you can use the index
to this language ID to access the string descriptors in this language
by specifying this in wIndex of the Get Descriptor (String) request.
In practise, with Windows, you will have difficulties if you do
not ensure that the first language specified is English (US).
|
|
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bLength
|
1
|
Number
|
Size
of this descriptor in bytes
|
1
|
bDescriptorType
|
1
|
Constant
|
STRING
descriptor type (= 3)
|
2
|
wLANGID[0]
|
2
|
Number
|
LANGID
Code 0
|
...
|
...
|
...
|
...
|
...
|
2
+ x*2
|
wLANGID[x]
|
2
|
Number
|
LANGID
Code x
|
String
Descriptor Zero
(Specifies
supported string languages)
Offset
|
Field
|
Size
|
Value
|
Description
|
0
|
bLength
|
1
|
Number
|
Size
of this descriptor in bytes
|
1
|
bDescriptorType
|
1
|
Constant
|
STRING
descriptor type (= 3)
|
2
|
bString
|
2
|
Number
|
UNICODE
encoded string
|
String
Descriptor
|
SET_CONFIGURATION
When the host has got
all the information it requires it loads a driver for the device
based on the VID/PID combination in the device descriptor, or on
the standard class defined there or in an interface descriptor.
The driver may also ask
for the same or different information using Get Descriptor requests.
Eventually it will decide
to configure the device using the SET_CONFIGURATION request.
Usually ( when there is one configuration) the Set Configuration
request will have wValue set to 1, which will select the first configuration.
Set Configuration can
also be used, with wValue set to 0, to deconfigure the device.
|
|
A Configured Device
Once a device has
been configured, it is allowed to respond to other transfer
types than Control transfers.
As we have seen,
the other transfer types are
- Interrupt Transfers
- Bulk Transfers
- Isochronous
Transfers
As a result of
the information in the descriptors, the host will now know
what particular transfers on which particular endpoints the
device is prepared to support. There may now also be new class
or vendor-specific requests which may now be supported on
the control endpoint in addition to the standard requests.
It is all these
additional transfers which perform the functionality that
the device was designed for.
|
|
GET_CONFIGURATION
This request compliments
Set Configuration, and simply allows the host to determine which
configuration it previously set.
|
|
|
SET_FEATURE
CLEAR_FEATURE
This pair of requests
is used to control a small number of on-off features on a device,
an interface or an endpoint.
A device has 5 possible
features, an endpoint has one, and an interface actually has none
at all.
The greyed out features
shown in the table only apply to OTG devices.
ENDPOINT_HALT
Setting this feature
will cause an endpoint to STALL any IN or OUT transactions.
DEVICE_REMOTE_WAKEUP
Setting this feature
allows a device which is then suspended to use resume signalling
to gain the host's attention.
|
|
Feature
Selector
|
Recipient
|
Value
|
ENDPOINT_HALT
|
Endpoint
|
0
|
DEVICE_REMOTE_WAKEUP
|
Device
|
1
|
TEST_MODE
|
Device
|
2
|
B_HNP_ENABLE
|
Device
|
3
|
A_HNP_SUPPORT
|
Device
|
4
|
A_ALT_HNP_SUPPORT
|
Device
|
5
|
Table
of wValues used in Set Feature and Clear Feature requests.
|
GET_STATUS
This request is used
to fetch status bits from a device, an interface or an endpoint.
In each case the request fetches 16 bits (2 bytes). The tables to
the right show the status bits which are currently implemented.
Note that Remote Wakeup
and Halt status bits can both be controlled by the host using Set.Clear
Feature requests, but the Self-powered bit is only controlled by
the device.
|
|
Status
Bit |
Purpose |
Comment |
D0
|
Self
Powered
|
Set
to 1 by the device when it is self-powered |
D1
|
Remote
Wakeup
|
Set
to 1 if the device has been enabled to signal remote wakeup. |
D2
- D15
|
reserved
|
Must
be set to 0 |
Device
Status Bits
Status
Bit |
Purpose |
Comment |
D0
- D15
|
reserved
|
Must
be set to 0 |
Interface
Status Bits
Status
Bit |
Purpose |
Comment |
D0
|
Halt
|
Set
to 1 when endpoint is halted |
D1
- D15
|
reserved
|
Must
be set to 0 |
Endpoint
Status Bits
|
SET_INTERFACE
GET_INTERFACE
Once a device has been
configured the host may use Set Interface to select an alternative
interface to a particular default interface. It can use the Get
Interface to determine which interface alternative it previous set
for a particular interface.
|
|
|
SYNCH_FRAME
This is used with some
isochronous transfer where the transfer size varies with the frame.
See USB 2.0 specification for more details.
|
|
|
SET_DESCRIPTOR
This Standard request
is optional and not often used. It allows the host to specify a
new set of values for a given descriptor. It is hard to imagine
when this might be of value.
|
|
|
Summary
We have looked at the
set of standard requests which a device must support to become operational.
|
|
|
Coming up...
Next we will examine
the complete enumeration and start of operation of a specific device.
|
|
Forward |
Copyright
© 2006-2008 MQP Electronics Ltd
|
|
|
ADVERTISEMENT
Packet-Master
USB Bus Analysers and Generators from MQP Electronics
|
|
|
|
|
- Radically
cut development time
- Intuitive
graphical interface
- Detailed
timing information
- Full
analysis of all standard events
- Results
can be printed
- Optional
class analysis modules
|
|
|