doc/html/ref/usbs-intro.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Introduction</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="eCos USB Slave Support"
  23 HREF="io-usb-slave.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="eCos USB Slave Support"
  26 HREF="io-usb-slave.html"><LINK
  27 REL="NEXT"
  28 TITLE="USB Enumeration Data"
  29 HREF="usbs-enum.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="io-usb-slave.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="usbs-enum.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="USBS-INTRO">Introduction</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16043"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Introduction&nbsp;--&nbsp;eCos support for USB slave devices</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN16046"
  95 ></A
  96 ><H2
  97 >Introduction</H2
  98 ><P
  99 >The eCos USB slave support allows developers to produce USB
 100 peripherals. It consists of a number of different eCos packages:</P
 101 ><P
 102 ></P
 103 ><OL
 104 TYPE="1"
 105 ><LI
 106 ><P
 107 >Device drivers for specific implementations of USB slave hardware, for
 108 example the on-chip USB Device Controller provided by the Intel SA1110
 109 processor. A typical USB peripheral will only provide one USB slave
 110 port and therefore only one such device driver package will be needed.
 111 Usually the device driver package will be loaded automatically when
 112 you create an eCos configuration for target hardware that has a USB
 113 slave device. If you select a target which does have a USB slave
 114 device but no USB device driver is loaded, this implies that no such
 115 device driver is currently available.</P
 116 ></LI
 117 ><LI
 118 ><P
 119 >The common USB slave package. This serves two purposes. It defines the
 120 API that specific device drivers should implement. It also provides
 121 various utilities that will be needed by most USB device drivers and
 122 applications, such as handlers for standard control messages.
 123 Usually this package will be loaded automatically at the same time as
 124 the USB device driver.</P
 125 ></LI
 126 ><LI
 127 ><P
 128 >The common USB package. This merely provides some information common
 129 to both the host and slave sides of USB, such as details of the
 130 control protocol. It is also used to place the other USB-related
 131 packages appropriately in the overall configuration hierarchy. Usually
 132 this package will be loaded at the same time as the USB device driver.</P
 133 ></LI
 134 ><LI
 135 ><P
 136 >Class-specific USB support packages. These make it easier to develop
 137 specific classes of USB peripheral, such as a USB-ethernet device. If
 138 no suitable package is available for a given class of peripheral then
 139 the USB device driver can instead be accessed directly from
 140 application code. Such packages will never be loaded automatically
 141 since the configuration system has no way of knowing what class of USB
 142 peripheral is being developed. Instead developers have to add the
 143 appropriate package or packages explicitly.</P
 144 ></LI
 145 ></OL
 146 ><P
 147 >These packages only provide support for developing USB peripherals,
 148 not USB hosts.</P
 149 ></DIV
 150 ><DIV
 151 CLASS="REFSECT1"
 152 ><A
 153 NAME="AEN16059"
 154 ></A
 155 ><H2
 156 >USB Concepts</H2
 157 ><P
 158 >Information about USB can be obtained from a number of sources
 159 including the <A
 160 HREF="http://www.usb.org/"
 161 TARGET="_top"
 162 >USB Implementers Forum
 163 web site</A
 164 >. Only a brief summary is provided here.</P
 165 ><P
 166 >A USB network is asymmetrical: it consists of a single host, one or
 167 more slave devices, and possibly some number of intermediate hubs. The
 168 host side is significantly more complicated than the slave side.
 169 Essentially, all operations are initiated by the host. For example, if
 170 the host needs to receive some data from a particular USB peripheral
 171 then it will send an IN token to that peripheral; the latter should
 172 respond with either a NAK or with appropriate data. Similarly, when
 173 the host wants to transmit data to a peripheral it will send an OUT
 174 token followed by the data; the peripheral will return a NAK if it is
 175 currently unable to receive more data or if there was corruption,
 176 otherwise it will return an ACK. All transfers are check-summed and
 177 there is a clearly-defined error recovery process. USB peripherals can
 178 only interact with the host, not with each other.</P
 179 ><P
 180 >USB supports four different types of communication: control messages,
 181 interrupt transfers, isochronous transfers, and bulk transfers.
 182 Control messages are further subdivided into four categories:
 183 standard, class, vendor and a reserved category. All USB peripherals
 184 must respond to certain standard control messages, and usually this
 185 will be handled by the common USB slave package (for complicated
 186 peripherals, application support will be needed). Class and vendor
 187 control messages may be handled by an class-specific USB support
 188 package, for example the USB-ethernet package will handle control
 189 messages such as getting the MAC address or enabling/disabling
 190 promiscuous mode. Alternatively, some or all of these messages will
 191 have to be handled by application code.</P
 192 ><P
 193 >Interrupt transfers are used for devices which need to be polled
 194 regularly. For example, a USB keyboard might be polled once every
 195 millisecond. The host will not poll the device more frequently than
 196 this, so interrupt transfers are best suited to peripherals that
 197 involve a relatively small amount of data. Isochronous transfers are
 198 intended for multimedia-related peripherals where typically a large
 199 amount of video or audio data needs to be exchanged continuously.
 200 Given appropriate host support a USB peripheral can reserve some of
 201 the available bandwidth. Isochronous transfers are not reliable; if a
 202 particular packet is corrupted then it will just be discarded and
 203 software is expected to recover from this. Bulk transfers are used for
 204 everything else: after taking care of any pending control, isochronous
 205 and interrupt transfers the host will use whatever bandwidth remains
 206 for bulk transfers. Bulk transfers are reliable.</P
 207 ><P
 208 >Transfers are organized into USB packets, with the details depending
 209 on the transfer type. Control messages always involve an initial
 210 8-byte packet from host to peripheral, optionally followed by some
 211 additional packets; in theory these additional packets can be up to 64
 212 bytes, but hardware may limit it to 8 bytes. Interrupt transfers
 213 involve a single packet of up to 64 bytes. Isochronous transfers
 214 involve a single packet of up to 1024 bytes. Bulk transfers involve
 215 multiple packets. There will be some number, possibly zero, of 64-byte
 216 packets. The transfer is terminated by a single packet of less than 64
 217 bytes. If the transfer involves an exact multiple of 64 bytes than the
 218 final packet will be 0 bytes, consisting of just a header and checksum
 219 which typically will be generated by the hardware. There is no
 220 pre-defined limit on the size of a bulk transfer. Instead higher-level
 221 protocols are expected to handle this, so for a USB-ethernet
 222 peripheral the protocol could impose a limit of 1514 bytes of data
 223 plus maybe some additional protocol overhead.</P
 224 ><P
 225 >Transfers from the host to a peripheral are addressed not just to that
 226 peripheral but to a specific endpoint within that peripheral.
 227 Similarly, the host requests incoming data from a specific endpoint
 228 rather than from the peripheral as a whole. For example, a combined
 229 keyboard/touchpad device could provide the keyboard events on endpoint
 230 1 and the mouse events on endpoint 2. A given USB peripheral can have
 231 up to 16 endpoints for incoming data and another 16 for outgoing data.
 232 However, given the comparatively high speed of USB I/O this endpoint
 233 addressing is typically implemented in hardware rather than software,
 234 and the hardware will only implement a small number of endpoints.
 235 Endpoint 0 is generally used only for control messages.</P
 236 ><P
 237 >In practice, many of these details are irrelevant to application code
 238 or to class packages. Instead, such higher-level code usually just
 239 performs blocking <TT
 240 CLASS="FUNCTION"
 241 >read</TT
 242 > and
 243 <TT
 244 CLASS="FUNCTION"
 245 >write</TT
 246 >, or non-blocking USB-specific calls, to
 247 transfer data between host and target via a specific endpoint. Control
 248 messages are more complicated but are usually handled by existing
 249 code.</P
 250 ><P
 251 >When a USB peripheral is plugged into the host there is an initial
 252 enumeration and configuration process. The peripheral provides
 253 information such as its class of device (audio, video, etc.), a
 254 vendor id, which endpoints should be used for what kind of data, and
 255 so on. The host OS uses this information to identify a suitable host
 256 device driver. This could be a generic driver for a class of
 257 peripherals, or it could be a vendor-specific driver. Assuming a
 258 suitable driver is installed the host will then activate the USB
 259 peripheral and perform additional application-specific initialisation.
 260 For example for a USB-ethernet device this would involve obtaining an
 261 ethernet MAC address. Most USB peripherals will be fairly simple, but
 262 it is possible to build multifunction peripherals with multiple
 263 configurations, interfaces, and alternate interface settings.</P
 264 ><P
 265 >It is not possible for any of the eCos packages to generate all the
 266 enumeration data automatically. Some of the required information such
 267 as the vendor id cannot be supplied by generic packages; only by the
 268 application developer. Class support code such as the USB-ethernet
 269 package could in theory supply some of the information automatically,
 270 but there are also hardware dependencies such as which endpoints get
 271 used for incoming and outgoing ethernet frames. Instead it is the
 272 responsibility of the application developer to provide all the
 273 enumeration data and perform some additional initialisation. In
 274 addition, the common USB slave package can handle all the standard
 275 control messages for a simple USB peripheral, but for something like a
 276 multifunction peripheral additional application support is needed.</P
 277 ><DIV
 278 CLASS="NOTE"
 279 ><BLOCKQUOTE
 280 CLASS="NOTE"
 281 ><P
 282 ><B
 283 >Note: </B
 284 >The initial implementation of the eCos USB slave packages involved
 285 hardware that only supported control and bulk transfers, not
 286 isochronous or interrupt. There may be future changes to the USB
 287 code and API to allow for isochronous and interrupt transfers,
 288 especially the former. Other changes may be required to support
 289 different USB devices. At present there is no support for USB remote
 290 wakeups, since again it is not supported by the hardware.</P
 291 ></BLOCKQUOTE
 292 ></DIV
 293 ></DIV
 294 ><DIV
 295 CLASS="REFSECT1"
 296 ><A
 297 NAME="AEN16075"
 298 ></A
 299 ><H2
 300 >eCos USB I/O Facilities</H2
 301 ><P
 302 >For protocols other than control messages, eCos provides two ways of
 303 performing USB I/O. The first involves device table or devtab entries such
 304 as <A
 305 HREF="usbs-devtab.html"
 306 ><TT
 307 CLASS="LITERAL"
 308 >/dev/usb1r</TT
 309 ></A
 310 >,
 311 with one entry per endpoint per USB device. It is possible to
 312 <TT
 313 CLASS="FUNCTION"
 314 >open</TT
 315 > these devices and use conventional blocking
 316 I/O functions such as <TT
 317 CLASS="FUNCTION"
 318 >read</TT
 319 > and
 320 <TT
 321 CLASS="FUNCTION"
 322 >write</TT
 323 > to exchange data between host and
 324 peripheral.</P
 325 ><P
 326 >There is also a lower-level USB-specific API, consisting of functions
 327 such as <A
 328 HREF="usbs-start-rx.html"
 329 ><TT
 330 CLASS="FUNCTION"
 331 >usbs_start_rx_buffer</TT
 332 ></A
 333 >.
 334 A USB device driver will supply a data structure for each endpoint,
 335 for example a <A
 336 HREF="usbs-data.html"
 337 ><SPAN
 338 CLASS="STRUCTNAME"
 339 >usbs_rx_endpoint</SPAN
 340 ></A
 341 >
 342 structure for every receive endpoint. The first argument to
 343 <TT
 344 CLASS="FUNCTION"
 345 >usbs_start_rx_buffer</TT
 346 > should be a pointer to such
 347 a data structure. The USB-specific API is non-blocking: the initial
 348 call merely starts the transfer; some time later, once the transfer
 349 has completed or has been aborted, the device driver will invoke a
 350 completion function.</P
 351 ><P
 352 >Control messages are different. With four different categories of
 353 control messages including application and vendor specific ones, the
 354 conventional
 355 <TT
 356 CLASS="FUNCTION"
 357 >open</TT
 358 >/<TT
 359 CLASS="FUNCTION"
 360 >read</TT
 361 >/<TT
 362 CLASS="FUNCTION"
 363 >write</TT
 364 >
 365 model of I/O cannot easily be applied. Instead, a USB device driver
 366 will supply a <A
 367 HREF="usbs-control.html"
 368 ><SPAN
 369 CLASS="STRUCTNAME"
 370 >usbs_control_endpoint</SPAN
 371 ></A
 372 >
 373 data structure which can be manipulated appropriately. In practice the
 374 standard control messages will usually be handled by the common USB
 375 slave package, and other control messages will be handled by
 376 class-specific code such as the USB-ethernet package. Typically,
 377 application code remains responsible for supplying the <A
 378 HREF="usbs-enum.html"
 379 >enumeration data</A
 380 > and for actually <A
 381 HREF="usbs-start.html"
 382 >starting</A
 383 > up the USB device.</P
 384 ></DIV
 385 ><DIV
 386 CLASS="REFSECT1"
 387 ><A
 388 NAME="AEN16097"
 389 ></A
 390 ><H2
 391 >Enabling the USB code</H2
 392 ><P
 393 >If the target hardware contains a USB slave device then the
 394 appropriate USB device driver and the common packages will typically
 395 be loaded into the configuration automatically when that target is
 396 selected (assuming a suitable device driver exists). However, the
 397 driver will not necessarily be active. For example a processor might
 398 have an on-chip USB device, but not all applications using that
 399 processor will want to use USB functionality. Hence by default the USB
 400 device is disabled, ensuring that applications do not suffer any
 401 memory or other penalties for functionality that is not required.</P
 402 ><P
 403 >If the application developer explicitly adds a class support package
 404 such as the USB-ethernet one then this implies that the USB device is
 405 actually needed, and the device will be enabled automatically.
 406 However, if no suitable class package is available and the USB device
 407 will instead be accessed by application code, it is necessary to
 408 enable the USB device manually. Usually the easiest way to do this is
 409 to enable the configuration option
 410 <TT
 411 CLASS="LITERAL"
 412 >CYGGLO_IO_USB_SLAVE_APPLICATION</TT
 413 >, and the USB device
 414 driver and related packages will adjust accordingly. Alternatively,
 415 the device driver may provide some configuration options to provide
 416 more fine-grained control.</P
 417 ></DIV
 418 ><DIV
 419 CLASS="NAVFOOTER"
 420 ><HR
 421 ALIGN="LEFT"
 422 WIDTH="100%"><TABLE
 423 SUMMARY="Footer navigation table"
 424 WIDTH="100%"
 425 BORDER="0"
 426 CELLPADDING="0"
 427 CELLSPACING="0"
 428 ><TR
 429 ><TD
 430 WIDTH="33%"
 431 ALIGN="left"
 432 VALIGN="top"
 433 ><A
 434 HREF="io-usb-slave.html"
 435 ACCESSKEY="P"
 436 >Prev</A
 437 ></TD
 438 ><TD
 439 WIDTH="34%"
 440 ALIGN="center"
 441 VALIGN="top"
 442 ><A
 443 HREF="ecos-ref.html"
 444 ACCESSKEY="H"
 445 >Home</A
 446 ></TD
 447 ><TD
 448 WIDTH="33%"
 449 ALIGN="right"
 450 VALIGN="top"
 451 ><A
 452 HREF="usbs-enum.html"
 453 ACCESSKEY="N"
 454 >Next</A
 455 ></TD
 456 ></TR
 457 ><TR
 458 ><TD
 459 WIDTH="33%"
 460 ALIGN="left"
 461 VALIGN="top"
 462 >eCos USB Slave Support</TD
 463 ><TD
 464 WIDTH="34%"
 465 ALIGN="center"
 466 VALIGN="top"
 467 ><A
 468 HREF="io-usb-slave.html"
 469 ACCESSKEY="U"
 470 >Up</A
 471 ></TD
 472 ><TD
 473 WIDTH="33%"
 474 ALIGN="right"
 475 VALIGN="top"
 476 >USB Enumeration Data</TD
 477 ></TR
 478 ></TABLE
 479 ></DIV
 480 ></BODY
 481 ></HTML
 482 >