packages/io/usb/slave/v2_0/doc/usbs-writing.html

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