1 // 2 // usblib.h - Main header file for the USB Library. 3 // 4 // Copyright (c) 2008-2010 Texas Instruments Incorporated. All rights reserved. 5 // Software License Agreement 6 // 7 // Texas Instruments (TI) is supplying this software for use solely and 8 // exclusively on TI's microcontroller products. The software is owned by 9 // TI and/or its suppliers, and is protected under applicable copyright 10 // laws. You may not combine this software with "viral" open-source 11 // software in order to form a larger program. 12 // 13 // THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS. 14 // NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT 15 // NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 16 // A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY 17 // CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL 18 // DAMAGES, FOR ANY REASON WHATSOEVER. 19 // 20 // 21 //***************************************************************************** 22 23 #ifndef __USBLIB_H__ 24 #define __USBLIB_H__ 25 26 //***************************************************************************** 27 // 28 // If building with a C++ compiler, make all of the definitions in this header 29 // have a C binding. 30 // 31 //***************************************************************************** 32 #ifdef __cplusplus 33 extern "C" 34 { 35 #endif 36 37 38 39 /* standard device requests -- USB_SetupDataPacket::bRequest */ 40 #define USB_REQUEST_GETSTATUS (0u) 41 #define USB_REQUEST_CLEARFEATURE (1u) 42 #define USB_REQUEST_SETFEATURE (3u) 43 #define USB_REQUEST_SETADDRESS (5u) 44 #define USB_REQUEST_GETDESCRIPTOR (6u) 45 #define USB_REQUEST_SETDESCRIPTOR (7u) 46 #define USB_REQUEST_GETCONFIGURATION (8u) 47 #define USB_REQUEST_SETCONFIGURATION (9u) 48 #define USB_REQUEST_GETINTERFACE (10u) 49 #define USB_REQUEST_SETINTERFACE (11u) 50 #define USB_REQUEST_SYNCHFRAME (12u) 51 52 53 //***************************************************************************** 54 // 55 // This is the maximum number of endpoints supported by the usblib. 56 // 57 //***************************************************************************** 58 #define USBLIB_NUM_EP 16 // Number of supported endpoints. 59 60 //***************************************************************************** 61 // 62 // The following macro allows compiler-independent syntax to be used to 63 // define packed structures. A typical structure definition using these 64 // macros will look similar to the following example: 65 // 66 // #ifdef ewarm 67 // #pragma pack(1) 68 // #endif 69 // 70 // typedef struct _PackedStructName 71 // { 72 // uint32 ulFirstField; 73 // char cCharMember; 74 // uint16 usShort; 75 // } 76 // PACKED tPackedStructName; 77 // 78 // #ifdef ewarm 79 // #pragma pack() 80 // #endif 81 // 82 // The conditional blocks related to ewarm include the #pragma pack() lines 83 // only if the IAR Embedded Workbench compiler is being used. Unfortunately, 84 // it is not possible to emit a #pragma from within a macro definition so this 85 // must be done explicitly. 86 // 87 //***************************************************************************** 88 #if defined(ccs) || \ 89 defined(codered) || \ 90 defined(gcc) || \ 91 defined(rvmdk) || \ 92 defined(__ARMCC_VERSION) || \ 93 defined(sourcerygxx) 94 #define PACKED __attribute__ ((packed)) 95 #elif defined(ewarm) || defined(__IAR_SYSTEMS_ICC__) 96 #define PACKED 97 #elif (__TMS470__) 98 #define PACKED __attribute__ ((packed)) 99 #else 100 #error Unrecognized COMPILER! 101 #endif 102 103 //***************************************************************************** 104 // 105 // Assorted language IDs from the document "USB_LANGIDs.pdf" provided by the 106 // USB Implementers' Forum (Version 1.0). 107 // 108 //***************************************************************************** 109 #define USB_LANG_CHINESE_PRC 0x0804 // Chinese (PRC) 110 #define USB_LANG_CHINESE_TAIWAN 0x0404 // Chinese (Taiwan) 111 #define USB_LANG_EN_US 0x0409 // English (United States) 112 #define USB_LANG_EN_UK 0x0809 // English (United Kingdom) 113 #define USB_LANG_EN_AUS 0x0C09 // English (Australia) 114 #define USB_LANG_EN_CA 0x1009 // English (Canada) 115 #define USB_LANG_EN_NZ 0x1409 // English (New Zealand) 116 #define USB_LANG_FRENCH 0x040C // French (Standard) 117 #define USB_LANG_GERMAN 0x0407 // German (Standard) 118 #define USB_LANG_HINDI 0x0439 // Hindi 119 #define USB_LANG_ITALIAN 0x0410 // Italian (Standard) 120 #define USB_LANG_JAPANESE 0x0411 // Japanese 121 #define USB_LANG_KOREAN 0x0412 // Korean 122 #define USB_LANG_ES_TRAD 0x040A // Spanish (Traditional) 123 #define USB_LANG_ES_MODERN 0x0C0A // Spanish (Modern) 124 #define USB_LANG_SWAHILI 0x0441 // Swahili (Kenya) 125 #define USB_LANG_URDU_IN 0x0820 // Urdu (India) 126 #define USB_LANG_URDU_PK 0x0420 // Urdu (Pakistan) 127 //***************************************************************************** 128 // 129 //! \addtogroup usbchap9_src 130 //! @{ 131 // 132 //***************************************************************************** 133 134 //***************************************************************************** 135 // 136 // Note: 137 // 138 // Structure definitions which are derived directly from the USB specification 139 // use field names from the specification. Since a somewhat different version 140 // of Hungarian prefix notation is used from the Stellaris standard, beware of 141 // making assumptions about field sizes based on the field prefix when using 142 // these structures. Of particular note is the difference in the meaning of 143 // the 'i' prefix. In USB structures, this indicates a single byte index 144 // whereas in Stellaris code, this is a 32 bit integer. 145 // 146 //***************************************************************************** 147 148 //***************************************************************************** 149 // 150 // All structures defined in this section of the header require byte packing of 151 // fields. This is usually accomplished using the PACKED macro but, for IAR 152 // Embedded Workbench, this requires a pragma. 153 // 154 //***************************************************************************** 155 #if defined(ewarm) || defined(__IAR_SYSTEMS_ICC__) 156 #pragma pack(1) 157 #endif 158 159 //***************************************************************************** 160 // 161 // Definitions related to standard USB device requests (sections 9.3 & 9.4) 162 // 163 //***************************************************************************** 164 165 //***************************************************************************** 166 // 167 //! The standard USB request header as defined in section 9.3 of the USB 2.0 168 //! specification. 169 // 170 //***************************************************************************** 171 typedef struct 172 { 173 // 174 //! Determines the type and direction of the request. 175 // 176 uint8 bmRequestType; 177 178 // 179 //! Identifies the specific request being made. 180 // 181 uint8 bRequest; 182 183 // 184 //! Word-sized field that varies according to the request. 185 // 186 uint16 wValue; 187 188 // 189 //! Word-sized field that varies according to the request; typically used 190 //! to pass an index or offset. 191 // 192 uint16 wIndex; 193 194 // 195 //! The number of bytes to transfer if there is a data stage to the 196 //! request. 197 // 198 uint16 wLength; 199 200 } 201 PACKED tUSBRequest; 202 203 //***************************************************************************** 204 // 205 // The following defines are used with the bmRequestType member of tUSBRequest. 206 // 207 // Request types have 3 bit fields: 208 // 4:0 - Is the recipient type. 209 // 6:5 - Is the request type. 210 // 7 - Is the direction of the request. 211 // 212 //***************************************************************************** 213 #define USB_RTYPE_DIR_IN 0x80 214 #define USB_RTYPE_DIR_OUT 0x00 215 216 #define USB_RTYPE_TYPE_M 0x60 217 #define USB_RTYPE_VENDOR 0x40 218 #define USB_RTYPE_CLASS 0x20 219 #define USB_RTYPE_STANDARD 0x00 220 221 #define USB_RTYPE_RECIPIENT_M 0x1f 222 #define USB_RTYPE_OTHER 0x03 223 #define USB_RTYPE_ENDPOINT 0x02 224 #define USB_RTYPE_INTERFACE 0x01 225 #define USB_RTYPE_DEVICE 0x00 226 227 //***************************************************************************** 228 // 229 // Standard USB requests IDs used in the bRequest field of tUSBRequest. 230 // 231 //***************************************************************************** 232 #define USBREQ_GET_STATUS 0x00 233 #define USBREQ_CLEAR_FEATURE 0x01 234 #define USBREQ_SET_FEATURE 0x03 235 #define USBREQ_SET_ADDRESS 0x05 236 #define USBREQ_GET_DESCRIPTOR 0x06 237 #define USBREQ_SET_DESCRIPTOR 0x07 238 #define USBREQ_GET_CONFIG 0x08 239 #define USBREQ_SET_CONFIG 0x09 240 #define USBREQ_GET_INTERFACE 0x0a 241 #define USBREQ_SET_INTERFACE 0x0b 242 #define USBREQ_SYNC_FRAME 0x0c 243 244 //***************************************************************************** 245 // 246 // Data returned from a USBREQ_GET_STATUS request to a device. 247 // 248 //***************************************************************************** 249 #define USB_STATUS_SELF_PWR 0x0001 // Currently self powered. 250 #define USB_STATUS_BUS_PWR 0x0000 // Currently bus-powered. 251 #define USB_STATUS_PWR_M 0x0001 // Mask for power mode. 252 #define USB_STATUS_REMOTE_WAKE 0x0002 // Remote wake-up is currently enabled. 253 254 //***************************************************************************** 255 // 256 // Feature Selectors (tUSBRequest.wValue) passed on USBREQ_CLEAR_FEATURE and 257 // USBREQ_SET_FEATURE. 258 // 259 //***************************************************************************** 260 #define USB_FEATURE_EP_HALT 0x0000 // Endpoint halt feature. 261 #define USB_FEATURE_REMOTE_WAKE 0x0001 // Remote wake feature, device only. 262 #define USB_FEATURE_TEST_MODE 0x0002 // Test mode 263 264 //***************************************************************************** 265 // 266 // Endpoint Selectors (tUSBRequest.wIndex) passed on USBREQ_CLEAR_FEATURE, 267 // USBREQ_SET_FEATURE and USBREQ_GET_STATUS. 268 // 269 //***************************************************************************** 270 #define USB_REQ_EP_NUM_M 0x007F 271 #define USB_REQ_EP_DIR_M 0x0080 272 #define USB_REQ_EP_DIR_IN 0x0080 273 #define USB_REQ_EP_DIR_OUT 0x0000 274 275 //***************************************************************************** 276 // 277 // Standard USB descriptor types. These values are passed in the upper bytes 278 // of tUSBRequest.wValue on USBREQ_GET_DESCRIPTOR and also appear in the 279 // bDescriptorType field of standard USB descriptors. 280 // 281 //***************************************************************************** 282 #define USB_DTYPE_DEVICE 1 283 #define USB_DTYPE_CONFIGURATION 2 284 #define USB_DTYPE_STRING 3 285 #define USB_DTYPE_INTERFACE 4 286 #define USB_DTYPE_ENDPOINT 5 287 #define USB_DTYPE_DEVICE_QUAL 6 288 #define USB_DTYPE_OSPEED_CONF 7 289 #define USB_DTYPE_INTERFACE_PWR 8 290 #define USB_DTYPE_OTG 9 291 #define USB_DTYPE_INTERFACE_ASC 11 292 #define USB_DTYPE_CS_INTERFACE 36 293 294 //***************************************************************************** 295 // 296 // Definitions related to USB descriptors (sections 9.5 & 9.6) 297 // 298 //***************************************************************************** 299 300 //***************************************************************************** 301 // 302 //! This structure describes a generic descriptor header. These fields are to 303 //! be found at the beginning of all valid USB descriptors. 304 // 305 //***************************************************************************** 306 typedef struct 307 { 308 // 309 //! The length of this descriptor (including this length byte) expressed 310 //! in bytes. 311 // 312 uint8 bLength; 313 314 // 315 //! The type identifier of the descriptor whose information follows. For 316 //! standard descriptors, this field could contain, for example, 317 //! USB_DTYPE_DEVICE to identify a device descriptor or USB_DTYPE_ENDPOINT 318 //! to identify an endpoint descriptor. 319 // 320 uint8 bDescriptorType; 321 } 322 PACKED tDescriptorHeader; 323 324 //***************************************************************************** 325 // 326 //! This structure describes the USB device descriptor as defined in USB 327 //! 2.0 specification section 9.6.1. 328 // 329 //***************************************************************************** 330 typedef struct 331 { 332 // 333 //! The length of this descriptor in bytes. All device descriptors are 334 //! 18 bytes long. 335 // 336 uint8 bLength; 337 338 // 339 //! The type of the descriptor. For a device descriptor, this will be 340 //! USB_DTYPE_DEVICE (1). 341 // 342 uint8 bDescriptorType; 343 344 // 345 //! The USB Specification Release Number in BCD format. For USB 2.0, this 346 //! will be 0x0200. 347 // 348 uint16 bcdUSB; 349 350 // 351 //! The device class code. 352 // 353 uint8 bDeviceClass; 354 355 // 356 //! The device subclass code. This value qualifies the value found in the 357 //! bDeviceClass field. 358 // 359 uint8 bDeviceSubClass; 360 361 // 362 //! The device protocol code. This value is qualified by the values of 363 //! bDeviceClass and bDeviceSubClass. 364 // 365 uint8 bDeviceProtocol; 366 367 // 368 //! The maximum packet size for endpoint zero. Valid values are 8, 16, 32 369 //! and 64. 370 // 371 uint8 bMaxPacketSize0; 372 373 // 374 //! The device Vendor ID (VID) as assigned by the USB-IF. 375 // 376 uint16 idVendor; 377 378 // 379 //! The device Product ID (PID) as assigned by the manufacturer. 380 // 381 uint16 idProduct; 382 383 // 384 //! The device release number in BCD format. 385 // 386 uint16 bcdDevice; 387 388 // 389 //! The index of a string descriptor describing the manufacturer. 390 // 391 uint8 iManufacturer; 392 393 // 394 //! The index of a string descriptor describing the product. 395 // 396 uint8 iProduct; 397 398 // 399 //! The index of a string descriptor describing the device's serial 400 //! number. 401 // 402 uint8 iSerialNumber; 403 404 // 405 //! The number of possible configurations offered by the device. This 406 //! field indicates the number of distinct configuration descriptors that 407 //! the device offers. 408 // 409 uint8 bNumConfigurations; 410 } 411 PACKED tDeviceDescriptor; 412 413 //***************************************************************************** 414 // 415 // USB Device Class codes used in the tDeviceDescriptor.bDeviceClass field. 416 // Definitions for the bDeviceSubClass and bDeviceProtocol fields are device 417 // specific and can be found in the appropriate device class header files. 418 // 419 //***************************************************************************** 420 #define USB_CLASS_DEVICE 0x00 421 #define USB_CLASS_AUDIO 0x01 422 #define USB_CLASS_CDC 0x02 423 #define USB_CLASS_HID 0x03 424 #define USB_CLASS_PHYSICAL 0x05 425 #define USB_CLASS_IMAGE 0x06 426 #define USB_CLASS_PRINTER 0x07 427 #define USB_CLASS_MASS_STORAGE 0x08 428 #define USB_CLASS_HUB 0x09 429 #define USB_CLASS_CDC_DATA 0x0a 430 #define USB_CLASS_SMART_CARD 0x0b 431 #define USB_CLASS_SECURITY 0x0d 432 #define USB_CLASS_VIDEO 0x0e 433 #define USB_CLASS_HEALTHCARE 0x0f 434 #define USB_CLASS_DIAG_DEVICE 0xdc 435 #define USB_CLASS_WIRELESS 0xe0 436 #define USB_CLASS_MISC 0xef 437 #define USB_CLASS_APP_SPECIFIC 0xfe 438 #define USB_CLASS_VEND_SPECIFIC 0xff 439 #define USB_CLASS_EVENTS 0xffffffff 440 441 //***************************************************************************** 442 // 443 // Generic values for undefined subclass and protocol. 444 // 445 //***************************************************************************** 446 #define USB_SUBCLASS_UNDEFINED 0x00 447 #define USB_PROTOCOL_UNDEFINED 0x00 448 449 //***************************************************************************** 450 // 451 // The following are the miscellaneous subclass values. 452 // 453 //***************************************************************************** 454 #define USB_MISC_SUBCLASS_SYNC 0x01 455 #define USB_MISC_SUBCLASS_COMMON 0x02 456 457 //***************************************************************************** 458 // 459 // These following are miscellaneous protocol values. 460 // 461 //***************************************************************************** 462 #define USB_MISC_PROTOCOL_IAD 0x01 463 464 //***************************************************************************** 465 // 466 //! This structure describes the USB device qualifier descriptor as defined in 467 //! the USB 2.0 specification, section 9.6.2. 468 // 469 //***************************************************************************** 470 typedef struct 471 { 472 // 473 //! The length of this descriptor in bytes. All device qualifier 474 //! descriptors are 10 bytes long. 475 // 476 uint8 bLength; 477 478 // 479 //! The type of the descriptor. For a device descriptor, this will be 480 //! USB_DTYPE_DEVICE_QUAL (6). 481 // 482 uint8 bDescriptorType; 483 484 // 485 //! The USB Specification Release Number in BCD format. For USB 2.0, this 486 //! will be 0x0200. 487 // 488 uint16 bcdUSB; 489 490 // 491 //! The device class code. 492 // 493 uint8 bDeviceClass; 494 495 // 496 //! The device subclass code. This value qualifies the value found in the 497 //! bDeviceClass field. 498 // 499 uint8 bDeviceSubClass; 500 501 // 502 //! The device protocol code. This value is qualified by the values of 503 //! bDeviceClass and bDeviceSubClass. 504 // 505 uint8 bDeviceProtocol; 506 507 // 508 //! The maximum packet size for endpoint zero when operating at a speed 509 //! other than high speed. 510 // 511 uint8 bMaxPacketSize0; 512 513 // 514 //! The number of other-speed configurations supported. 515 // 516 uint8 bNumConfigurations; 517 518 // 519 //! Reserved for future use. Must be set to zero. 520 // 521 uint8 bReserved; 522 } 523 PACKED tDeviceQualifierDescriptor; 524 525 //***************************************************************************** 526 // 527 //! This structure describes the USB configuration descriptor as defined in 528 //! USB 2.0 specification section 9.6.3. This structure also applies to the 529 //! USB other speed configuration descriptor defined in section 9.6.4. 530 // 531 //***************************************************************************** 532 typedef struct 533 { 534 // 535 //! The length of this descriptor in bytes. All configuration descriptors 536 //! are 9 bytes long. 537 // 538 uint8 bLength; 539 540 // 541 //! The type of the descriptor. For a configuration descriptor, this will 542 //! be USB_DTYPE_CONFIGURATION (2). 543 // 544 uint8 bDescriptorType; 545 546 // 547 //! The total length of data returned for this configuration. This 548 //! includes the combined length of all descriptors (configuration, 549 //! interface, endpoint and class- or vendor-specific) returned for this 550 //! configuration. 551 // 552 uint16 wTotalLength; 553 554 // 555 //! The number of interface supported by this configuration. 556 // 557 uint8 bNumInterfaces; 558 559 // 560 //! The value used as an argument to the SetConfiguration standard request 561 //! to select this configuration. 562 // 563 uint8 bConfigurationValue; 564 565 // 566 //! The index of a string descriptor describing this configuration. 567 // 568 uint8 iConfiguration; 569 570 // 571 //! Attributes of this configuration. 572 // 573 uint8 bmAttributes; 574 575 // 576 //! The maximum power consumption of the USB device from the bus in this 577 //! configuration when the device is fully operational. This is expressed 578 //! in units of 2mA so, for example, 100 represents 200mA. 579 // 580 uint8 bMaxPower; 581 } 582 PACKED tConfigDescriptor; 583 584 //***************************************************************************** 585 // 586 // Flags used in constructing the value assigned to the field 587 // tConfigDescriptor.bmAttributes. Note that bit 7 is reserved and must be set 588 // to 1. 589 // 590 //***************************************************************************** 591 #define USB_CONF_ATTR_PWR_M 0xC0 592 593 #define USB_CONF_ATTR_SELF_PWR 0xC0 594 #define USB_CONF_ATTR_BUS_PWR 0x80 595 #define USB_CONF_ATTR_RWAKE 0xA0 596 597 //***************************************************************************** 598 // 599 //! This structure describes the USB interface descriptor as defined in USB 600 //! 2.0 specification section 9.6.5. 601 // 602 //***************************************************************************** 603 typedef struct 604 { 605 // 606 //! The length of this descriptor in bytes. All interface descriptors 607 //! are 9 bytes long. 608 // 609 uint8 bLength; 610 611 // 612 //! The type of the descriptor. For an interface descriptor, this will 613 //! be USB_DTYPE_INTERFACE (4). 614 // 615 uint8 bDescriptorType; 616 617 // 618 //! The number of this interface. This is a zero based index into the 619 //! array of concurrent interfaces supported by this configuration. 620 // 621 uint8 bInterfaceNumber; 622 623 // 624 //! The value used to select this alternate setting for the interface 625 //! defined in bInterfaceNumber. 626 // 627 uint8 bAlternateSetting; 628 629 // 630 //! The number of endpoints used by this interface (excluding endpoint 631 //! zero). 632 // 633 uint8 bNumEndpoints; 634 635 // 636 //! The interface class code as assigned by the USB-IF. 637 // 638 uint8 bInterfaceClass; 639 640 // 641 //! The interface subclass code as assigned by the USB-IF. 642 // 643 uint8 bInterfaceSubClass; 644 645 // 646 //! The interface protocol code as assigned by the USB-IF. 647 // 648 uint8 bInterfaceProtocol; 649 650 // 651 //! The index of a string descriptor describing this interface. 652 // 653 uint8 iInterface; 654 } 655 PACKED tInterfaceDescriptor; 656 657 //***************************************************************************** 658 // 659 //! This structure describes the USB endpoint descriptor as defined in USB 660 //! 2.0 specification section 9.6.6. 661 // 662 //***************************************************************************** 663 typedef struct 664 { 665 // 666 //! The length of this descriptor in bytes. All endpoint descriptors 667 //! are 7 bytes long. 668 // 669 uint8 bLength; 670 671 // 672 //! The type of the descriptor. For an endpoint descriptor, this will 673 //! be USB_DTYPE_ENDPOINT (5). 674 // 675 uint8 bDescriptorType; 676 677 // 678 //! The address of the endpoint. This field contains the endpoint number 679 //! ORed with flag USB_EP_DESC_OUT or USB_EP_DESC_IN to indicate the 680 //! endpoint direction. 681 // 682 uint8 bEndpointAddress; 683 684 // 685 //! The endpoint transfer type, USB_EP_ATTR_CONTROL, USB_EP_ATTR_ISOC, 686 //! USB_EP_ATTR_BULK or USB_EP_ATTR_INT and, if isochronous, additional 687 //! flags indicating usage type and synchronization method. 688 // 689 uint8 bmAttributes; 690 691 // 692 //! The maximum packet size this endpoint is capable of sending or 693 //! receiving when this configuration is selected. For high speed 694 //! isochronous or interrupt endpoints, bits 11 and 12 are used to 695 //! pass additional information. 696 // 697 uint16 wMaxPacketSize; 698 699 // 700 //! The polling interval for data transfers expressed in frames or 701 //! micro frames depending upon the operating speed. 702 // 703 uint8 bInterval; 704 } 705 PACKED tEndpointDescriptor; 706 707 //***************************************************************************** 708 // 709 // Flags used in constructing the value assigned to the field 710 // tEndpointDescriptor.bEndpointAddress. 711 // 712 //***************************************************************************** 713 #define USB_EP_DESC_OUT 0x00 714 #define USB_EP_DESC_IN 0x80 715 #define USB_EP_DESC_NUM_M 0x0f 716 717 //***************************************************************************** 718 // 719 // Mask used to extract the maximum packet size (in bytes) from the 720 // wMaxPacketSize field of the endpoint descriptor. 721 // 722 //***************************************************************************** 723 #define USB_EP_MAX_PACKET_COUNT_M 0x07FF 724 725 //***************************************************************************** 726 // 727 // Endpoint attributes used in tEndpointDescriptor.bmAttributes. 728 // 729 //***************************************************************************** 730 #define USB_EP_ATTR_CONTROL 0x00 731 #define USB_EP_ATTR_ISOC 0x01 732 #define USB_EP_ATTR_BULK 0x02 733 #define USB_EP_ATTR_INT 0x03 734 #define USB_EP_ATTR_TYPE_M 0x03 735 736 #define USB_EP_ATTR_ISOC_M 0x0c 737 #define USB_EP_ATTR_ISOC_NOSYNC 0x00 738 #define USB_EP_ATTR_ISOC_ASYNC 0x04 739 #define USB_EP_ATTR_ISOC_ADAPT 0x08 740 #define USB_EP_ATTR_ISOC_SYNC 0x0c 741 #define USB_EP_ATTR_USAGE_M 0x30 742 #define USB_EP_ATTR_USAGE_DATA 0x00 743 #define USB_EP_ATTR_USAGE_FEEDBACK 0x10 744 #define USB_EP_ATTR_USAGE_IMPFEEDBACK 0x20 745 746 //***************************************************************************** 747 // 748 //! This structure describes the USB string descriptor for index 0 as defined 749 //! in USB 2.0 specification section 9.6.7. Note that the number of language 750 //! IDs is variable and can be determined by examining bLength. The number of 751 //! language IDs present in the descriptor is given by ((bLength - 2) / 2). 752 // 753 //***************************************************************************** 754 typedef struct 755 { 756 // 757 //! The length of this descriptor in bytes. This value will vary 758 //! depending upon the number of language codes provided in the descriptor. 759 // 760 uint8 bLength; 761 762 // 763 //! The type of the descriptor. For a string descriptor, this will be 764 //! USB_DTYPE_STRING (3). 765 // 766 uint8 bDescriptorType; 767 768 // 769 //! The language code (LANGID) for the first supported language. Note that 770 //! this descriptor may support multiple languages, in which case, the 771 //! number of elements in the wLANGID array will increase and bLength will 772 //! be updated accordingly. 773 // 774 uint16 wLANGID[1]; 775 } 776 PACKED tString0Descriptor; 777 778 //***************************************************************************** 779 // 780 //! This structure describes the USB string descriptor for all string indexes 781 //! other than 0 as defined in USB 2.0 specification section 9.6.7. 782 // 783 //***************************************************************************** 784 typedef struct 785 { 786 // 787 //! The length of this descriptor in bytes. This value will be 2 greater 788 //! than the number of bytes comprising the UNICODE string that the 789 //! descriptor contains. 790 // 791 uint8 bLength; 792 793 // 794 //! The type of the descriptor. For a string descriptor, this will be 795 //! USB_DTYPE_STRING (3). 796 // 797 uint8 bDescriptorType; 798 799 // 800 //! The first byte of the UNICODE string. This string is not NULL 801 //! terminated. Its length (in bytes) can be computed by subtracting 2 802 //! from the value in the bLength field. 803 // 804 uint8 bString; 805 } 806 PACKED tStringDescriptor; 807 808 //***************************************************************************** 809 // 810 //! Write a 2 byte uint16 value to a USB descriptor block. 811 //! 812 //! \param usValue is the two byte uint16 that is to be written to 813 //! the descriptor. 814 //! 815 //! This helper macro is used in descriptor definitions to write two-byte 816 //! values. Since the configuration descriptor contains all interface and 817 //! endpoint descriptors in a contiguous block of memory, these descriptors are 818 //! typically defined using an array of bytes rather than as packed structures. 819 //! 820 //! \return Not a function. 821 // 822 //***************************************************************************** 823 #define USBShort(usValue) (usValue & 0xff), (usValue >> 8) 824 825 //***************************************************************************** 826 // 827 //! Write a 3 byte uint32 value to a USB descriptor block. 828 //! 829 //! \param ulValue is the three byte unsigned value that is to be written to the 830 //! descriptor. 831 //! 832 //! This helper macro is used in descriptor definitions to write three-byte 833 //! values. Since the configuration descriptor contains all interface and 834 //! endpoint descriptors in a contiguous block of memory, these descriptors are 835 //! typically defined using an array of bytes rather than as packed structures. 836 //! 837 //! \return Not a function. 838 // 839 //***************************************************************************** 840 #define USB3Byte(ulValue) (ulValue & 0xff), \ 841 ((ulValue >> 8) & 0xff), \ 842 ((ulValue >> 16) & 0xff) 843 844 //***************************************************************************** 845 // 846 //! Write a 4 byte uint32 value to a USB descriptor block. 847 //! 848 //! \param ulValue is the four byte uint32 that is to be written to the 849 //! descriptor. 850 //! 851 //! This helper macro is used in descriptor definitions to write four-byte 852 //! values. Since the configuration descriptor contains all interface and 853 //! endpoint descriptors in a contiguous block of memory, these descriptors are 854 //! typically defined using an array of bytes rather than as packed structures. 855 //! 856 //! \return Not a function. 857 // 858 //***************************************************************************** 859 #define USBLong(ulValue) (ulValue & 0xff), \ 860 ((ulValue >> 8) & 0xff), \ 861 ((ulValue >> 16) & 0xff), \ 862 ((ulValue >> 24) & 0xff) 863 864 //***************************************************************************** 865 // 866 //! Traverse to the next USB descriptor in a block. 867 //! 868 //! \param ptr points to the first byte of a descriptor in a block of 869 //! USB descriptors. 870 //! 871 //! This macro aids in traversing lists of descriptors by returning a pointer 872 //! to the next descriptor in the list given a pointer to the current one. 873 //! 874 //! \return Returns a pointer to the next descriptor in the block following 875 //! \e ptr. 876 //! 877 //***************************************************************************** 878 #define NEXT_USB_DESCRIPTOR(ptr) \ 879 (tDescriptorHeader *)(((uint8 *)(ptr)) + \ 880 *((uint8 *)(ptr))) 881 882 //***************************************************************************** 883 // 884 // Return to default packing when using the IAR Embedded Workbench compiler. 885 // 886 //***************************************************************************** 887 #if defined(ewarm) || defined(__IAR_SYSTEMS_ICC__) 888 #pragma pack() 889 #endif 890 891 //***************************************************************************** 892 // 893 // Close the usbchap9_src Doxygen group. 894 //! @} 895 // 896 //***************************************************************************** 897 898 //***************************************************************************** 899 // 900 //! \addtogroup device_api 901 //! @{ 902 // 903 //***************************************************************************** 904 905 //***************************************************************************** 906 // 907 // Function prototype for any standard USB request. 908 // 909 //***************************************************************************** 910 typedef void (* tStdRequest)(void *pvInstance, tUSBRequest *pUSBRequest); 911 912 //***************************************************************************** 913 // 914 // Data callback for receiving data from an endpoint. 915 // 916 //***************************************************************************** 917 typedef void (* tInfoCallback)(void *pvInstance, uint32 ulInfo); 918 919 //***************************************************************************** 920 // 921 // Callback made to indicate that an interface alternate setting change has 922 // occurred. 923 // 924 //***************************************************************************** 925 typedef void (* tInterfaceCallback)(void *pvInstance, 926 uint8 ucInterfaceNum, 927 uint8 ucAlternateSetting); 928 929 //***************************************************************************** 930 // 931 // Generic interrupt handler callbacks. 932 // 933 //***************************************************************************** 934 typedef void (* tUSBIntHandler)(void *pvInstance); 935 936 //***************************************************************************** 937 // 938 // Interrupt handler callbacks that have status information. 939 // 940 //***************************************************************************** 941 typedef void (* tUSBEPIntHandler)(void *pvInstance, 942 uint32 ulStatus); 943 944 //***************************************************************************** 945 // 946 // Generic handler callbacks that are used when the callers needs to call into 947 // an instance of class. 948 // 949 //***************************************************************************** 950 typedef void (* tUSBDeviceHandler)(void *pvInstance, 951 uint32 ulRequest, 952 void *pvRequestData); 953 954 //***************************************************************************** 955 // 956 //! USB event handler functions used during enumeration and operation of the 957 //! device stack. 958 // 959 //***************************************************************************** 960 typedef struct 961 { 962 // 963 //! This callback is made whenever the USB host requests a non-standard 964 //! descriptor from the device. 965 // 966 tStdRequest pfnGetDescriptor; 967 968 // 969 //! This callback is made whenever the USB host makes a non-standard 970 //! request. 971 // 972 tStdRequest pfnRequestHandler; 973 974 // 975 //! This callback is made in response to a SetInterface request from the 976 //! host. 977 // 978 tInterfaceCallback pfnInterfaceChange; 979 980 // 981 //! This callback is made in response to a SetConfiguration request from 982 //! the host. 983 // 984 tInfoCallback pfnConfigChange; 985 986 // 987 //! This callback is made when data has been received following to a call 988 //! to USBDCDRequestDataEP0. 989 // 990 tInfoCallback pfnDataReceived; 991 992 // 993 //! This callback is made when data has been transmitted following a call 994 //! to USBDCDSendDataEP0. 995 // 996 tInfoCallback pfnDataSent; 997 998 // 999 //! This callback is made when a USB reset is detected. 1000 // 1001 tUSBIntHandler pfnResetHandler; 1002 1003 // 1004 //! This callback is made when the bus has been inactive long enough to 1005 //! trigger a suspend condition. 1006 // 1007 tUSBIntHandler pfnSuspendHandler; 1008 1009 // 1010 //! This is called when resume signaling is detected. 1011 // 1012 tUSBIntHandler pfnResumeHandler; 1013 1014 // 1015 //! This callback is made when the device is disconnected from the USB bus. 1016 // 1017 tUSBIntHandler pfnDisconnectHandler; 1018 1019 // 1020 //! This callback is made to inform the device of activity on all endpoints 1021 //! other than endpoint zero. 1022 // 1023 tUSBEPIntHandler pfnEndpointHandler; 1024 1025 // 1026 //! This generic handler is provided to allow requests based on 1027 //! a given instance to be passed into a device. This is commonly used 1028 //! by a top level composite device that is using multiple instances of 1029 //! a class. 1030 // 1031 tUSBDeviceHandler pfnDeviceHandler; 1032 } 1033 tCustomHandlers; 1034 1035 //***************************************************************************** 1036 // 1037 //! This structure defines how a given endpoint's FIFO is configured in 1038 //! relation to the maximum packet size for the endpoint as specified in the 1039 //! endpoint descriptor. 1040 // 1041 //***************************************************************************** 1042 typedef struct 1043 { 1044 // 1045 //! The multiplier to apply to an endpoint's maximum packet size when 1046 //! configuring the FIFO for that endpoint. For example, setting this 1047 //! value to 2 will result in a 128 byte FIFO being configured if 1048 //! bDoubleBuffer is FALSE and the associated endpoint is set to use a 64 1049 //! byte maximum packet size. 1050 // 1051 uint8 cMultiplier; 1052 1053 // 1054 //! This field indicates whether to configure an endpoint's FIFO to be 1055 //! double- or single-buffered. If TRUE, a double-buffered FIFO is 1056 //! created and the amount of required FIFO storage is multiplied by two. 1057 // 1058 tBoolean bDoubleBuffer; 1059 1060 // 1061 //! This field defines endpoint mode flags which cannot be deduced from 1062 //! the configuration descriptor, namely any in the set USB_EP_AUTO_xxx or 1063 //! USB_EP_DMA_MODE_x. USBDCDConfig adds these flags to the endpoint 1064 //! mode and direction determined from the config descriptor before it 1065 //! configures the endpoint using a call to USBDevEndpointConfigSet(). 1066 // 1067 uint16 usEPFlags; 1068 } 1069 tFIFOEntry; 1070 1071 //***************************************************************************** 1072 // 1073 //! This structure defines endpoint and FIFO configuration information for 1074 //! all endpoints that the device wishes to use. This information cannot be 1075 //! determined by examining the USB configuration descriptor and is 1076 //! provided to USBDCDConfig by the application to allow the USB controller 1077 //! endpoints to be correctly configured. 1078 // 1079 //***************************************************************************** 1080 typedef struct 1081 { 1082 // 1083 //! An array containing one FIFO entry for each of the IN endpoints. 1084 //! Note that endpoint 0 is configured and managed by the USB device stack 1085 //! so is excluded from this array. The index 0 entry of the array 1086 //! corresponds to endpoint 1, index 1 to endpoint 2, etc. 1087 // 1088 tFIFOEntry sIn[USBLIB_NUM_EP - 1]; 1089 1090 // 1091 //! An array containing one FIFO entry for each of the OUT endpoints. 1092 //! Note that endpoint 0 is configured and managed by the USB device stack 1093 //! so is excluded from this array. The index 0 entry of the array 1094 //! corresponds to endpoint 1, index 1 to endpoint 2, etc. 1095 // 1096 tFIFOEntry sOut[USBLIB_NUM_EP - 1]; 1097 } 1098 tFIFOConfig; 1099 1100 //***************************************************************************** 1101 // 1102 //! This structure defines a contiguous block of data which contains a group 1103 //! of descriptors that form part of a configuration descriptor for a device. 1104 //! It is assumed that a config section contains only whole descriptors. It is 1105 //! not valid to split a single descriptor across multiple sections. 1106 //! 1107 //***************************************************************************** 1108 typedef struct 1109 { 1110 // 1111 //! The number of bytes of descriptor data pointed to by pucData. 1112 // 1113 uint8 ucSize; 1114 1115 // 1116 //! A pointer to a block of data containing an integral number of 1117 //! USB descriptors which form part of a larger configuration descriptor. 1118 // 1119 const uint8 *pucData; 1120 } 1121 tConfigSection; 1122 1123 //***************************************************************************** 1124 // 1125 //! This is the top level structure defining a USB device configuration 1126 //! descriptor. A configuration descriptor contains a collection of device- 1127 //! specific descriptors in addition to the basic config, interface and 1128 //! endpoint descriptors. To allow flexibility in constructing the 1129 //! configuration, the descriptor is described in terms of a list of data 1130 //! blocks. The first block must contain the configuration descriptor itself 1131 //! and the following blocks are appended to this in order to produce the 1132 //! full descriptor sent to the host in response to a GetDescriptor request 1133 //! for the configuration descriptor. 1134 //! 1135 //***************************************************************************** 1136 typedef struct 1137 { 1138 // 1139 //! The number of sections comprising the full descriptor for this 1140 //! configuration. 1141 // 1142 uint8 ucNumSections; 1143 1144 // 1145 //! A pointer to an array of ucNumSections section pointers which must 1146 //! be concatenated to form the configuration descriptor. 1147 // 1148 const tConfigSection * const *psSections; 1149 } 1150 tConfigHeader; 1151 1152 //***************************************************************************** 1153 // 1154 //! This structure is passed to the USB library on a call to USBDCDInit and 1155 //! provides the library with information about the device that the 1156 //! application is implementing. It contains functions pointers for the 1157 //! various USB event handlers and pointers to each of the standard device 1158 //! descriptors. 1159 // 1160 //***************************************************************************** 1161 typedef struct 1162 { 1163 // 1164 //! A pointer to a structure containing pointers to event handler functions 1165 //! provided by the client to support the operation of this device. 1166 // 1167 tCustomHandlers sCallbacks; 1168 1169 // 1170 //! A pointer to the device descriptor for this device. 1171 // 1172 const uint8 *pDeviceDescriptor; 1173 1174 // 1175 //! A pointer to an array of configuration descriptor pointers. Each entry 1176 //! in the array corresponds to one configuration that the device may be set 1177 //! to use by the USB host. The number of entries in the array must 1178 //! match the bNumConfigurations value in the device descriptor 1179 //! array, pDeviceDescriptor. 1180 // 1181 const tConfigHeader * const *ppConfigDescriptors; 1182 1183 // 1184 //! A pointer to the string descriptor array for this device. This array 1185 //! must be arranged as follows: 1186 //! 1187 //! - [0] - Standard descriptor containing supported language codes. 1188 //! - [1] - String 1 for the first language listed in descriptor 0. 1189 //! - [2] - String 2 for the first language listed in descriptor 0. 1190 //! - ... 1191 //! - [n] - String n for the first language listed in descriptor 0. 1192 //! - [n+1] - String 1 for the second language listed in descriptor 0. 1193 //! - ... 1194 //! - [2n] - String n for the second language listed in descriptor 0. 1195 //! - [2n+1]- String 1 for the third language listed in descriptor 0. 1196 //! - ... 1197 //! - [3n] - String n for the third language listed in descriptor 0. 1198 //! 1199 //! and so on. 1200 // 1201 const uint8 * const *ppStringDescriptors; 1202 1203 // 1204 //! The total number of descriptors provided in the ppStringDescriptors 1205 //! array. 1206 // 1207 uint32 ulNumStringDescriptors; 1208 1209 // 1210 //! A structure defining how the USB controller FIFO is to be partitioned 1211 //! between the various endpoints. This member can be set to point to 1212 //! g_sUSBDefaultFIFOConfig if the default FIFO configuration is acceptable 1213 //! This configuration sets each endpoint FIFO to be single buffered and 1214 //! sized to hold the maximum packet size for the endpoint. 1215 // 1216 const tFIFOConfig *psFIFOConfig; 1217 1218 // 1219 //! This value will be passed back to all call back functions so that 1220 //! they have access to individual instance data based on the this pointer. 1221 // 1222 void *pvInstance; 1223 } 1224 tDeviceInfo; 1225 1226 //***************************************************************************** 1227 // 1228 // Close the Doxygen group. 1229 //! @} 1230 // 1231 //***************************************************************************** 1232 1233 //***************************************************************************** 1234 // 1235 //! \addtogroup general_usblib_api 1236 //! @{ 1237 // 1238 //***************************************************************************** 1239 1240 //***************************************************************************** 1241 // 1242 // USB descriptor parsing functions found in usbdesc.c 1243 // 1244 //***************************************************************************** 1245 1246 //***************************************************************************** 1247 // 1248 //! The USB_DESC_ANY label is used as a wild card in several of the descriptor 1249 //! parsing APIs to determine whether or not particular search criteria should 1250 //! be ignored. 1251 // 1252 //***************************************************************************** 1253 #define USB_DESC_ANY 0xFFFFFFFF 1254 1255 extern uint32 USBDescGetNum(tDescriptorHeader *psDesc, 1256 uint32 ulSize, uint32 ulType); 1257 extern tDescriptorHeader *USBDescGet(tDescriptorHeader *psDesc, 1258 uint32 ulSize, 1259 uint32 ulType, 1260 uint32 ulIndex); 1261 extern uint32 1262 USBDescGetNumAlternateInterfaces(tConfigDescriptor *psConfig, 1263 uint8 ucInterfaceNumber); 1264 extern tInterfaceDescriptor *USBDescGetInterface(tConfigDescriptor *psConfig, 1265 uint32 ulIndex, 1266 uint32 ulAltCfg); 1267 extern tEndpointDescriptor * 1268 USBDescGetInterfaceEndpoint(tInterfaceDescriptor *psInterface, 1269 uint32 ulIndex, 1270 uint32 ulSize); 1271 1272 //***************************************************************************** 1273 // 1274 //! The operating mode required by the USB library client. This type is used 1275 //! by applications which wish to be able to switch between host and device 1276 //! modes by calling the USBStackModeSet() API. 1277 // 1278 //***************************************************************************** 1279 typedef enum 1280 { 1281 // 1282 //! The application wishes to operate as a USB device. 1283 // 1284 USB_MODE_DEVICE = 0, 1285 1286 // 1287 //! The application wishes to operate as a USB host. 1288 // 1289 USB_MODE_HOST, 1290 1291 // 1292 //! The application wishes to operate as both a host and device using 1293 //! On-The-Go protocols to negotiate. 1294 // 1295 USB_MODE_OTG, 1296 1297 // 1298 //! A marker indicating that no USB mode has yet been set by the 1299 //! application. 1300 // 1301 USB_MODE_NONE 1302 } tUSBMode; 1303 1304 //***************************************************************************** 1305 // 1306 // A pointer to a USB mode callback function. This function is called by the 1307 // USB library to indicate to the application which operating mode it should 1308 // use, host or device. 1309 // 1310 //***************************************************************************** 1311 typedef void (*tUSBModeCallback)(uint32 ulIndex, tUSBMode eMode); 1312 1313 //***************************************************************************** 1314 // 1315 // Mode selection and dual mode interrupt steering functions. 1316 // 1317 //***************************************************************************** 1318 extern void USBStackModeSet(uint32 ulIndex, tUSBMode eUSBMode, 1319 tUSBModeCallback pfnCallback); 1320 extern void USBDualModeInit(uint32 ulIndex); 1321 extern void USBDualModeTerm(uint32 ulIndex); 1322 extern void USBOTGMain(uint32 ulMsTicks); 1323 extern void USBOTGPollRate(uint32 ulIndex, uint32 ulPollRate); 1324 extern void USBOTGModeInit(uint32 ulIndex, uint32 ulPollRate, 1325 void *pHostData, uint32 ulHostDataSize); 1326 extern void USBOTGModeTerm(uint32 ulIndex); 1327 extern void USB0OTGModeIntHandler(void); 1328 extern void USB0DualModeIntHandler(void); 1329 1330 //***************************************************************************** 1331 // 1332 //! USB callback function. 1333 //! 1334 //! \param pvCBData is the callback pointer associated with the instance 1335 //! generating the callback. This is a value provided by the client during 1336 //! initialization of the instance making the callback. 1337 //! \param ulEvent is the identifier of the asynchronous event which is being 1338 //! notified to the client. 1339 //! \param ulMsgParam is an event-specific parameter. 1340 //! \param pvMsgData is an event-specific data pointer. 1341 //! 1342 //! A function pointer provided to the USB layer by the application 1343 //! which will be called to notify it of all asynchronous events relating to 1344 //! data transmission or reception. This callback is used by device class 1345 //! drivers and host pipe functions. 1346 //! 1347 //! \return Returns an event-dependent value. 1348 // 1349 //***************************************************************************** 1350 typedef uint32 (* tUSBCallback)(void *pvCBData, uint32 ulEvent, 1351 uint32 ulMsgParam, 1352 void *pvMsgData); 1353 1354 //***************************************************************************** 1355 // 1356 // Base identifiers for groups of USB events. These are used by both the 1357 // device class drivers and host layer. 1358 // 1359 // USB_CLASS_EVENT_BASE is the lowest identifier that should be used for 1360 // a class-specific event. Individual event bases are defined for each 1361 // of the supported device class drivers. Events with IDs between 1362 // USB_EVENT_BASE and USB_CLASS_EVENT_BASE are reserved for stack use. 1363 // 1364 //***************************************************************************** 1365 #define USB_EVENT_BASE 0x0000 1366 #define USB_CLASS_EVENT_BASE 0x8000 1367 1368 //***************************************************************************** 1369 // 1370 // Event base identifiers for the various device classes supported in host 1371 // and device modes. 1372 // The first 0x800 values of a range are reserved for the device specific 1373 // messages and the second 0x800 values of a range are used for the host 1374 // specific messages for a given class. 1375 // 1376 //***************************************************************************** 1377 #define USBD_CDC_EVENT_BASE (USB_CLASS_EVENT_BASE + 0) 1378 #define USBD_HID_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x1000) 1379 #define USBD_HID_KEYB_EVENT_BASE (USBD_HID_EVENT_BASE + 0x100) 1380 #define USBD_BULK_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x2000) 1381 #define USBD_MSC_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x3000) 1382 #define USBD_AUDIO_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x4000) 1383 1384 #define USBH_CDC_EVENT_BASE (USBD_CDC_EVENT_BASE + 0x800) 1385 #define USBH_HID_EVENT_BASE (USBD_HID_EVENT_BASE + 0x800) 1386 #define USBH_BULK_EVENT_BASE (USBD_BULK_EVENT_BASE + 0x800) 1387 #define USBH_MSC_EVENT_BASE (USBD_MSC_EVENT_BASE + 0x800) 1388 #define USBH_AUDIO_EVENT_BASE (USBD_AUDIO_EVENT_BASE + 0x800) 1389 1390 //***************************************************************************** 1391 // 1392 // General events supported by device classes and host pipes. 1393 // 1394 //***************************************************************************** 1395 1396 // 1397 //! The device is now attached to a USB host and ready to begin sending 1398 //! and receiving data (used by device classes only). 1399 // 1400 #define USB_EVENT_CONNECTED (USB_EVENT_BASE + 0) 1401 1402 // 1403 //! The device has been disconnected from the USB host (used by device classes 1404 //! only). 1405 //! 1406 //! Note: Due to a hardware erratum in revision A of LM3S3748, this 1407 //! event is not posted to self-powered USB devices when they are disconnected 1408 //! from the USB host. 1409 // 1410 #define USB_EVENT_DISCONNECTED (USB_EVENT_BASE + 1) 1411 1412 // 1413 //! Data has been received and is in the buffer provided. 1414 // 1415 #define USB_EVENT_RX_AVAILABLE (USB_EVENT_BASE + 2) 1416 1417 // 1418 //! This event is sent by a lower layer to inquire about the amount of 1419 //! unprocessed data buffered in the layers above. It is used in cases 1420 //! where a low level driver needs to ensure that all preceding data has 1421 //! been processed prior to performing some action or making some notification. 1422 //! Clients receiving this event should return the number of bytes of data 1423 //! that are unprocessed or 0 if no outstanding data remains. 1424 // 1425 #define USB_EVENT_DATA_REMAINING (USB_EVENT_BASE + 3) 1426 1427 // 1428 //! This event is sent by a lower layer supporting DMA to request a buffer in 1429 //! which the next received packet may be stored. The \e ulMsgValue parameter 1430 //! indicates the maximum size of packet that can be received in this channel 1431 //! and \e pvMsgData points to storage which should be written with the 1432 //! returned buffer pointer. The return value from the callback should be the 1433 //! size of the buffer allocated (which may be less than the maximum size 1434 //! passed in \e ulMsgValue if the client knows that fewer bytes are expected 1435 //! to be received) or 0 if no buffer is being returned. 1436 // 1437 #define USB_EVENT_REQUEST_BUFFER (USB_EVENT_BASE + 4) 1438 1439 // 1440 //! Data has been sent and acknowledged. If this event is received via the 1441 //! USB buffer callback, the \e ulMsgValue parameter indicates the number of 1442 //! bytes from the transmit buffer that have been successfully transmitted 1443 //! and acknowledged. 1444 // 1445 #define USB_EVENT_TX_COMPLETE (USB_EVENT_BASE + 5) 1446 1447 // 1448 //! An error has been reported on the channel or pipe. The \e ulMsgValue 1449 //! parameter indicates the source(s) of the error and is the logical OR 1450 //! combination of "USBERR_" flags defined below. 1451 // 1452 #define USB_EVENT_ERROR (USB_EVENT_BASE + 6) 1453 1454 // 1455 //! The bus has entered suspend state. 1456 // 1457 #define USB_EVENT_SUSPEND (USB_EVENT_BASE + 7) 1458 1459 // 1460 //! The bus has left suspend state. 1461 // 1462 #define USB_EVENT_RESUME (USB_EVENT_BASE + 8) 1463 1464 // 1465 //! A scheduler event has occurred. 1466 // 1467 #define USB_EVENT_SCHEDULER (USB_EVENT_BASE + 9) 1468 // 1469 //! A device or host has detected a stall condition. 1470 // 1471 #define USB_EVENT_STALL (USB_EVENT_BASE + 10) 1472 1473 // 1474 //! The host detected a power fault condition. 1475 // 1476 #define USB_EVENT_POWER_FAULT (USB_EVENT_BASE + 11) 1477 1478 // 1479 //! The controller has detected a A-Side cable and needs power applied This is 1480 //! only generated on OTG parts if automatic power control is disabled. 1481 // 1482 #define USB_EVENT_POWER_ENABLE (USB_EVENT_BASE + 12) 1483 1484 // 1485 //! The controller needs power removed, This is only generated on OTG parts 1486 //! if automatic power control is disabled. 1487 // 1488 #define USB_EVENT_POWER_DISABLE (USB_EVENT_BASE + 13) 1489 1490 // 1491 //! Used with pfnDeviceHandler handler function is classes to indicate changes 1492 //! in the interface number by a class outside the class being accessed. 1493 //! Typically this is when composite device class is in use. 1494 //! 1495 //! The \e pvInstance value should point to an instance of the device being 1496 //! accessed. 1497 //! 1498 //! The \e ulRequest should be USB_EVENT_COMP_IFACE_CHANGE. 1499 //! 1500 //! The \e pvRequestData should point to a two byte array where the first value 1501 //! is the old interface number and the second is the new interface number. 1502 // 1503 #define USB_EVENT_COMP_IFACE_CHANGE (USB_EVENT_BASE + 14) 1504 1505 // 1506 //! Used with pfnDeviceHandler handler function is classes to indicate changes 1507 //! in endpoint number by a class outside the class being accessed. 1508 //! Typically this is when composite device class is in use. 1509 //! 1510 //! The \e pvInstance value should point to an instance of the device being 1511 //! accessed. 1512 //! 1513 //! The \e ulRequest should be USB_EVENT_COMP_EP_CHANGE. 1514 //! 1515 //! The \e pvRequestData should point to a two byte array where the first value 1516 //! is the old endpoint number and the second is the new endpoint number. The 1517 //! endpoint numbers should be exactly as USB specification defines them and 1518 //! bit 7 set indicates an IN endpoint and bit 7 clear indicates an OUT 1519 //! endpoint. 1520 // 1521 #define USB_EVENT_COMP_EP_CHANGE (USB_EVENT_BASE + 15) 1522 1523 // 1524 //! Used with pfnDeviceHandler handler function is classes to indicate changes 1525 //! in string index number by a class outside the class being accessed. 1526 //! Typically this is when composite device class is in use. 1527 //! 1528 //! The \e pvInstance value should point to an instance of the device being 1529 //! accessed. 1530 //! 1531 //! The \e ulRequest should be USB_EVENT_COMP_STR_CHANGE. 1532 //! 1533 //! The \e pvRequestData should point to a two byte array where the first value 1534 //! is the old string index and the second is the new string index. 1535 // 1536 #define USB_EVENT_COMP_STR_CHANGE (USB_EVENT_BASE + 16) 1537 1538 // 1539 //! Used with pfnDeviceHandler handler function is classes to allow the device 1540 //! class to make final adjustments to the configuration descriptor. 1541 //! This is only used when a device class is used in a composite device class 1542 //! is in use. 1543 //! 1544 //! The \e pvInstance value should point to an instance of the device being 1545 //! accessed. 1546 //! 1547 //! The \e ulRequest should be USB_EVENT_COMP_CONFIG. 1548 //! 1549 //! The \e pvRequestData should point to the beginning of the configuration 1550 //! descriptor for the device instance. 1551 // 1552 #define USB_EVENT_COMP_CONFIG (USB_EVENT_BASE + 17) 1553 1554 //***************************************************************************** 1555 // 1556 // Error sources reported via USB_EVENT_ERROR. 1557 // 1558 //***************************************************************************** 1559 1560 // 1561 //! The host received an invalid PID in a transaction. 1562 // 1563 #define USBERR_HOST_IN_PID_ERROR 0x01000000 1564 1565 // 1566 //! The host did not receive a response from a device. 1567 // 1568 #define USBERR_HOST_IN_NOT_COMP 0x00100000 1569 1570 // 1571 //! The host received a stall on an IN endpoint. 1572 // 1573 #define USBERR_HOST_IN_STALL 0x00400000 1574 1575 // 1576 //! The host detected a CRC or bit-stuffing error (isochronous mode). 1577 // 1578 #define USBERR_HOST_IN_DATA_ERROR 0x00080000 1579 1580 // 1581 //! The host received NAK on an IN endpoint for longer than the specified 1582 //! timeout period (interrupt, bulk and control modes). 1583 // 1584 #define USBERR_HOST_IN_NAK_TO 0x00080000 1585 1586 // 1587 //! The host failed to communicate with a device via an IN endpoint. 1588 // 1589 #define USBERR_HOST_IN_ERROR 0x00040000 1590 1591 // 1592 //! The host receive FIFO is full. 1593 // 1594 #define USBERR_HOST_IN_FIFO_FULL 0x00020000 // RX FIFO full 1595 // 1596 //! The host received NAK on an OUT endpoint for longer than the specified 1597 //! timeout period (bulk, interrupt and control modes). 1598 // 1599 #define USBERR_HOST_OUT_NAK_TO 0x00000080 1600 1601 // 1602 //! The host did not receive a response from a device (isochronous mode). 1603 // 1604 #define USBERR_HOST_OUT_NOT_COMP 0x00000080 1605 1606 // 1607 //! The host received a stall on an OUT endpoint. 1608 // 1609 #define USBERR_HOST_OUT_STALL 0x00000020 1610 1611 // 1612 //! The host failed to communicate with a device via an OUT endpoint. 1613 // 1614 #define USBERR_HOST_OUT_ERROR 0x00000004 1615 1616 // 1617 //! The host received NAK on endpoint 0 for longer than the configured 1618 //! timeout. 1619 // 1620 #define USBERR_HOST_EP0_NAK_TO 0x00000080 1621 1622 // 1623 //! The host failed to communicate with a device via an endpoint zero. 1624 // 1625 #define USBERR_HOST_EP0_ERROR 0x00000010 1626 1627 // 1628 //! The device detected a CRC error in received data. 1629 // 1630 #define USBERR_DEV_RX_DATA_ERROR 0x00080000 1631 1632 // 1633 //! The device was unable to receive a packet from the host since the receive 1634 //! FIFO is full. 1635 // 1636 #define USBERR_DEV_RX_OVERRUN 0x00040000 1637 1638 // 1639 //! The device receive FIFO is full. 1640 // 1641 #define USBERR_DEV_RX_FIFO_FULL 0x00020000 // RX FIFO full 1642 1643 //***************************************************************************** 1644 // 1645 // Close the general_usblib_api Doxygen group. 1646 //! @} 1647 // 1648 //***************************************************************************** 1649 1650 //***************************************************************************** 1651 // 1652 //! \addtogroup usblib_buffer_api 1653 //! @{ 1654 // 1655 //***************************************************************************** 1656 1657 //***************************************************************************** 1658 // 1659 //! A function pointer type which describes either a class driver packet read 1660 //! or packet write function (both have the same prototype) to the USB 1661 //! buffer object. 1662 // 1663 //***************************************************************************** 1664 typedef uint32 (* tUSBPacketTransfer)(void *pvHandle, 1665 uint8 *pcData, 1666 uint32 ulLength, 1667 tBoolean bLast); 1668 1669 //***************************************************************************** 1670 // 1671 //! A function pointer type which describes either a class driver transmit 1672 //! or receive packet available function (both have the same prototype) to the 1673 //! USB buffer object. 1674 // 1675 //***************************************************************************** 1676 typedef uint32 (* tUSBPacketAvailable)(void *pvHandle); 1677 1678 //***************************************************************************** 1679 // 1680 //! The number of bytes of workspace that each USB buffer object requires. 1681 //! This workspace memory is provided to the buffer on USBBufferInit() in 1682 //! the \e pvWorkspace field of the \e tUSBBuffer structure. 1683 // 1684 //***************************************************************************** 1685 #define USB_BUFFER_WORKSPACE_SIZE 16 1686 1687 //***************************************************************************** 1688 // 1689 //! The structure used by the application to initialize a buffer object that 1690 //! will provide buffered access to either a transmit or receive channel. 1691 // 1692 //***************************************************************************** 1693 typedef struct 1694 { 1695 // 1696 //! This field sets the mode of the buffer. If TRUE, the buffer 1697 //! operates as a transmit buffer and supports calls to USBBufferWrite 1698 //! by the client. If FALSE, the buffer operates as a receive buffer 1699 //! and supports calls to USBBufferRead. 1700 // 1701 tBoolean bTransmitBuffer; 1702 1703 // 1704 //! A pointer to the callback function which will be called to notify 1705 //! the application of all asynchronous events related to the operation 1706 //! of the buffer. 1707 // 1708 tUSBCallback pfnCallback; 1709 1710 // 1711 //! A pointer that the buffer will pass back to the client in the 1712 //! first parameter of all callbacks related to this instance. 1713 // 1714 void *pvCBData; 1715 1716 // 1717 //! The function which should be called to transmit a packet of data 1718 //! in transmit mode or receive a packet in receive mode. 1719 // 1720 tUSBPacketTransfer pfnTransfer; 1721 1722 // 1723 //! The function which should be called to determine if the endpoint is 1724 //! ready to accept a new packet for transmission in transmit mode or 1725 //! to determine the size of the buffer required to read a packet in 1726 //! receive mode. 1727 // 1728 tUSBPacketAvailable pfnAvailable; 1729 1730 // 1731 //! The handle to pass to the low level function pointers 1732 //! provided in the pfnTransfer and pfnAvailable members. For USB device 1733 //! use, this is the psDevice parameter required by the relevant device 1734 //! class driver APIs. For USB host use, this is the pipe identifier 1735 //! returned by USBHCDPipeAlloc. 1736 // 1737 void *pvHandle; 1738 1739 // 1740 //! A pointer to memory to be used as the ring buffer for this 1741 //! instance. 1742 // 1743 uint8 *pcBuffer; 1744 1745 // 1746 //! The size, in bytes, of the buffer pointed to by pcBuffer. 1747 // 1748 uint32 ulBufferSize; 1749 1750 // 1751 //! A pointer to USB_BUFFER_WORKSPACE_SIZE bytes of RAM that the buffer 1752 //! object can use for workspace. 1753 // 1754 void *pvWorkspace; 1755 } 1756 tUSBBuffer; 1757 1758 //***************************************************************************** 1759 // 1760 //! The structure used for encapsulating all the items associated with a 1761 //! ring buffer. 1762 // 1763 //***************************************************************************** 1764 typedef struct 1765 { 1766 // 1767 //! The ring buffer size. 1768 // 1769 uint32 ulSize; 1770 1771 // 1772 //! The ring buffer write index. 1773 // 1774 volatile uint32 ulWriteIndex; 1775 1776 // 1777 //! The ring buffer read index. 1778 // 1779 volatile uint32 ulReadIndex; 1780 1781 // 1782 //! The ring buffer. 1783 // 1784 uint8 *pucBuf; 1785 } 1786 tUSBRingBufObject; 1787 1788 //***************************************************************************** 1789 // 1790 // USB buffer API function prototypes. 1791 // 1792 //***************************************************************************** 1793 extern const tUSBBuffer *USBBufferInit(const tUSBBuffer *psBuffer); 1794 extern void USBBufferInfoGet(const tUSBBuffer *psBuffer, 1795 tUSBRingBufObject *psRingBuf); 1796 extern void *USBBufferCallbackDataSet(tUSBBuffer *psBuffer, void *pvCBData); 1797 extern uint32 USBBufferWrite(const tUSBBuffer *psBuffer, 1798 const uint8 *pucData, 1799 uint32 ulLength); 1800 extern void USBBufferDataWritten(const tUSBBuffer *psBuffer, 1801 uint32 ulLength); 1802 extern void USBBufferDataRemoved(const tUSBBuffer *psBuffer, 1803 uint32 ulLength); 1804 extern void USBBufferFlush(const tUSBBuffer *psBuffer); 1805 extern uint32 USBBufferRead(const tUSBBuffer *psBuffer, 1806 uint8 *pucData, 1807 uint32 ulLength); 1808 extern uint32 USBBufferDataAvailable(const tUSBBuffer *psBuffer); 1809 extern uint32 USBBufferSpaceAvailable(const tUSBBuffer *psBuffer); 1810 extern uint32 USBBufferEventCallback(void *pvCBData, 1811 uint32 ulEvent, 1812 uint32 ulMsgValue, 1813 void *pvMsgData); 1814 extern tBoolean USBRingBufFull(tUSBRingBufObject *ptUSBRingBuf); 1815 extern tBoolean USBRingBufEmpty(tUSBRingBufObject *ptUSBRingBuf); 1816 extern void USBRingBufFlush(tUSBRingBufObject *ptUSBRingBuf); 1817 extern uint32 USBRingBufUsed(tUSBRingBufObject *ptUSBRingBuf); 1818 extern uint32 USBRingBufFree(tUSBRingBufObject *ptUSBRingBuf); 1819 extern uint32 USBRingBufContigUsed(tUSBRingBufObject *ptUSBRingBuf); 1820 extern uint32 USBRingBufContigFree(tUSBRingBufObject *ptUSBRingBuf); 1821 extern uint32 USBRingBufSize(tUSBRingBufObject *ptUSBRingBuf); 1822 extern uint8 USBRingBufReadOne(tUSBRingBufObject *ptUSBRingBuf); 1823 extern void USBRingBufRead(tUSBRingBufObject *ptUSBRingBuf, 1824 uint8 *pucData, uint32 ulLength); 1825 extern void USBRingBufWriteOne(tUSBRingBufObject *ptUSBRingBuf, 1826 uint8 ucData); 1827 extern void USBRingBufWrite(tUSBRingBufObject *ptUSBRingBuf, 1828 const uint8 *pucData, 1829 uint32 ulLength); 1830 extern void USBRingBufAdvanceWrite(tUSBRingBufObject *ptUSBRingBuf, 1831 uint32 ulNumBytes); 1832 extern void USBRingBufAdvanceRead(tUSBRingBufObject *ptUSBRingBuf, 1833 uint32 ulNumBytes); 1834 extern void USBRingBufInit(tUSBRingBufObject *ptUSBRingBuf, 1835 uint8 *pucBuf, uint32 ulSize); 1836 1837 //***************************************************************************** 1838 // 1839 // Close the Doxygen group. 1840 //! @} 1841 // 1842 //***************************************************************************** 1843 1844 //***************************************************************************** 1845 // 1846 // Mark the end of the C bindings section for C++ compilers. 1847 // 1848 //***************************************************************************** 1849 #ifdef __cplusplus 1850 } 1851 #endif 1852 1853 #endif // __USBLIB_H__ 1854