+/rtos

git clone https://git.julia.blue/+/rtos

Vivek Malneediusb headers326af29

master
66.7 KiB1899 linesraw
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    //
171    uint8_t bmRequestType;
172
173    //
174    //! Identifies the specific request being made.
175    //
176    uint8_t bRequest;
177
178    //
179    //! Word-sized field that varies according to the request.
180    //
181    uint16_t wValue;
182
183    //
184    //! Word-sized field that varies according to the request; typically used
185    //! to pass an index or offset.
186    //
187    uint16_t wIndex;
188
189    //
190    //! The number of bytes to transfer if there is a data stage to the
191    //! request.
192    //
193    uint16_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    //
306    uint8_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    //
314    uint8_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    //
328    uint8_t bLength;
329
330    //
331    //! The type of the descriptor.  For a device descriptor, this will be
332    //! USB_DTYPE_DEVICE (1).
333    //
334    uint8_t bDescriptorType;
335
336    //
337    //! The USB Specification Release Number in BCD format.  For USB 2.0, this
338    //! will be 0x0200.
339    //
340    uint16_t bcdUSB;
341
342    //
343    //! The device class code.
344    //
345    uint8_t bDeviceClass;
346
347    //
348    //! The device subclass code.  This value qualifies the value found in the
349    //! bDeviceClass field.
350    //
351    uint8_t bDeviceSubClass;
352
353    //
354    //! The device protocol code.  This value is qualified by the values of
355    //! bDeviceClass and bDeviceSubClass.
356    //
357    uint8_t bDeviceProtocol;
358
359    //
360    //! The maximum packet size for endpoint zero.  Valid values are 8, 16, 32
361    //! and 64.
362    //
363    uint8_t bMaxPacketSize0;
364
365    //
366    //! The device Vendor ID (VID) as assigned by the USB-IF.
367    //
368    uint16_t idVendor;
369
370    //
371    //! The device Product ID (PID) as assigned by the manufacturer.
372    //
373    uint16_t idProduct;
374
375    //
376    //! The device release number in BCD format.
377    //
378    uint16_t bcdDevice;
379
380    //
381    //! The index of a string descriptor describing the manufacturer.
382    //
383    uint8_t iManufacturer;
384
385    //
386    //! The index of a string descriptor describing the product.
387    //
388    uint8_t iProduct;
389
390    //
391    //! The index of a string descriptor describing the device's serial
392    //! number.
393    //
394    uint8_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    //
401    uint8_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    //
475    uint8_t bLength;
476
477    //
478    //! The type of the descriptor.  For a device descriptor, this will be
479    //! USB_DTYPE_DEVICE_QUAL (6).
480    //
481    uint8_t bDescriptorType;
482
483    //
484    //! The USB Specification Release Number in BCD format.  For USB 2.0, this
485    //! will be 0x0200.
486    //
487    uint16_t bcdUSB;
488
489    //
490    //! The device class code.
491    //
492    uint8_t bDeviceClass;
493
494    //
495    //! The device subclass code.  This value qualifies the value found in the
496    //! bDeviceClass field.
497    //
498    uint8_t bDeviceSubClass;
499
500    //
501    //! The device protocol code.  This value is qualified by the values of
502    //! bDeviceClass and bDeviceSubClass.
503    //
504    uint8_t bDeviceProtocol;
505
506    //
507    //! The maximum packet size for endpoint zero when operating at a speed
508    //! other than high speed.
509    //
510    uint8_t bMaxPacketSize0;
511
512    //
513    //! The number of other-speed configurations supported.
514    //
515    uint8_t bNumConfigurations;
516
517    //
518    //! Reserved for future use.  Must be set to zero.
519    //
520    uint8_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    //
535    uint8_t bLength;
536
537    //
538    //! The type of the descriptor.  For a configuration descriptor, this will
539    //! be USB_DTYPE_CONFIGURATION (2).
540    //
541    uint8_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    //
549    uint16_t wTotalLength;
550
551    //
552    //! The number of interface supported by this configuration.
553    //
554    uint8_t bNumInterfaces;
555
556    //
557    //! The value used as an argument to the SetConfiguration standard request
558    //! to select this configuration.
559    //
560    uint8_t bConfigurationValue;
561
562    //
563    //! The index of a string descriptor describing this configuration.
564    //
565    uint8_t iConfiguration;
566
567    //
568    //! Attributes of this configuration.
569    //
570    uint8_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    //
577    uint8_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    //
604    uint8_t bLength;
605
606    //
607    //! The type of the descriptor.  For an interface descriptor, this will
608    //! be USB_DTYPE_INTERFACE (4).
609    //
610    uint8_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    //
616    uint8_t bInterfaceNumber;
617
618    //
619    //! The value used to select this alternate setting for the interface
620    //! defined in bInterfaceNumber.
621    //
622    uint8_t bAlternateSetting;
623
624    //
625    //! The number of endpoints used by this interface (excluding endpoint
626    //! zero).
627    //
628    uint8_t bNumEndpoints;
629
630    //
631    //! The interface class code as assigned by the USB-IF.
632    //
633    uint8_t bInterfaceClass;
634
635    //
636    //! The interface subclass code as assigned by the USB-IF.
637    //
638    uint8_t bInterfaceSubClass;
639
640    //
641    //! The interface protocol code as assigned by the USB-IF.
642    //
643    uint8_t bInterfaceProtocol;
644
645    //
646    //! The index of a string descriptor describing this interface.
647    //
648    uint8_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    //
662    uint8_t bLength;
663
664    //
665    //! The type of the descriptor.  For an endpoint descriptor, this will
666    //! be USB_DTYPE_ENDPOINT (5).
667    //
668    uint8_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    //
675    uint8_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    //
682    uint8_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    //
690    uint16_t wMaxPacketSize;
691
692    //
693    //! The polling interval for data transfers expressed in frames or
694    //! micro frames depending upon the operating speed.
695    //
696    uint8_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    //
751    uint8_t bLength;
752
753    //
754    //! The type of the descriptor.  For a string descriptor, this will be
755    //! USB_DTYPE_STRING (3).
756    //
757    uint8_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    //
765    uint16_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    //
780    uint8_t bLength;
781
782    //
783    //! The type of the descriptor.  For a string descriptor, this will be
784    //! USB_DTYPE_STRING (3).
785    //
786    uint8_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    //
793    uint8_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,
908                                   uint8_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,
931                                  void* 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    //
944    tStdRequest pfnGetDescriptor;
945
946    //
947    //! This callback is made whenever the USB host makes a non-standard
948    //! request.
949    //
950    tStdRequest pfnRequestHandler;
951
952    //
953    //! This callback is made in response to a SetInterface request from the
954    //! host.
955    //
956    tInterfaceCallback pfnInterfaceChange;
957
958    //
959    //! This callback is made in response to a SetConfiguration request from
960    //! the host.
961    //
962    tInfoCallback pfnConfigChange;
963
964    //
965    //! This callback is made when data has been received following to a call
966    //! to USBDCDRequestDataEP0.
967    //
968    tInfoCallback pfnDataReceived;
969
970    //
971    //! This callback is made when data has been transmitted following a call
972    //! to USBDCDSendDataEP0.
973    //
974    tInfoCallback pfnDataSent;
975
976    //
977    //! This callback is made when a USB reset is detected.
978    //
979    tUSBIntHandler pfnResetHandler;
980
981    //
982    //! This callback is made when the bus has been inactive long enough to
983    //! trigger a suspend condition.
984    //
985    tUSBIntHandler pfnSuspendHandler;
986
987    //
988    //! This is called when resume signaling is detected.
989    //
990    tUSBIntHandler pfnResumeHandler;
991
992    //
993    //! This callback is made when the device is disconnected from the USB bus.
994    //
995    tUSBIntHandler pfnDisconnectHandler;
996
997    //
998    //! This callback is made to inform the device of activity on all endpoints
999    //! other than endpoint zero.
1000    //
1001    tUSBEPIntHandler 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    //
1009    tUSBDeviceHandler 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    //
1024    uint16_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    //
1030    const 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    //
1051    uint8_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    //
1057    const 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,
1097                              uint32_t ui32Type);
1098extern tDescriptorHeader* USBDescGet(tDescriptorHeader* psDesc,
1099                                     uint32_t ui32Size, uint32_t ui32Type,
1100                                     uint32_t ui32Index);
1101extern uint32_t USBDescGetNumAlternateInterfaces(tConfigDescriptor* psConfig,
1102                                                 uint8_t ui8InterfaceNumber);
1103extern tInterfaceDescriptor* USBDescGetInterface(tConfigDescriptor* psConfig,
1104                                                 uint32_t ui32Index,
1105                                                 uint32_t ui32AltCfg);
1106extern tEndpointDescriptor*
1107USBDescGetInterfaceEndpoint(tInterfaceDescriptor* psInterface,
1108                            uint32_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    //
1122    eUSBModeDevice = 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    //
1128    eUSBModeHost,
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    //
1134    eUSBModeOTG,
1135
1136    //
1137    //! A marker indicating that no USB mode has yet been set by the
1138    //! application.
1139    //
1140    eUSBModeNone,
1141
1142    //
1143    //! Force host mode so that the VBUS and ID pins are not used or monitored
1144    //! by the USB controller.
1145    //
1146    eUSBModeForceHost,
1147
1148    //
1149    //! Forcing device mode so that the VBUS and ID pins are not used or
1150    //! monitored by the USB controller.
1151    //
1152    eUSBModeForceDevice,
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,
1185                                 uint32_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    //
1303    uint32_t ui32Event;
1304
1305    //
1306    //! The caller supplied instance value that is passed to event handlers.
1307    //
1308    uint32_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,
1573                                       uint32_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 {
1705    uint32_t ui32HIRD;
1706    uint32_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    //
1719    uint32_t ui32Size;
1720
1721    //
1722    //! The ring buffer write index.
1723    //
1724    volatile uint32_t ui32WriteIndex;
1725
1726    //
1727    //! The ring buffer read index.
1728    //
1729    volatile uint32_t ui32ReadIndex;
1730
1731    //
1732    //! The ring buffer.
1733    //
1734    uint8_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 {
1744    tUSBRingBufObject sRingBuf;
1745    uint32_t ui32LastSent;
1746    uint32_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    //
1762    bool 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    //
1769    tUSBCallback 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    //
1775    void* 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    //
1781    tUSBPacketTransfer 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    //
1789    tUSBPacketAvailable 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    //
1798    void* pvHandle;
1799
1800    //
1801    //! A pointer to memory to be used as the ring buffer for this
1802    //! instance.
1803    //
1804    uint8_t* pui8Buffer;
1805
1806    //
1807    //! The size, in bytes, of the buffer pointed to by pi8Buffer.
1808    //
1809    uint32_t ui32BufferSize;
1810
1811    //
1812    //! The private data for the USB buffer that is allocated by the
1813    //! application.
1814    //
1815    tUSBBufferVars 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,
1832                                            bool bSendZLP);
1833extern void USBBufferInfoGet(const tUSBBuffer* psBuffer,
1834                             tUSBRingBufObject* psRingBuf);
1835extern void* USBBufferCallbackDataSet(tUSBBuffer* psBuffer, void* pvCBData);
1836extern uint32_t USBBufferWrite(const tUSBBuffer* psBuffer,
1837                               const uint8_t* pui8Data, uint32_t ui32Length);
1838extern void USBBufferDataWritten(const tUSBBuffer* psBuffer,
1839                                 uint32_t ui32Length);
1840extern void USBBufferDataRemoved(const tUSBBuffer* psBuffer,
1841                                 uint32_t ui32Length);
1842extern void USBBufferFlush(const tUSBBuffer* psBuffer);
1843extern uint32_t USBBufferRead(const tUSBBuffer* psBuffer, uint8_t* pui8Data,
1844                              uint32_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,
1848                                       uint32_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,
1859                           uint32_t ui32Length);
1860extern void USBRingBufWriteOne(tUSBRingBufObject* psUSBRingBuf,
1861                               uint8_t ui8Data);
1862extern void USBRingBufWrite(tUSBRingBufObject* psUSBRingBuf,
1863                            const uint8_t* pui8Data, uint32_t ui32Length);
1864extern void USBRingBufAdvanceWrite(tUSBRingBufObject* psUSBRingBuf,
1865                                   uint32_t ui32NumBytes);
1866extern void USBRingBufAdvanceRead(tUSBRingBufObject* psUSBRingBuf,
1867                                  uint32_t ui32NumBytes);
1868extern void USBRingBufInit(tUSBRingBufObject* psUSBRingBuf, uint8_t* pui8Buf,
1869                           uint32_t ui32Size);
1870
1871//*****************************************************************************
1872//
1873// Mode selection and dual mode interrupt steering functions.
1874//
1875//*****************************************************************************
1876extern void USBStackModeSet(uint32_t ui32Index, tUSBMode iUSBMode,
1877                            tUSBModeCallback 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,
1883                           void* pHostData, uint32_t ui32HostDataSize);
1884extern void USBOTGModeTerm(uint32_t ui32Index);
1885extern void USB0OTGModeIntHandler(void);
1886extern bool USBOTGFeatureSet(uint32_t ui32Index, uint32_t ui32Feature,
1887                             void* 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__