doc/html/ref/usbs-writing.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 >Writing a USB Device Driver</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="Data Endpoints"
  26 HREF="usbs-data.html"><LINK
  27 REL="NEXT"
  28 TITLE="Testing"
  29 HREF="usbs-testing.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="usbs-data.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-testing.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-WRITING">Writing a USB Device Driver</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16705"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Writing a USB Device Driver&nbsp;--&nbsp;USB Device Driver Porting Guide</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN16708"
  95 ></A
  96 ><H2
  97 >Introduction</H2
  98 ><P
  99 >Often the best way to write a USB device driver will be to start with
 100 an existing one and modify it as necessary. The information given here
 101 is intended primarily as an outline rather than as a complete guide.</P
 102 ><DIV
 103 CLASS="NOTE"
 104 ><BLOCKQUOTE
 105 CLASS="NOTE"
 106 ><P
 107 ><B
 108 >Note: </B
 109 >At the time of writing only one USB device driver has been
 110 implemented. Hence it is possible, perhaps probable, that some
 111 portability issues have not yet been addressed. One issue
 112 involves the different types of transfer, for example the initial
 113 target hardware had no support for isochronous or interrupt transfers,
 114 so additional functionality may be needed to switch between transfer
 115 types. Another issue would be hardware where a given endpoint number,
 116 say endpoint 1, could be used for either receiving or transmitting
 117 data, but not both because a single fifo is used. Issues like these
 118 will have to be resolved as and when additional USB device drivers are
 119 written.</P
 120 ></BLOCKQUOTE
 121 ></DIV
 122 ></DIV
 123 ><DIV
 124 CLASS="REFSECT1"
 125 ><A
 126 NAME="AEN16713"
 127 ></A
 128 ><H2
 129 >The Control Endpoint</H2
 130 ><P
 131 >A USB device driver should provide a single <A
 132 HREF="usbs-control.html"
 133 ><SPAN
 134 CLASS="STRUCTNAME"
 135 >usbs_control_endpoint</SPAN
 136 ></A
 137 >
 138 data structure for every USB device. Typical peripherals will have
 139 only one USB port so there will be just one such data structure in the
 140 entire system, but theoretically it is possible to have multiple USB
 141 devices. These may all involve the same chip, in which case a single
 142 device driver should support multiple device instances, or they may
 143 involve different chips. The name or names of these data structures
 144 are determined by the device driver, but appropriate care should be
 145 taken to avoid name clashes. </P
 146 ><P
 147 >A USB device cannot be used unless the control endpoint data structure
 148 exists. However, the presence of USB hardware in the target processor
 149 or board does not guarantee that the application will necessarily want
 150 to use that hardware. To avoid unwanted code or data overheads, the
 151 device driver can provide a configuration option to determine whether
 152 or not the endpoint 0 data structure is actually provided. A default
 153 value of <TT
 154 CLASS="LITERAL"
 155 >CYGINT_IO_USB_SLAVE_CLIENTS</TT
 156 > ensures that
 157 the USB driver will be enabled automatically if higher-level code does
 158 require USB support, while leaving ultimate control to the user.</P
 159 ><P
 160 >The USB device driver is responsible for filling in the
 161 <TT
 162 CLASS="STRUCTFIELD"
 163 ><I
 164 >start_fn</I
 165 ></TT
 166 >,
 167 <TT
 168 CLASS="STRUCTFIELD"
 169 ><I
 170 >poll_fn</I
 171 ></TT
 172 > and
 173 <TT
 174 CLASS="STRUCTFIELD"
 175 ><I
 176 >interrupt_vector</I
 177 ></TT
 178 > fields. Usually this can
 179 be achieved by static initialization. The driver is also largely
 180 responsible for maintaining the <TT
 181 CLASS="STRUCTFIELD"
 182 ><I
 183 >state</I
 184 ></TT
 185 >
 186 field. The <TT
 187 CLASS="STRUCTFIELD"
 188 ><I
 189 >control_buffer</I
 190 ></TT
 191 > array should be
 192 used to hold the first packet of a control message. The
 193 <TT
 194 CLASS="STRUCTFIELD"
 195 ><I
 196 >buffer</I
 197 ></TT
 198 > and other fields related to data
 199 transfers will be managed <A
 200 HREF="usbs-control.html#AEN16615"
 201 >jointly</A
 202 > by higher-level code and
 203 the device driver. The remaining fields are generally filled in by
 204 higher-level code, although the driver should initialize them to NULL
 205 values.</P
 206 ><P
 207 >Hardware permitting, the USB device should be inactive until the
 208 <TT
 209 CLASS="STRUCTFIELD"
 210 ><I
 211 >start_fn</I
 212 ></TT
 213 > is invoked, for example by
 214 tristating the appropriate pins. This prevents the host from
 215 interacting with the peripheral before all other parts of the system
 216 have initialized. It is expected that the
 217 <TT
 218 CLASS="STRUCTFIELD"
 219 ><I
 220 >start_fn</I
 221 ></TT
 222 > will only be invoked once, shortly
 223 after power-up.</P
 224 ><P
 225 >Where possible the device driver should detect state changes, such as
 226 when the connection between host and peripheral is established, and
 227 <A
 228 HREF="usbs-control.html#AEN16552"
 229 >report</A
 230 > these to higher-level
 231 code via the <TT
 232 CLASS="STRUCTFIELD"
 233 ><I
 234 >state_change_fn</I
 235 ></TT
 236 > callback, if
 237 any. The state change to and from configured state cannot easily be
 238 handled by the device driver itself, instead higher-level code such as
 239 the common USB slave package will take care of this.</P
 240 ><P
 241 >Once the connection between host and peripheral has been established,
 242 the peripheral must be ready to accept control messages at all times,
 243 and must respond to these within certain time constraints. For
 244 example, the standard set-address control message must be handled
 245 within 50ms. The USB specification provides more information on these
 246 constraints. The device driver is responsible for receiving the
 247 initial packet of a control message. This packet will always be eight
 248 bytes and should be stored in the
 249 <TT
 250 CLASS="STRUCTFIELD"
 251 ><I
 252 >control_buffer</I
 253 ></TT
 254 > field. Certain standard
 255 control messages should be detected and handled by the device driver
 256 itself. The most important is set-address, but usually the get-status,
 257 set-feature and clear-feature requests when applied to halted
 258 endpoints should also be handled by the driver. Other standard control
 259 messages should first be passed on to the
 260 <TT
 261 CLASS="STRUCTFIELD"
 262 ><I
 263 >standard_control_fn</I
 264 ></TT
 265 > callback (if any), and
 266 finally to the default handler
 267 <TT
 268 CLASS="FUNCTION"
 269 >usbs_handle_standard_control</TT
 270 > provided by the
 271 common USB slave package. Class, vendor and reserved control messages
 272 should always be dispatched to the appropriate callback and there is
 273 no default handler for these.</P
 274 ><P
 275 >Some control messages will involve further data transfer, not just the
 276 initial packet. The device driver must handle this in accordance with
 277 the USB specification and the <A
 278 HREF="usbs-control.html#AEN16615"
 279 >buffer management strategy</A
 280 >. The
 281 driver is also responsible for keeping track of whether or not the
 282 control operation has succeeded and generating an ACK or STALL
 283 handshake. </P
 284 ><P
 285 >The polling support is optional and may not be feasible on all
 286 hardware. It is only used in certain specialised environments such as
 287 RedBoot. A typical implementation of the polling function would just
 288 check whether or not an interrupt would have occurred and, if so, call
 289 the same code that the interrupt handler would.</P
 290 ></DIV
 291 ><DIV
 292 CLASS="REFSECT1"
 293 ><A
 294 NAME="AEN16741"
 295 ></A
 296 ><H2
 297 >Data Endpoints</H2
 298 ><P
 299 >In addition to the control endpoint data structure, a USB device
 300 driver should also provide appropriate <A
 301 HREF="usbs-data.html"
 302 >data
 303 endpoint</A
 304 > data structures. Obviously this is only relevant if
 305 the USB support generally is desired, that is if the control endpoint is
 306 provided. In addition, higher-level code may not require all the
 307 endpoints, so it may be useful to provide configuration options that
 308 control the presence of each endpoint. For example, the intended
 309 application might only involve a single transmit endpoint and of
 310 course control messages, so supporting receive endpoints might waste
 311 memory.</P
 312 ><P
 313 >Conceptually, data endpoints are much simpler than the control
 314 endpoint. The device driver has to supply two functions, one for
 315 data transfers and another to control the halted condition. These
 316 implement the functionality for
 317 <A
 318 HREF="usbs-start-rx.html"
 319 ><TT
 320 CLASS="FUNCTION"
 321 >usbs_start_rx_buffer</TT
 322 ></A
 323 >,
 324 <A
 325 HREF="usbs-start-tx.html"
 326 ><TT
 327 CLASS="FUNCTION"
 328 >usbs_start_tx_buffer</TT
 329 ></A
 330 >,
 331 <A
 332 HREF="usbs-halt.html"
 333 ><TT
 334 CLASS="FUNCTION"
 335 >usbs_set_rx_endpoint_halted</TT
 336 ></A
 337 > and
 338 <A
 339 HREF="usbs-halt.html"
 340 ><TT
 341 CLASS="FUNCTION"
 342 >usbs_set_tx_endpoint_halted</TT
 343 ></A
 344 >.
 345 The device driver is also responsible for maintaining the
 346 <TT
 347 CLASS="STRUCTFIELD"
 348 ><I
 349 >halted</I
 350 ></TT
 351 > status.</P
 352 ><P
 353 >For data transfers, higher-level code will have filled in the
 354 <TT
 355 CLASS="STRUCTFIELD"
 356 ><I
 357 >buffer</I
 358 ></TT
 359 >,
 360 <TT
 361 CLASS="STRUCTFIELD"
 362 ><I
 363 >buffer_size</I
 364 ></TT
 365 >,
 366 <TT
 367 CLASS="STRUCTFIELD"
 368 ><I
 369 >complete_fn</I
 370 ></TT
 371 > and
 372 <TT
 373 CLASS="STRUCTFIELD"
 374 ><I
 375 >complete_data</I
 376 ></TT
 377 > fields. The transfer function
 378 should arrange for the transfer to start, allowing the host to send or
 379 receive packets. Typically this will result in an interrupt at the end
 380 of the transfer or after each packet. Once the entire transfer has
 381 been completed, the driver's interrupt handling code should invoke the
 382 completion function. This can happen either in DSR context or thread
 383 context, depending on the driver's implementation. There are a number
 384 of special cases to consider. If the endpoint is halted when the
 385 transfer is started then the completion function can be invoked
 386 immediately with <TT
 387 CLASS="LITERAL"
 388 >-EAGAIN</TT
 389 >. If the transfer cannot be
 390 completed because the connection is broken then the completion
 391 function should be invoked with <TT
 392 CLASS="LITERAL"
 393 >-EPIPE</TT
 394 >. If the
 395 endpoint is stalled during the transfer, either because of a standard
 396 control message or because higher-level code calls the appropriate
 397 <TT
 398 CLASS="STRUCTFIELD"
 399 ><I
 400 >set_halted_fn</I
 401 ></TT
 402 >, then again the completion
 403 function should be invoked with <TT
 404 CLASS="LITERAL"
 405 >-EAGAIN</TT
 406 >. Finally,
 407 the &#60;<TT
 408 CLASS="FUNCTION"
 409 >usbs_start_rx_endpoint_wait</TT
 410 > and
 411 <TT
 412 CLASS="FUNCTION"
 413 >usbs_start_tx_endpoint_wait</TT
 414 > functions involve
 415 calling the device driver's data transfer function with a buffer size
 416 of 0 bytes.</P
 417 ><DIV
 418 CLASS="NOTE"
 419 ><BLOCKQUOTE
 420 CLASS="NOTE"
 421 ><P
 422 ><B
 423 >Note: </B
 424 >Giving a buffer size of 0 bytes a special meaning is problematical
 425 because it prevents transfers of that size. Such transfers are allowed
 426 by the USB protocol, consisting of just headers and acknowledgements
 427 and an empty data phase, although rarely useful. A future modification
 428 of the device driver specification will address this issue, although
 429 care has to be taken that the functionality remains accessible through
 430 devtab entries as well as via low-level accesses.</P
 431 ></BLOCKQUOTE
 432 ></DIV
 433 ></DIV
 434 ><DIV
 435 CLASS="REFSECT1"
 436 ><A
 437 NAME="AEN16768"
 438 ></A
 439 ><H2
 440 >Devtab Entries</H2
 441 ><P
 442 >For some applications or higher-level packages it may be more
 443 convenient to use traditional open/read/write I/O calls rather than
 444 the non-blocking USB I/O calls. To support this the device driver can
 445 provide a devtab entry for each endpoint, for example:</P
 446 ><TABLE
 447 BORDER="5"
 448 BGCOLOR="#E0E0F0"
 449 WIDTH="70%"
 450 ><TR
 451 ><TD
 452 ><PRE
 453 CLASS="PROGRAMLISTING"
 454 >#ifdef CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY
 455
 456 static CHAR_DEVIO_TABLE(usbs_sa11x0_ep1_devtab_functions,
 457                         &amp;cyg_devio_cwrite,
 458                         &amp;usbs_devtab_cread,
 459                         &amp;cyg_devio_bwrite,
 460                         &amp;cyg_devio_bread,
 461                         &amp;cyg_devio_select,
 462                         &amp;cyg_devio_get_config,
 463                         &amp;cyg_devio_set_config);
 464
 465 static CHAR_DEVTAB_ENTRY(usbs_sa11x0_ep1_devtab_entry,
 466                          CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME "1r",
 467                          0,
 468                          &amp;usbs_sa11x0_ep1_devtab_functions,
 469                          &amp;usbs_sa11x0_devtab_dummy_init,
 470                          0,
 471                          (void*) &amp;usbs_sa11x0_ep1);
 472 #endif</PRE
 473 ></TD
 474 ></TR
 475 ></TABLE
 476 ><P
 477 >Again care must be taken to avoid name clashes. This can be achieved
 478 by having a configuration option to control the base name, with a
 479 default value of e.g. <TT
 480 CLASS="LITERAL"
 481 >/dev/usbs</TT
 482 >, and appending an
 483 endpoint-specific string. This gives the application developer
 484 sufficient control to eliminate any name clashes. The common USB slave
 485 package provides functions <TT
 486 CLASS="FUNCTION"
 487 >usbs_devtab_cwrite</TT
 488 > and
 489 <TT
 490 CLASS="FUNCTION"
 491 >usbs_devtab_cread</TT
 492 >, which can be used in the
 493 function tables for transmit and receive endpoints respectively. The
 494 private field <TT
 495 CLASS="STRUCTFIELD"
 496 ><I
 497 >priv</I
 498 ></TT
 499 > of the devtab entry
 500 should be a pointer to the underlying endpoint data structure.</P
 501 ><P
 502 >Because devtab entries are never accessed directly, only indirectly,
 503 they would usually be eliminated by the linker. To avoid this the
 504 devtab entries should normally be defined in a separate source file
 505 which ends up the special library <TT
 506 CLASS="FILENAME"
 507 >libextras.a</TT
 508 >
 509 rather than in the default library <TT
 510 CLASS="FILENAME"
 511 >libtarget.a</TT
 512 >.</P
 513 ><P
 514 >Not all applications or higher-level packages will want to use the
 515 devtab entries and the blocking I/O facilities. It may be appropriate
 516 for the device driver to provide additional configuration options that
 517 control whether or not any or all of the devtab entries should be
 518 provided, to avoid unnecessary memory overheads.</P
 519 ></DIV
 520 ><DIV
 521 CLASS="REFSECT1"
 522 ><A
 523 NAME="AEN16781"
 524 ></A
 525 ><H2
 526 >Interrupt Handling</H2
 527 ><P
 528 >A typical USB device driver will need to service interrupts for all of
 529 the endpoints and possibly for additional USB events such as entering
 530 or leaving suspended mode. Usually these interrupts need not be
 531 serviced directly by the ISR. Instead, they can be left to a DSR. If
 532 the peripheral is not able to accept or send another packet just yet,
 533 the hardware will generate a NAK and the host will just retry a little
 534 bit later. If high throughput is required then it may be desirable to
 535 handle the bulk transfer protocol largely at ISR level, that is take
 536 care of each packet in the ISR and only activate the DSR once the
 537 whole transfer has completed.</P
 538 ><P
 539 >Control messages may involve invoking arbitrary callback functions in
 540 higher-level code. This should normally happen at DSR level. Doing it
 541 at ISR level could seriously affect the system's interrupt latency and
 542 impose unacceptable constraints on what operations can be performed by
 543 those callbacks. If the device driver requires a thread anyway then it
 544 may be appropriate to use this thread for invoking the callbacks, but
 545 usually it is not worthwhile to add a new thread to the system just
 546 for this; higher-level code is expected to write callbacks that
 547 function sensibly at DSR level. Much the same applies to the
 548 completion functions associated with data transfers. These should also
 549 be invoked at DSR or thread level.</P
 550 ></DIV
 551 ><DIV
 552 CLASS="REFSECT1"
 553 ><A
 554 NAME="AEN16785"
 555 ></A
 556 ><H2
 557 >Support for USB Testing</H2
 558 ><P
 559 >Optionally a USB device driver can provide support for the
 560 <A
 561 HREF="usbs-testing.html"
 562 >USB test software</A
 563 >. This requires
 564 defining a number of additional data structures, allowing the
 565 generic test code to work out just what the hardware is capable of and
 566 hence what testing can be performed.</P
 567 ><P
 568 >The key data structure is
 569 <SPAN
 570 CLASS="STRUCTNAME"
 571 >usbs_testing_endpoint</SPAN
 572 >, defined in <TT
 573 CLASS="FILENAME"
 574 >cyg/io/usb/usbs.h</TT
 575 >. In addition some
 576 commonly required constants are provided by the common USB package in
 577 <TT
 578 CLASS="FILENAME"
 579 >cyg/io/usb/usb.h</TT
 580 >. One
 581 <SPAN
 582 CLASS="STRUCTNAME"
 583 >usbs_testing_endpoint</SPAN
 584 > structure should be
 585 defined for each supported endpoint. The following fields need to be
 586 filled in:</P
 587 ><P
 588 ></P
 589 ><DIV
 590 CLASS="VARIABLELIST"
 591 ><DL
 592 ><DT
 593 ><TT
 594 CLASS="STRUCTFIELD"
 595 ><I
 596 >endpoint_type</I
 597 ></TT
 598 ></DT
 599 ><DD
 600 ><P
 601 >    This specifies the type of endpoint and should be one of
 602     <TT
 603 CLASS="LITERAL"
 604 >USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL</TT
 605 >,
 606     <TT
 607 CLASS="LITERAL"
 608 >BULK</TT
 609 >, <TT
 610 CLASS="LITERAL"
 611 >ISOCHRONOUS</TT
 612 > or
 613     <TT
 614 CLASS="LITERAL"
 615 >INTERRUPT</TT
 616 >.
 617   </P
 618 ></DD
 619 ><DT
 620 ><TT
 621 CLASS="STRUCTFIELD"
 622 ><I
 623 >endpoint_number</I
 624 ></TT
 625 ></DT
 626 ><DD
 627 ><P
 628 >    This identifies the number that should be used by the host
 629     to address this endpoint. For a control endpoint it should
 630     be 0. For other types of endpoints it should be between
 631     1 and 15.
 632   </P
 633 ></DD
 634 ><DT
 635 ><TT
 636 CLASS="STRUCTFIELD"
 637 ><I
 638 >endpoint_direction</I
 639 ></TT
 640 ></DT
 641 ><DD
 642 ><P
 643 >    For control endpoints this field is irrelevant. For other
 644     types of endpoint it should be either
 645     <TT
 646 CLASS="LITERAL"
 647 >USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN</TT
 648 > or
 649     <TT
 650 CLASS="LITERAL"
 651 >USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT</TT
 652 >. If a given
 653     endpoint number can be used for traffic in both directions then
 654     there should be two entries in the array, one for each direction.
 655   </P
 656 ></DD
 657 ><DT
 658 ><TT
 659 CLASS="STRUCTFIELD"
 660 ><I
 661 >endpoint</I
 662 ></TT
 663 ></DT
 664 ><DD
 665 ><P
 666 >    This should be a pointer to the appropriate
 667     <SPAN
 668 CLASS="STRUCTNAME"
 669 >usbs_control_endpoint</SPAN
 670 >,
 671     <SPAN
 672 CLASS="STRUCTNAME"
 673 >usbs_rx_endpoint</SPAN
 674 > or
 675     <SPAN
 676 CLASS="STRUCTNAME"
 677 >usbs_tx_endpoint</SPAN
 678 > structure, allowing the
 679     generic testing code to perform low-level I/O.
 680   </P
 681 ></DD
 682 ><DT
 683 ><TT
 684 CLASS="STRUCTFIELD"
 685 ><I
 686 >devtab_entry</I
 687 ></TT
 688 ></DT
 689 ><DD
 690 ><P
 691 >    If the endpoint also has an entry in the system's device table then
 692     this field should give the corresponding string, for example
 693     <TT
 694 CLASS="LITERAL"
 695 >&quot;/dev/usbs1r&quot;</TT
 696 >. This allows the
 697     generic testing code to access the device via higher-level
 698     calls like <TT
 699 CLASS="FUNCTION"
 700 >open</TT
 701 > and <TT
 702 CLASS="FUNCTION"
 703 >read</TT
 704 >.
 705   </P
 706 ></DD
 707 ><DT
 708 ><TT
 709 CLASS="STRUCTFIELD"
 710 ><I
 711 >min_size</I
 712 ></TT
 713 ></DT
 714 ><DD
 715 ><P
 716 >    This indicates the smallest transfer size that the hardware can
 717     support on this endpoint. Typically this will be one.
 718   </P
 719 ><DIV
 720 CLASS="NOTE"
 721 ><BLOCKQUOTE
 722 CLASS="NOTE"
 723 ><P
 724 ><B
 725 >Note: </B
 726 >    Strictly speaking a minimum size of one is not quite right since it
 727     is valid for a USB transfer to involve zero bytes, in other words a
 728     transfer that involves just headers and acknowledgements and an
 729     empty data phase, and that should be tested as well. However current
 730     device drivers interpret a transfer size of 0 as special, so that
 731     would have to be resolved first.
 732   </P
 733 ></BLOCKQUOTE
 734 ></DIV
 735 ></DD
 736 ><DT
 737 ><TT
 738 CLASS="STRUCTFIELD"
 739 ><I
 740 >max_size</I
 741 ></TT
 742 ></DT
 743 ><DD
 744 ><P
 745 >    Similarly, this specifies the largest transfer size. For control
 746     endpoints the USB protocol uses only two bytes to hold the transfer
 747     length, so there is an upper bound of 65535 bytes. In practice
 748     it is very unlikely that any control transfers would ever need to
 749     be this large, and in fact such transfers would take a long time
 750     and probably violate timing constraints. For other types of endpoint
 751     any of the protocol, the hardware, or the device driver may impose
 752     size limits. For example a given device driver might be unable to
 753     cope with transfers larger than 65535 bytes. If it should be
 754     possible to transfer arbitrary amounts of data then a value of
 755     <TT
 756 CLASS="LITERAL"
 757 >-1</TT
 758 > indicates no upper limit, and transfer
 759     sizes will be limited by available memory and by the capabilities
 760     of the host machine.
 761   </P
 762 ></DD
 763 ><DT
 764 ><TT
 765 CLASS="STRUCTFIELD"
 766 ><I
 767 >max_in_padding</I
 768 ></TT
 769 ></DT
 770 ><DD
 771 ><P
 772 >    This field is needed on some hardware where it is impossible to
 773     send packets of a certain size. For example the hardware may be
 774     incapable of sending an empty bulk packet to terminate a transfer
 775     that is an exact multiple of the 64-byte bulk packet size.
 776     Instead the driver has to do some padding and send an extra byte,
 777     and the host has to be prepared to receive this extra byte. Such a
 778     driver should specify a value of <TT
 779 CLASS="LITERAL"
 780 >1</TT
 781 > for the
 782     padding field. For most drivers this field should be set to
 783   <TT
 784 CLASS="LITERAL"
 785 >0</TT
 786 >.
 787   </P
 788 ><P
 789 >    A better solution would be for the device driver to supply a
 790     fragment of Tcl code that would adjust the receive buffer size
 791     only when necessary, rather than for every transfer. Forcing
 792     receive padding on all transfers when only certain transfers
 793     will actually be padded reduces the accuracy of certain tests.
 794   </P
 795 ></DD
 796 ><DT
 797 ><TT
 798 CLASS="STRUCTFIELD"
 799 ><I
 800 >alignment</I
 801 ></TT
 802 ></DT
 803 ><DD
 804 ><P
 805 >    On some hardware data transfers may need to be aligned to certain
 806     boundaries, for example a word boundary or a cacheline boundary.
 807     Although in theory device drivers could hide such alignment
 808     restrictions from higher-level code by having their own buffers and
 809     performing appropriate copying, that would be expensive in terms of
 810     both memory and cpu cycles. Instead the generic testing code will
 811     align any buffers passed to the device driver to the specified
 812     boundary. For example, if the driver requires that buffers be
 813     aligned to a word boundary then it should specify an alignment
 814     value of 4.
 815   </P
 816 ></DD
 817 ></DL
 818 ></DIV
 819 ><P
 820 >The device driver should provide an array of these structures
 821 <TT
 822 CLASS="VARNAME"
 823 >usbs_testing_endpoints[]</TT
 824 >. The USB testing code
 825 examines this array and uses the information to perform appropriate
 826 tests. Because different USB devices support different numbers of
 827 endpoints the number of entries in the array is not known in advance,
 828 so instead the testing code looks for a special terminator
 829 <TT
 830 CLASS="VARNAME"
 831 >USBS_TESTING_ENDPOINTS_TERMINATOR</TT
 832 >. An example
 833 array, showing just the control endpoint and the terminator, might
 834 look like this:</P
 835 ><TABLE
 836 BORDER="5"
 837 BGCOLOR="#E0E0F0"
 838 WIDTH="70%"
 839 ><TR
 840 ><TD
 841 ><PRE
 842 CLASS="PROGRAMLISTING"
 843 >usbs_testing_endpoint usbs_testing_endpoints[] = {
 844     {
 845         endpoint_type       : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL,
 846         endpoint_number     : 0,
 847         endpoint_direction  : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN,
 848         endpoint            : (void*) &amp;ep0.common,
 849         devtab_entry        : (const char*) 0,
 850         min_size            : 1,
 851         max_size            : 0x0FFFF,
 852         max_in_padding      : 0,
 853         alignment           : 0
 854     },
 855     &#8230;,
 856     USBS_TESTING_ENDPOINTS_TERMINATOR
 857 };</PRE
 858 ></TD
 859 ></TR
 860 ></TABLE
 861 ><DIV
 862 CLASS="NOTE"
 863 ><BLOCKQUOTE
 864 CLASS="NOTE"
 865 ><P
 866 ><B
 867 >Note: </B
 868 >The use of a single array <TT
 869 CLASS="VARNAME"
 870 >usbs_testing_endpoints</TT
 871 >
 872 limits USB testing to platforms with a single USB device: if there
 873 were multiple devices, each defining their own instance of this array,
 874 then there would a collision at link time. In practice this should not
 875 be a major problem since typical USB peripherals only interact with a
 876 single host machine via a single slave port. In addition, even if a
 877 peripheral did have multiple slave ports the current USB testing code
 878 would not support this since it would not know which port to use.</P
 879 ></BLOCKQUOTE
 880 ></DIV
 881 ></DIV
 882 ><DIV
 883 CLASS="NAVFOOTER"
 884 ><HR
 885 ALIGN="LEFT"
 886 WIDTH="100%"><TABLE
 887 SUMMARY="Footer navigation table"
 888 WIDTH="100%"
 889 BORDER="0"
 890 CELLPADDING="0"
 891 CELLSPACING="0"
 892 ><TR
 893 ><TD
 894 WIDTH="33%"
 895 ALIGN="left"
 896 VALIGN="top"
 897 ><A
 898 HREF="usbs-data.html"
 899 ACCESSKEY="P"
 900 >Prev</A
 901 ></TD
 902 ><TD
 903 WIDTH="34%"
 904 ALIGN="center"
 905 VALIGN="top"
 906 ><A
 907 HREF="ecos-ref.html"
 908 ACCESSKEY="H"
 909 >Home</A
 910 ></TD
 911 ><TD
 912 WIDTH="33%"
 913 ALIGN="right"
 914 VALIGN="top"
 915 ><A
 916 HREF="usbs-testing.html"
 917 ACCESSKEY="N"
 918 >Next</A
 919 ></TD
 920 ></TR
 921 ><TR
 922 ><TD
 923 WIDTH="33%"
 924 ALIGN="left"
 925 VALIGN="top"
 926 >Data Endpoints</TD
 927 ><TD
 928 WIDTH="34%"
 929 ALIGN="center"
 930 VALIGN="top"
 931 ><A
 932 HREF="io-usb-slave.html"
 933 ACCESSKEY="U"
 934 >Up</A
 935 ></TD
 936 ><TD
 937 WIDTH="33%"
 938 ALIGN="right"
 939 VALIGN="top"
 940 >Testing</TD
 941 ></TR
 942 ></TABLE
 943 ></DIV
 944 ></BODY
 945 ></HTML
 946 >