<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-AD195629-81CE-5E57-A59E-C67AACF7A2C2" xml:lang="en"><title>USB
Client Driver Technology</title><shortdesc>This topic describes the technology that the USB Client Driver
provides.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-2FF7A568-3908-4AF5-ABA7-2A2F92E2D063"><title>USB</title> <p>The Universal Serial Bus (USB) is a high speed
data transport mechanism that uses a 4 wire cable attached to a USB Host to
transfer signals and bus power to low cost peripherals (clients). Theoretically,
up to 127 devices (such as keyboards, video cameras etc.) can share the bus,
although less than four devices is more typical. </p> <p>There are two versions
of the USB standard in use: V1.1 and V2.0. The following table shows the speeds
supported by the different versions: </p> <p><b>USB Speeds </b> </p> <table id="GUID-EEBE7ED4-EB35-5E1D-B3FA-7518F6C4D2DE">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<tbody>
<row>
<entry><p> <b> Name</b>  </p> </entry>
<entry><p> <b>Rate</b>  </p> </entry>
<entry><p> <b>USB Version</b>  </p> </entry>
</row>
<row>
<entry><p>High Speed </p> </entry>
<entry><p>480Mbit/s </p> </entry>
<entry><p>2.0 only </p> </entry>
</row>
<row>
<entry><p>Low Speed </p> </entry>
<entry><p>12Mbits/s </p> </entry>
<entry><p>1.1 and 2.0 </p> </entry>
</row>
<row>
<entry><p>Full Speed </p> </entry>
<entry><p>1.5Mbits/s </p> </entry>
<entry><p>1.1 and 2.0 </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>As the table shows USB V2.0 adds support for the higher speed
of 480Mbit/s. </p> <p>The USB system consists of single USB host controller
(the USB Host) connected to a number of USB peripheral devices. The host is
the bus master, initiating all transactions over the bus. </p> <p>A client
device is a USB peripheral device. It is connected to a USB Controller and
responds to transactions addressed to it from the Controller. The Universal
Serial Bus Specification 1.1 describes how a USB Host sends commands to a
peripheral and how data can be transferred from and to a Client. The main
points are: </p> <ul>
<li id="GUID-F247C990-BE75-52EE-8F5F-BA1726541336"><p>USB is a Host polled
bus. This means that a peripheral cannot send a data packet unless the Host
has requested it. The request must either be accepted, and the data packet
sent within a given time period, or refused. </p> </li>
<li id="GUID-F517A353-4B3F-5EE2-8432-B10718774A85"><p>Every peripheral attached
to the USB is allocated a unique device address. The Host uses the device
address to direct its communication to a particular device. In fact, the Host
sees the peripheral as a collection of endpoints. Each endpoint is an address
within the peripheral to which the Host sends packets or from which the Host
receives packets. </p> </li>
<li id="GUID-35285198-7F18-5ABA-B0B8-1E4437CA65A6"><p>Endpoints are grouped
together by the peripheral into Interfaces. The Host regards each peripheral
as a set of functions and communicates with each function via its Interface.
Simple devices, such as mice, contain only one function, other devices may
contain more than one function, e.g. a monitor may contain speakers and a
microphone. </p> </li>
<li id="GUID-1BDEBAC5-23C0-5CDD-A6BD-1CCB6D1B0EC3"><p>Each function requires
its own driver at the Host end which communicates with the function within
the peripheral using a USB class driver or vendor defined protocol. The function
informs the Host what protocol it understands via its Interface. </p> </li>
</ul> <p>The USB Client Driver supports: </p> <ul>
<li id="GUID-B5051F6F-9E1E-5A79-B45A-D81B7A94EA23"><p>multiple USB interfaces,
i.e. it supports licensee products that implement multiple USB interfaces
simultaneously </p> </li>
<li id="GUID-31AC620E-4DD3-51B9-9492-E0C3EB0C8751"><p>alternate USB interfaces </p> </li>
<li id="GUID-D9563D5D-679E-540C-AA96-B55CB65578FC"><p>a single USB Configuration
only; the API does not provide a mechanism for specifying more than one USB
configuration. </p> </li>
<li id="GUID-CD97C393-9630-5A56-934A-D2453CEAA56C"><p>extended standard endpoint
descriptors. </p> </li>
<li id="GUID-28F9D219-0FD8-57FD-867D-2AA2E5461914"><p>reading and modifying
standard descriptors. </p> </li>
<li id="GUID-8AF1738D-3321-5503-8440-2F8782658BD9"><p>setting class specific
interface and endpoint descriptors. </p> </li>
<li id="GUID-6665A0F8-E1DD-5CB9-98AD-79D5BE63B074"><p>remote wakeup signalling. </p> </li>
<li id="GUID-15199F33-31AB-54E0-B427-1B68B946213E"><p>reading device directed
Ep0 (Endpoint Zero) traffic. </p> </li>
</ul> </section>
<section id="GUID-1ECB4FAF-745C-52CE-92A4-9077ABB585C3"><title>Endpoint types</title> <p>There
are four endpoint types corresponding to the four transfer types: </p> <ul>
<li id="GUID-63D3194C-E3B0-5C76-9A11-398963275D38"><p>Control endpoints </p> </li>
<li id="GUID-BC5DBF35-B82D-554F-AF6A-325316248464"><p>Bulk endpoints </p> </li>
<li id="GUID-C33C7BF8-9E81-5541-ABE4-DF31CF101977"><p>Interrupt endpoints </p> </li>
<li id="GUID-549981D7-9AC8-5D2A-BDC8-9643F8C27B9F"><p>Isochronous endpoints. </p> </li>
</ul> <p><b>Control
endpoints</b> </p> <p>These are serially bi-directional. This means that they
can send and receive data, but not simultaneously. </p> <p>Every peripheral
has at least one control endpoint. Although other control endpoints are possible,
Symbian platform only allows Endpoint zero (Ep0) as the control endpoint.
Ep0 is a shared resource, which must always be available. </p> <p>Ep0 is vital
for the operation of the device. Its primary function is the control endpoint
for the Host. When the device is first connected to the Host, a process known
as enumeration must occur, and this takes place through Ep0. During enumeration,
the client tells the Host what kind of device it is and what classes it supports.
Enumeration is complete, for the purpose of writing client drivers, when the
Host moves the client into its configured state. The Host moves the client
into its configured state when a Host driver is available to communicate with
the client. </p> <p>Ep0 needs handling with some sensitivity. Every request
arriving on Ep0 must be handled either by the Controller or by a client class
driver. Each request must be moved through the data phase, even if there is
no associated request data, so that the status phase may begin. It is imperative
that this happens otherwise endpoint zero will be unable to accept any further
requests. This could result in the Host stopping communication with the device. </p> <p><b>Bulk endpoints</b> </p> <p>These are unidirectional. They can have the
IN or the OUT direction. </p> <p>The IN direction means sending packets to
the Host. The OUT direction means receiving packets from the Host. </p> <p>Bulk
endpoints can supply a maximum of 64 bytes of data per packet, but such transfers
have no guaranteed bus bandwidth. </p> <p><b>Interrupt
endpoints</b> </p> <p>Interrupt endpoints are similar to Bulk endpoints but,
in addition, the endpoint descriptor specifies how often the Host should poll
the endpoint for data. The polling frequency may be anything from 1ms to 255ms. </p> <p><b>Isochronous endpoints</b> </p> <p>Isochronous endpoints can deliver up
to 1023 bytes of data per packet, but there is no retry capability if an error
is detected. Like Interrupt endpoints, they have an associated polling frequency,
which is fixed at 1ms. </p> </section>
<section id="GUID-A2A987CD-2DEA-5B40-8C42-157DD36BA2CA"><title>Endpoint numbering</title> <p>Two
numbering schemes are used within the USB implementation. There is also the
external USB address numbering scheme. </p> <p id="GUID-2CFB38E0-0A98-516C-B4EE-DECCD65F824A"><b>Virtual endpoint numbers</b> </p> <p>Applications
or class drivers use virtual endpoints when communicating with the USB client
driver. These numbers are used when exchanging data over the USB. </p> <p>Virtual
endpoints range in value from 1 to <xref href="GUID-CB8EA082-EA6E-3A7E-81C7-E06A6F8DD9B8.dita"><apiname>KMaxEndpointsPerClient</apiname></xref>,
and applications refer to these endpoints by number when using the user side
handle to the USB client driver. </p> <p>For applications that implement a
specific USB device class, and which need access to endpoint-0, virtual endpoint-0
is available. This endpoint is special because it does not belong to any specific
interface. It is always available and, at the interface to the USB client
driver, is the only bi-directional endpoint. </p> <p><b>Implementation note </b> </p> <p>Within the platform independent layer,
virtual endpoint numbers are represented by instances of the internal class <codeph>TUsbcLogicalEndpoint</codeph>.
Note that there is no representation for virtual endpoint-0. </p> <p><b>Physical endpoints</b> </p> <p>Physical (or 'real') endpoints are used
at the interface between the platform independent layer and the platform specific
layer within the USB client controller. They represent endpoints physically
present on a given device. </p> <p><b>Implementation note </b> </p> <p>Within the platform independent layer,
physical endpoint numbers are represented by instances of the internal class <codeph>TUsbcPhysicalEndpoint</codeph>,
in the array represented by the internal data member <codeph>DUsbClientController::iRealEndPoints</codeph>. </p> <p>To
simplify array indexing, the numbering scheme uses "transformed" USB endpoint
addresses. We represent each channel as a separate endpoint, RX (OUT) channel
as <codeph>iRealEndpoints[n]</codeph> and TX (IN) channel as <codeph>iRealEndpoints[n
+ 1]</codeph>. </p> <p id="GUID-8592C90D-ECA7-59CB-A419-0C4ABDEB9229"><b>Canonical endpoint numbers</b> </p> <p>The
two layers of the USB client controller, i.e. the Platform Independent layer
and the Platform Specific layer, use a numbering system known as canonical
endpoint numbers when communicating between each other. The physical endpoint
numbers are never used explicitly. </p> <p>This system is based upon the physical
endpoint number, but takes the direction of the endpoint into account. If <codeph>r</codeph> is
the physical endpoint number, then the corresponding canonical endpoint number
is a value defined as: </p> <ul>
<li id="GUID-DFD56EC6-7B4D-58C2-96E3-E232D9D26494"><codeblock id="GUID-2A405E0A-857A-5978-9BE7-2C4193CA16D8" xml:space="preserve">2r + 1</codeblock> <p>if
the endpoint direction is IN </p> </li>
<li id="GUID-FD8BABD6-39E5-54E5-A4D6-EA5F809B0D28"><codeblock id="GUID-A868BFCC-6FB7-501D-8CAE-D2ECB56B78DA" xml:space="preserve">2r</codeblock> <p>if
the endpoint direction is OUT </p> </li>
</ul> <p>This means that canonical endpoint numbers fall into a range from
0 to 31. </p> <p>For example, Endpoint 0 (Ep0) is represented by 2 canonical
endpoint numbers: </p> <ul>
<li id="GUID-9A9D6B64-C15D-554A-B34B-90521659600A"><p>0, representing Ep0(OUT) </p> </li>
<li id="GUID-B85424E3-D704-5EDA-87E8-2216BA1878DF"><p>1, representing Ep0(IN). </p> </li>
</ul> <p id="GUID-4037A87D-802A-5FD5-A0B5-2A002A0FD092"><b>Converting between Endpoint
number representations</b> </p> <p>It is possible to convert between the Endpoint
Address representation and the Canonical Endpoint. The following text explains
how these values are stored in memory and shows the conversion process: </p> <p><b>Endpoint Address </b> </p> <fig id="GUID-0135DF6D-895B-53E0-A2EA-8E7F0EF6BBDE">
<desc><p>where the numbers 0-7 represent bits 0-7 of the byte containing the
endpoint address. </p> <p>D = Direction: 0 = Receive/IN, 1 = Transmit/OUT </p> <p>P3
P2 P1 P0 represents the physical endpoint number (0-15) </p> </desc>
<image href="GUID-59FF3BFE-21E2-554D-99EC-1A1D34AAEB7C_d0e35295_href.png" placement="inline"/>
</fig> <p><b>Canonical Endpoint Number </b> </p> <p>The canonical endpoint number is
just the endpoint address rotated left by 1 bit as shown below: </p> <fig id="GUID-237E227A-03E7-5BDE-B8E0-AA96FB74CA36">
<image href="GUID-CDDD8189-D532-5179-92F6-74264C2E3D81_d0e35308_href.png" placement="inline"/>
</fig> <p><b>Summary
of Endpoint Number Representations</b> </p> <p>The APIs use the following
conventions for representing endpoint numbers types: </p> <table id="GUID-E5C3C773-3D6F-521C-B012-11A13E8008C7">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>Name</b>  </p> </entry>
<entry><p> <b> Endpoint number</b>  </p> </entry>
</row>
<row>
<entry><p> <codeph>aRealEndpoint</codeph>  </p> </entry>
<entry><p>Canonical Endpoint Number </p> </entry>
</row>
<row>
<entry><p> <codeph>aEndpointNum</codeph>  </p> </entry>
<entry><p>Virtual Endpoint Number </p> </entry>
</row>
<row>
<entry><p> <codeph>aAddress</codeph>  </p> </entry>
<entry><p>Endpoint Address </p> </entry>
</row>
<row>
<entry><p> <b>n/a</b>  </p> </entry>
<entry><p>Physical Endpoint Number </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
</conbody></concept>