doc/html/ref/usbs-enum.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 >USB Enumeration Data</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="Introduction"
  26 HREF="usbs-intro.html"><LINK
  27 REL="NEXT"
  28 TITLE="Starting up a USB Device"
  29 HREF="usbs-start.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-intro.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-start.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-ENUM">USB Enumeration Data</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN16105"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Enumeration Data&nbsp;--&nbsp;The USB enumeration data structures</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN16108"><H2
  95 >Synopsis</H2
  96 ><TABLE
  97 BORDER="5"
  98 BGCOLOR="#E0E0F0"
  99 WIDTH="70%"
 100 ><TR
 101 ><TD
 102 ><PRE
 103 CLASS="SYNOPSIS"
 104 >#include &lt;cyg/io/usb/usb.h&gt;
 105 #include &lt;cyg/io/usb/usbs.h&gt;
 106
 107 typedef struct usb_device_descriptor {
 108     &#8230;
 109 } usb_device_descriptor __attribute__((packed));
 110
 111 typedef struct usb_configuration_descriptor {
 112     &#8230;
 113 } usb_configuration_descriptor __attribute__((packed));
 114
 115 typedef struct usb_interface_descriptor {
 116     &#8230;
 117 } usb_interface_descriptor __attribute__((packed));
 118
 119 typedef struct usb_endpoint_descriptor {
 120     &#8230;
 121 } usb_endpoint_descriptor;
 122
 123 typedef struct usbs_enumeration_data {
 124     usb_device_descriptor               device;
 125     int                                 total_number_interfaces;
 126     int                                 total_number_endpoints;
 127     int                                 total_number_strings;
 128     const usb_configuration_descriptor* configurations;
 129     const usb_interface_descriptor*     interfaces;
 130     const usb_endpoint_descriptor*      endpoints;
 131     const unsigned char**               strings;
 132 } usbs_enumeration_data;</PRE
 133 ></TD
 134 ></TR
 135 ></TABLE
 136 ></DIV
 137 ><DIV
 138 CLASS="REFSECT1"
 139 ><A
 140 NAME="AEN16110"
 141 ></A
 142 ><H2
 143 >USB Enumeration Data</H2
 144 ><P
 145 >When a USB host detects that a peripheral has been plugged in or
 146 powered up, one of the first steps is to ask the peripheral to
 147 describe itself by supplying enumeration data. Some of this data
 148 depends on the class of peripheral. Other fields are vendor-specific.
 149 There is also a dependency on the hardware, specifically which
 150 endpoints are available should be used. In general it is not possible
 151 for generic code to provide this information, so it is the
 152 responsibility of application code to provide a suitable
 153 <SPAN
 154 CLASS="STRUCTNAME"
 155 >usbs_enumeration_data</SPAN
 156 > data structure and
 157 install it in the endpoint 0 data structure during initialization.
 158 This must happen before the USB device is enabled by a call to
 159 <TT
 160 CLASS="FUNCTION"
 161 >usbs_start</TT
 162 >, for example:</P
 163 ><TABLE
 164 BORDER="5"
 165 BGCOLOR="#E0E0F0"
 166 WIDTH="70%"
 167 ><TR
 168 ><TD
 169 ><PRE
 170 CLASS="PROGRAMLISTING"
 171 >const usbs_enumeration_data usb_enum_data = {
 172     &#8230;
 173 };
 174
 175 int
 176 main(int argc, char** argv)
 177 {
 178     usbs_sa11x0_ep0.enumeration_data = &amp;usb_enum_data;
 179     &#8230;
 180     usbs_start(&amp;usbs_sa11x0_ep0);
 181     &#8230;
 182 }</PRE
 183 ></TD
 184 ></TR
 185 ></TABLE
 186 ><P
 187 >For most applications the enumeration data will be static, although
 188 the <SPAN
 189 CLASS="STRUCTNAME"
 190 >usbs_enumeration_data</SPAN
 191 > structure can be
 192 filled in at run-time if necessary. Full details of the enumeration
 193 data can be found in the Universal Serial Bus specification obtainable
 194 from the <A
 195 HREF="http://www.usb.org/"
 196 TARGET="_top"
 197 >USB Implementers Forum web
 198 site</A
 199 >, although the meaning of most fields is fairly obvious.
 200 The various data structures and utility macros are defined in the
 201 header files <TT
 202 CLASS="FILENAME"
 203 >cyg/io/usb/usb.h</TT
 204 >
 205 and <TT
 206 CLASS="FILENAME"
 207 >cyg/io/usb/usbs.h</TT
 208 >. Note
 209 that the example code below makes use of the gcc labelled element
 210 extension.</P
 211 ><DIV
 212 CLASS="REFSECT2"
 213 ><A
 214 NAME="AEN16121"
 215 ></A
 216 ><H3
 217 ><SPAN
 218 CLASS="STRUCTNAME"
 219 >usb_device_descriptor</SPAN
 220 ></H3
 221 ><P
 222 >The main information about a USB peripheral comes from a single
 223 <SPAN
 224 CLASS="STRUCTNAME"
 225 >usb_device_descriptor</SPAN
 226 > structure, which is
 227 embedded in the <SPAN
 228 CLASS="STRUCTNAME"
 229 >usbs_enumeration_data</SPAN
 230 >
 231 structure. A typical example might look like this:</P
 232 ><TABLE
 233 BORDER="5"
 234 BGCOLOR="#E0E0F0"
 235 WIDTH="70%"
 236 ><TR
 237 ><TD
 238 ><PRE
 239 CLASS="PROGRAMLISTING"
 240 >const usbs_enumeration_data usb_enum_data = {
 241     {
 242         length:                 USB_DEVICE_DESCRIPTOR_LENGTH,
 243         type:                   USB_DEVICE_DESCRIPTOR_TYPE,
 244         usb_spec_lo:            USB_DEVICE_DESCRIPTOR_USB11_LO,
 245         usb_spec_hi:            USB_DEVICE_DESCRIPTOR_USB11_HI,
 246         device_class:           USB_DEVICE_DESCRIPTOR_CLASS_VENDOR,
 247         device_subclass:        USB_DEVICE_DESCRIPTOR_SUBCLASS_VENDOR,
 248         device_protocol:        USB_DEVICE_DESCRIPTOR_PROTOCOL_VENDOR,
 249         max_packet_size:        8,
 250         vendor_lo:              0x42,
 251         vendor_hi:              0x42,
 252         product_lo:             0x42,
 253         product_hi:             0x42,
 254         device_lo:              0x00,
 255         device_hi:              0x01,
 256         manufacturer_str:       1,
 257         product_str:            2,
 258         serial_number_str:      0,
 259         number_configurations:  1
 260     },
 261     &#8230;
 262 };</PRE
 263 ></TD
 264 ></TR
 265 ></TABLE
 266 ><P
 267 >The length and type fields are specified by the USB standard. The
 268 <TT
 269 CLASS="STRUCTFIELD"
 270 ><I
 271 >usb_spec_lo</I
 272 ></TT
 273 > and
 274 <TT
 275 CLASS="STRUCTFIELD"
 276 ><I
 277 >usb_spec_hi</I
 278 ></TT
 279 > fields identify the particular
 280 revision of the standard that the peripheral implements, for example
 281 revision 1.1.</P
 282 ><P
 283 >The device class, subclass, and protocol fields are used by generic
 284 host-side USB software to determine which host-side device driver
 285 should be loaded to interact with the peripheral. A number of standard
 286 classes are defined, for example mass-storage devices and
 287 human-interface devices. If a peripheral implements one of the
 288 standard classes then a standard existing host-side device driver may
 289 exist, eliminating the need to write a custom driver. The value
 290 <TT
 291 CLASS="LITERAL"
 292 >0xFF</TT
 293 > (<TT
 294 CLASS="LITERAL"
 295 >VENDOR</TT
 296 >) is reserved for
 297 peripherals that implement a vendor-specific protocol rather than a
 298 standard one. Such peripherals will require a custom host-side device
 299 driver. The value <TT
 300 CLASS="LITERAL"
 301 >0x00</TT
 302 >
 303 (<TT
 304 CLASS="LITERAL"
 305 >INTERFACE</TT
 306 >) is reserved and indicates that the
 307 protocol used by the peripheral is defined at the interface level
 308 rather than for the peripheral as a whole.</P
 309 ><P
 310 >The <TT
 311 CLASS="STRUCTFIELD"
 312 ><I
 313 >max_package_size</I
 314 ></TT
 315 > field specifies the
 316 maximum length of a control message. There is a lower bound of eight
 317 bytes, and typical hardware will not support anything larger because
 318 control messages are usually small and not performance-critical.</P
 319 ><P
 320 >The <TT
 321 CLASS="STRUCTFIELD"
 322 ><I
 323 >vendor_lo</I
 324 ></TT
 325 > and
 326 <TT
 327 CLASS="STRUCTFIELD"
 328 ><I
 329 >vendor_hi</I
 330 ></TT
 331 > fields specify a vendor id, which
 332 must be obtained from the USB Implementor's Forum. The numbers used in
 333 the code fragment above are examples only and must not be used in real
 334 USB peripherals. The product identifier is determined by the vendor,
 335 and different USB peripherals should use different identifiers. The
 336 device identifier field should indicate a release number in
 337 binary-coded decimal.</P
 338 ><P
 339 >The above fields are all numerical in nature. A USB peripheral can
 340 also provide a number of strings as described <A
 341 HREF="usbs-enum.html#AEN16196"
 342 >below</A
 343 >, for example the name of the
 344 vendor can be provided. The various <TT
 345 CLASS="STRUCTFIELD"
 346 ><I
 347 >_str</I
 348 ></TT
 349 >
 350 fields act as indices into an array of strings, with index 0
 351 indicating that no string is available. </P
 352 ><P
 353 >A typical USB peripheral involves just a single configuration. However
 354 more complicated peripherals can support multiple configurations. Only
 355 one configuration will be active at any one time, and the host will
 356 switch between them as appropriate. If a peripheral does involve
 357 multiple configurations then typically it will be the responsibility
 358 of application code to <A
 359 HREF="usbs-control.html#AEN16582"
 360 >handle</A
 361 > the standard
 362 set-configuration control message.</P
 363 ></DIV
 364 ><DIV
 365 CLASS="REFSECT2"
 366 ><A
 367 NAME="AEN16146"
 368 ></A
 369 ><H3
 370 ><SPAN
 371 CLASS="STRUCTNAME"
 372 >usb_configuration_descriptor</SPAN
 373 ></H3
 374 ><P
 375 >A USB peripheral involves at least one and possible several different
 376 configurations. The <SPAN
 377 CLASS="STRUCTNAME"
 378 >usbs_enumeration_data</SPAN
 379 >
 380 structure requires a pointer to an array, possibly of length 1, of
 381 <SPAN
 382 CLASS="STRUCTNAME"
 383 >usb_configuration_descriptor</SPAN
 384 > structures.
 385 Usually a single structure suffices:</P
 386 ><TABLE
 387 BORDER="5"
 388 BGCOLOR="#E0E0F0"
 389 WIDTH="70%"
 390 ><TR
 391 ><TD
 392 ><PRE
 393 CLASS="PROGRAMLISTING"
 394 >const usb_configuration_descriptor usb_configuration = {
 395     length:             USB_CONFIGURATION_DESCRIPTOR_LENGTH,
 396     type:               USB_CONFIGURATION_DESCRIPTOR_TYPE,
 397     total_length_lo:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_LO(1, 2),
 398     total_length_hi:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_HI(1, 2),
 399     number_interfaces:  1,
 400     configuration_id:   1,
 401     configuration_str:  0,
 402     attributes:         USB_CONFIGURATION_DESCRIPTOR_ATTR_REQUIRED |
 403                         USB_CONFIGURATION_DESCRIPTOR_ATTR_SELF_POWERED,
 404     max_power:          50
 405 };
 406
 407 const usbs_enumeration_data usb_enum_data = {
 408     &#8230;
 409     configurations:             &amp;usb_configuration,
 410     &#8230;
 411 };</PRE
 412 ></TD
 413 ></TR
 414 ></TABLE
 415 ><P
 416 >The values for the <TT
 417 CLASS="STRUCTFIELD"
 418 ><I
 419 >length</I
 420 ></TT
 421 > and
 422 <TT
 423 CLASS="STRUCTFIELD"
 424 ><I
 425 >type</I
 426 ></TT
 427 > fields are determined by the standard.
 428 The <TT
 429 CLASS="STRUCTFIELD"
 430 ><I
 431 >total_length</I
 432 ></TT
 433 > field depends on the
 434 number of interfaces and endpoints used by this configuration, and
 435 convenience macros are provided to calculate this: the first argument
 436 to the macros specify the number of interfaces, the second the number
 437 of endpoints. The <TT
 438 CLASS="STRUCTFIELD"
 439 ><I
 440 >number_interfaces</I
 441 ></TT
 442 > field
 443 is self-explanatory. If the peripheral involves multiple
 444 configurations then each one must have a unique id, and this will be
 445 used in the set-configuration control message. The id
 446 <TT
 447 CLASS="LITERAL"
 448 >0</TT
 449 > is reserved, and a set-configuration control
 450 message that uses this id indicates that the peripheral should be
 451 inactive. Configurations can have a string description if required.
 452 The <TT
 453 CLASS="STRUCTFIELD"
 454 ><I
 455 >attributes</I
 456 ></TT
 457 > field must have the
 458 <TT
 459 CLASS="LITERAL"
 460 >REQUIRED</TT
 461 > bit set; the
 462 <TT
 463 CLASS="LITERAL"
 464 >SELF_POWERED</TT
 465 > bit informs the host that the
 466 peripheral has its own power supply and will not draw any power over
 467 the bus, leaving more bus power available to other peripherals; the
 468 <TT
 469 CLASS="LITERAL"
 470 >REMOTE_WAKEUP</TT
 471 > bit is used if the peripheral can
 472 interrupt the host when the latter is in power-saving mode. For
 473 peripherals that are not self-powered, the
 474 <TT
 475 CLASS="STRUCTFIELD"
 476 ><I
 477 >max_power</I
 478 ></TT
 479 > field specifies the power
 480 requirements in units of 2mA.</P
 481 ></DIV
 482 ><DIV
 483 CLASS="REFSECT2"
 484 ><A
 485 NAME="AEN16164"
 486 ></A
 487 ><H3
 488 ><SPAN
 489 CLASS="STRUCTNAME"
 490 >usb_interface_descriptor</SPAN
 491 ></H3
 492 ><P
 493 >A USB configuration involves one or more interfaces, typically
 494 corresponding to different streams of data. For example, one interface
 495 might involve video data while another interface is for audio.
 496 Multiple interfaces in a single configuration will be active at the
 497 same time.</P
 498 ><TABLE
 499 BORDER="5"
 500 BGCOLOR="#E0E0F0"
 501 WIDTH="70%"
 502 ><TR
 503 ><TD
 504 ><PRE
 505 CLASS="PROGRAMLISTING"
 506 >const usb_interface_descriptor usb_interface = {
 507     length:             USB_INTERFACE_DESCRIPTOR_LENGTH,
 508     type:               USB_INTERFACE_DESCRIPTOR_TYPE,
 509     interface_id:       0,
 510     alternate_setting:  0,
 511     number_endpoints:   2,
 512     interface_class:    USB_INTERFACE_DESCRIPTOR_CLASS_VENDOR,
 513     interface_subclass: USB_INTERFACE_DESCRIPTOR_SUBCLASS_VENDOR,
 514     interface_protocol: USB_INTERFACE_DESCRIPTOR_PROTOCOL_VENDOR,
 515     interface_str:      0
 516 };
 517
 518 const usbs_enumeration_data usb_enum_data = {
 519     &#8230;
 520     total_number_interfaces:    1,
 521     interfaces:                 &amp;usb_interface,
 522     &#8230;
 523 };</PRE
 524 ></TD
 525 ></TR
 526 ></TABLE
 527 ><P
 528 >Again, the <TT
 529 CLASS="STRUCTFIELD"
 530 ><I
 531 >length</I
 532 ></TT
 533 > and
 534 <TT
 535 CLASS="STRUCTFIELD"
 536 ><I
 537 >type</I
 538 ></TT
 539 > fields are specified by the standard.
 540 Each interface within a configuration requires its own id. However, a
 541 given interface may have several alternate settings, in other words
 542 entries in the interfaces array with the same id but different
 543 <TT
 544 CLASS="STRUCTFIELD"
 545 ><I
 546 >alternate_setting</I
 547 ></TT
 548 > fields. For example,
 549 there might be one setting which requires a bandwidth of 100K/s and
 550 another setting that only needs 50K/s. The host can use the standard
 551 set-interface control message to choose the most appropriate setting.
 552 The handling of this request is the responsibility of higher-level
 553 code, so the application may have to <A
 554 HREF="usbs-control.html#AEN16582"
 555 >install</A
 556 > its own handler.</P
 557 ><P
 558 >The number of endpoints used by an interface is specified in the
 559 <TT
 560 CLASS="STRUCTFIELD"
 561 ><I
 562 >number_endpoints</I
 563 ></TT
 564 > field. Exact details of
 565 which endpoints are used is held in a separate array of endpoint
 566 descriptors. The class, subclass and protocol fields are used by
 567 host-side code to determine which host-side device driver should
 568 handle this specific interface. Usually this is determined on a
 569 per-peripheral basis in the
 570 <SPAN
 571 CLASS="STRUCTNAME"
 572 >usb_device_descriptor</SPAN
 573 > structure, but that can
 574 defer the details to individual interfaces. A per-interface string
 575 is allowed as well.</P
 576 ><P
 577 >For USB peripherals involving multiple configurations, the array of
 578 <SPAN
 579 CLASS="STRUCTNAME"
 580 >usb_interface_descriptor</SPAN
 581 > structures should
 582 first contain all the interfaces for the first configuration, then all
 583 the interfaces for the second configuration, and so on.</P
 584 ></DIV
 585 ><DIV
 586 CLASS="REFSECT2"
 587 ><A
 588 NAME="AEN16179"
 589 ></A
 590 ><H3
 591 ><SPAN
 592 CLASS="STRUCTNAME"
 593 >usb_endpoint_descriptor</SPAN
 594 ></H3
 595 ><P
 596 >The host also needs information about which endpoint should be used
 597 for what. This involves an array of endpoint descriptors:</P
 598 ><TABLE
 599 BORDER="5"
 600 BGCOLOR="#E0E0F0"
 601 WIDTH="70%"
 602 ><TR
 603 ><TD
 604 ><PRE
 605 CLASS="PROGRAMLISTING"
 606 >const usb_endpoint_descriptor usb_endpoints[] = {
 607     {
 608         length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,
 609         type:           USB_ENDPOINT_DESCRIPTOR_TYPE,
 610         endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT | 1,
 611         attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,
 612         max_packet_lo:  64,
 613         max_packet_hi:  0,
 614         interval:       0
 615     },
 616     {
 617         length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,
 618         type:           USB_ENDPOINT_DESCRIPTOR_TYPE,
 619         endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN | 2,
 620         attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,
 621         max_packet_lo:  64,
 622         max_packet_hi:  0,
 623         interval:       0
 624     }
 625 };
 626
 627 const usbs_enumeration_data usb_enum_data = {
 628     &#8230;
 629     total_number_endpoints:     2,
 630     endpoints:                  usb_endpoints,
 631     &#8230;
 632 };</PRE
 633 ></TD
 634 ></TR
 635 ></TABLE
 636 ><P
 637 >As usual the values for the <TT
 638 CLASS="STRUCTFIELD"
 639 ><I
 640 >length</I
 641 ></TT
 642 > and
 643 <TT
 644 CLASS="STRUCTFIELD"
 645 ><I
 646 >type</I
 647 ></TT
 648 > fields are specified by the standard.
 649 The <TT
 650 CLASS="STRUCTFIELD"
 651 ><I
 652 >endpoint</I
 653 ></TT
 654 > field gives both the endpoint
 655 number and the direction, so in the above example endpoint 1 is used
 656 for OUT (host to peripheral) transfers and endpoint 2 is used for IN
 657 (peripheral to host) transfers. The
 658 <TT
 659 CLASS="STRUCTFIELD"
 660 ><I
 661 >attributes</I
 662 ></TT
 663 > field indicates the USB protocol
 664 that should be used on this endpoint: <TT
 665 CLASS="LITERAL"
 666 >CONTROL</TT
 667 >,
 668 <TT
 669 CLASS="LITERAL"
 670 >ISOCHRONOUS</TT
 671 >, <TT
 672 CLASS="LITERAL"
 673 >BULK</TT
 674 > or
 675 <TT
 676 CLASS="LITERAL"
 677 >INTERRUPT</TT
 678 >. The
 679 <TT
 680 CLASS="STRUCTFIELD"
 681 ><I
 682 >max_packet</I
 683 ></TT
 684 > field specifies the maximum size
 685 of a single USB packet. For bulk transfers this will typically be 64
 686 bytes. For isochronous transfers this can be up to 1023 bytes. For
 687 interrupt transfers it can be up to 64 bytes, although usually a
 688 smaller value will be used. The <TT
 689 CLASS="STRUCTFIELD"
 690 ><I
 691 >interval</I
 692 ></TT
 693 >
 694 field is ignored for control and bulk transfers. For isochronous
 695 transfers it should be set to 1. For interrupt transfers it can be a
 696 value between 1 and 255, and indicates the number of milliseconds
 697 between successive polling operations.</P
 698 ><P
 699 >For USB peripherals involving multiple configurations or interfaces
 700 the array of endpoint descriptors should be organized sequentially:
 701 first the endpoints corresponding to the first interface of the first
 702 configuration, then the second interface in that configuration, and so
 703 on; then all the endpoints for all the interfaces in the second
 704 configuration; etc.</P
 705 ></DIV
 706 ><DIV
 707 CLASS="REFSECT2"
 708 ><A
 709 NAME="AEN16196"
 710 ></A
 711 ><H3
 712 >Strings</H3
 713 ><P
 714 >The enumeration data can contain a number of strings with additional
 715 information. Unicode encoding is used for the strings, and it is
 716 possible for a peripheral to supply a given string in multiple
 717 languages using the appropriate characters. The first two bytes of
 718 each string give a length and type field. The first string is special;
 719 after the two bytes header it consists of an array of 2-byte language
 720 id codes, indicating the supported languages. The language code
 721 0x0409 corresponds to English (United States). </P
 722 ><TABLE
 723 BORDER="5"
 724 BGCOLOR="#E0E0F0"
 725 WIDTH="70%"
 726 ><TR
 727 ><TD
 728 ><PRE
 729 CLASS="PROGRAMLISTING"
 730 >const unsigned char* usb_strings[] = {
 731     "\004\003\011\004",
 732     "\020\003R\000e\000d\000 \000H\000a\000t\000"
 733 };
 734
 735 const usbs_enumeration_data usb_enum_data = {
 736     &#8230;
 737     total_number_strings:       2,
 738     strings:                    usb_strings,
 739     &#8230;
 740 };</PRE
 741 ></TD
 742 ></TR
 743 ></TABLE
 744 ><P
 745 >The default handler for standard control messages assumes that the
 746 peripheral only uses a single language. If this is not the case then
 747 higher-level code will have to handle the standard get-descriptor
 748 control messages when a string descriptor is requested.</P
 749 ></DIV
 750 ><DIV
 751 CLASS="REFSECT2"
 752 ><A
 753 NAME="AEN16201"
 754 ></A
 755 ><H3
 756 ><SPAN
 757 CLASS="STRUCTNAME"
 758 >usbs_enumeration_data</SPAN
 759 ></H3
 760 ><P
 761 >The <SPAN
 762 CLASS="STRUCTNAME"
 763 >usbs_enumeration_data</SPAN
 764 > data structure
 765 collects together all the various descriptors that make up the
 766 enumeration data. It is the responsibility of application code to
 767 supply a suitable data structure and install it in the control
 768 endpoints's <TT
 769 CLASS="STRUCTFIELD"
 770 ><I
 771 >enumeration_data</I
 772 ></TT
 773 > field before
 774 the USB device is started.</P
 775 ></DIV
 776 ></DIV
 777 ><DIV
 778 CLASS="NAVFOOTER"
 779 ><HR
 780 ALIGN="LEFT"
 781 WIDTH="100%"><TABLE
 782 SUMMARY="Footer navigation table"
 783 WIDTH="100%"
 784 BORDER="0"
 785 CELLPADDING="0"
 786 CELLSPACING="0"
 787 ><TR
 788 ><TD
 789 WIDTH="33%"
 790 ALIGN="left"
 791 VALIGN="top"
 792 ><A
 793 HREF="usbs-intro.html"
 794 ACCESSKEY="P"
 795 >Prev</A
 796 ></TD
 797 ><TD
 798 WIDTH="34%"
 799 ALIGN="center"
 800 VALIGN="top"
 801 ><A
 802 HREF="ecos-ref.html"
 803 ACCESSKEY="H"
 804 >Home</A
 805 ></TD
 806 ><TD
 807 WIDTH="33%"
 808 ALIGN="right"
 809 VALIGN="top"
 810 ><A
 811 HREF="usbs-start.html"
 812 ACCESSKEY="N"
 813 >Next</A
 814 ></TD
 815 ></TR
 816 ><TR
 817 ><TD
 818 WIDTH="33%"
 819 ALIGN="left"
 820 VALIGN="top"
 821 >Introduction</TD
 822 ><TD
 823 WIDTH="34%"
 824 ALIGN="center"
 825 VALIGN="top"
 826 ><A
 827 HREF="io-usb-slave.html"
 828 ACCESSKEY="U"
 829 >Up</A
 830 ></TD
 831 ><TD
 832 WIDTH="33%"
 833 ALIGN="right"
 834 VALIGN="top"
 835 >Starting up a USB Device</TD
 836 ></TR
 837 ></TABLE
 838 ></DIV
 839 ></BODY
 840 ></HTML
 841 >