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