+/rtos

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

Vivek Malneediusb headers326af29

master
41.9 KiB1084 linesraw
1//*****************************************************************************
2//
3// usbdhid.h - Definitions used by HID class devices.
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 __USBDHID_H__
26#define __USBDHID_H__
27#include "usblib/device/usbdevicepriv.h"
28#include "usblib/usbhid.h"
29
30//*****************************************************************************
31//
32// If building with a C++ compiler, make all of the definitions in this header
33// have a C binding.
34//
35//*****************************************************************************
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40//*****************************************************************************
41//
42//! \addtogroup hid_device_class_api
43//! @{
44//
45//*****************************************************************************
46
47//*****************************************************************************
48//
49// This is the size of the g_pui8HIDInterface array in bytes.
50//
51//*****************************************************************************
52#define HIDINTERFACE_SIZE (9)
53
54//*****************************************************************************
55//
56// This is the size of the g_pui8HIDInEndpoint array in bytes.
57//
58//*****************************************************************************
59#define HIDINENDPOINT_SIZE (7)
60
61//*****************************************************************************
62//
63// This is the size of the g_pui8HIDOutEndpoint array in bytes.
64//
65//*****************************************************************************
66#define HIDOUTENDPOINT_SIZE (7)
67
68//*****************************************************************************
69//
70// This is the size of the tHIDDescriptor in bytes.
71//
72//*****************************************************************************
73#define HIDDESCRIPTOR_SIZE (9)
74
75//*****************************************************************************
76//
77//! The size of the memory that should be allocated to create a configuration
78//! descriptor for a single instance of the USB HID Device.
79//! This does not include the configuration descriptor which is automatically
80//! ignored by the composite device class.
81//
82//*****************************************************************************
83#define COMPOSITE_DHID_SIZE                                                    \
84    (HIDINTERFACE_SIZE + HIDINENDPOINT_SIZE + HIDOUTENDPOINT_SIZE +            \
85     HIDDESCRIPTOR_SIZE)
86
87//*****************************************************************************
88//
89// Macros used to create the static Report Descriptors.
90//
91//*****************************************************************************
92
93//*****************************************************************************
94//
95//! This is a macro to assist adding Usage Page entries in HID report
96//! descriptors.
97//!
98//! \param ui8Value is the Usage Page value.
99//!
100//! This macro takes a value and prepares it to be placed as a Usage Page entry
101//! into a HID report structure.  These are defined by the USB HID
102//! specification.
103//!
104//! \return Not a function.
105//
106//*****************************************************************************
107#define UsagePage(ui8Value) 0x05, ((ui8Value)&0xff)
108
109//*****************************************************************************
110//
111//! This is a macro to assist adding Usage Page entries in HID report
112//! descriptors when a vendor-specific value is to be used.
113//!
114//! \param ui16Value is the Usage Page value.
115//!
116//! This macro takes a value and prepares it to be placed as a Usage Page entry
117//! into a HID report structure.  These are defined by the USB HID
118//! specification.  Vendor-specific values must lie in the range 0xFF00 to
119//! 0xFFFF inclusive.
120//!
121//! \return Not a function.
122//
123//*****************************************************************************
124#define UsagePageVendor(ui16Value)                                             \
125    0x06, ((ui16Value)&0xFF), (((ui16Value) >> 8) & 0xFF)
126
127//*****************************************************************************
128//
129//! This is a macro to assist adding Usage entries in HID report descriptors.
130//!
131//! \param ui8Value is the Usage value.
132//!
133//! This macro takes a value and prepares it to be placed as a Usage entry into
134//! a HID report structure.  These are defined by the USB HID specification.
135//!
136//! \return Not a function.
137//
138//*****************************************************************************
139#define Usage(ui8Value) 0x09, ((ui8Value)&0xff)
140
141//*****************************************************************************
142//
143//! This is a macro to assist adding vendor-specific Usage entries in HID
144//! report descriptors.
145//!
146//! \param ui16Value is the vendor-specific Usage value in the range 0xFF00 to
147//! 0xFFFF.
148//!
149//! This macro takes a value and prepares it to be placed as a Usage entry into
150//! a HID report structure.  These are defined by the USB HID specification.
151//!
152//! \return Not a function.
153//
154//*****************************************************************************
155#define UsageVendor(ui16Value)                                                 \
156    0x0A, ((ui16Value)&0xFF), (((ui16Value) >> 8) & 0xFF)
157
158//*****************************************************************************
159//
160//! This is a macro to assist adding Usage Minimum entries in HID report
161//! descriptors.
162//!
163//! \param ui8Value is the Usage Minimum value.
164//!
165//! This macro takes a value and prepares it to be placed as a Usage Minimum
166//! entry into a HID report structure.  This is the first or minimum value
167//! associated with a usage value.
168//!
169//! \return Not a function.
170//
171//*****************************************************************************
172#define UsageMinimum(ui8Value) 0x19, ((ui8Value)&0xff)
173
174//*****************************************************************************
175//
176//! This is a macro to assist adding Usage Maximum entries in HID report
177//! descriptors.
178//!
179//! \param ui8Value is the Usage Maximum value.
180//!
181//! This macro takes a value and prepares it to be placed as a Usage Maximum
182//! entry into a HID report structure.  This is the last or maximum value
183//! associated with a usage value.
184//!
185//! \return Not a function.
186//
187//*****************************************************************************
188#define UsageMaximum(ui8Value) 0x29, ((ui8Value)&0xff)
189
190//*****************************************************************************
191//
192//! This is a macro to assist adding Logical Minimum entries in HID report
193//! descriptors.
194//!
195//! \param i8Value is the Logical Minimum value.
196//!
197//! This macro takes a value and prepares it to be placed as a Logical Minimum
198//! entry into a HID report structure.  This is the actual minimum value for a
199//! range of values associated with a field.
200//!
201//! \return Not a function.
202//
203//*****************************************************************************
204#define LogicalMinimum(i8Value) 0x15, ((i8Value)&0xff)
205
206//*****************************************************************************
207//
208//! This is a macro to assist adding Logical Maximum entries in HID report
209//! descriptors.
210//!
211//! \param i8Value is the Logical Maximum value.
212//!
213//! This macro takes a value and prepares it to be placed as a Logical Maximum
214//! entry into a HID report structure.  This is the actual maximum value for a
215//! range of values associated with a field.
216//!
217//! \return Not a function.
218//
219//*****************************************************************************
220#define LogicalMaximum(i8Value) 0x25, ((i8Value)&0xff)
221
222//*****************************************************************************
223//
224//! This is a macro to assist adding Physical Minimum entries in HID report
225//! descriptors.
226//!
227//! \param i16Value is the Physical Minimum value.  It is a signed, 16 bit
228//! number.
229//!
230//! This macro takes a value and prepares it to be placed as a Physical Minimum
231//! entry into a HID report structure.  This is value is used in conversion of
232//! the control logical value, as returned to the host in the relevant report,
233//! to a physical measurement in the appropriate units.
234//!
235//! \return Not a function.
236//
237//*****************************************************************************
238#define PhysicalMinimum(i16Value)                                              \
239    0x36, ((i16Value)&0xFF), (((i16Value) >> 8) & 0xFF)
240
241//*****************************************************************************
242//
243//! This is a macro to assist adding Physical Maximum entries in HID report
244//! descriptors.
245//!
246//! \param i16Value is the Physical Maximum value.  It is a signed, 16 bit
247//! number.
248//!
249//! This macro takes a value and prepares it to be placed as a Physical Maximum
250//! entry into a HID report structure.  This is value is used in conversion of
251//! the control logical value, as returned to the host in the relevant report,
252//! to a physical measurement in the appropriate units.
253//!
254//! \return Not a function.
255//
256//*****************************************************************************
257#define PhysicalMaximum(i16Value)                                              \
258    0x46, ((i16Value)&0xFF), (((i16Value) >> 8) & 0xFF)
259
260//*****************************************************************************
261//
262//! This is a macro to assist adding Collection entries in HID report
263//! descriptors.
264//!
265//! \param ui8Value is the type of Collection.
266//!
267//! This macro takes a value and prepares it to be placed as a Collection
268//! entry into a HID report structure.  This is the type of values that are
269//! being grouped together, for instance input, output or features can be
270//! grouped together as a collection.
271//!
272//! \return Not a function.
273//
274//*****************************************************************************
275#define Collection(ui8Value) 0xa1, ((ui8Value)&0xff)
276
277//*****************************************************************************
278//
279//! This is a macro to assist adding End Collection entries in HID report
280//! descriptors.
281//!
282//! This macro can be used to place an End Collection entry into a HID report
283//! structure.  This is a tag to indicate that a collection of entries has
284//! ended in the HID report structure.  This terminates a previous Collection()
285//! entry.
286//!
287//! \return Not a function.
288//
289//*****************************************************************************
290#define EndCollection 0xc0
291
292//*****************************************************************************
293//
294//! This is a macro to assist adding Report Count entries in HID report
295//! descriptors.
296//!
297//! \param ui8Value is the number of items in a report item.
298//!
299//! This macro takes a value and prepares it to be placed as a Report Count
300//! entry into a HID report structure.  This is number of entries of Report
301//! Size for a given item.
302//!
303//! \return Not a function.
304//
305//*****************************************************************************
306#define ReportCount(ui8Value) 0x95, ((ui8Value)&0xff)
307
308//*****************************************************************************
309//
310//! This is a macro to assist adding Report ID entries in HID report
311//! descriptors.
312//!
313//! \param ui8Value is the identifier prefix for the current report.
314//!
315//! This macro takes a value and prepares it to be placed as a Report ID
316//! entry into a HID report structure.  This value is used as a 1 byte prefix
317//! for the report it is contained within.
318//!
319//! \return Not a function.
320//
321//*****************************************************************************
322#define ReportID(ui8Value) 0x85, ((ui8Value)&0xff)
323
324//*****************************************************************************
325//
326//! This is a macro to assist adding Report Size entries in HID report
327//! descriptors.
328//!
329//! \param ui8Value is the size, in bits, of items in a report item.
330//!
331//! This macro takes a value and prepares it to be placed as a Report Size
332//! entry into a HID report structure.  This is size in bits of the entries of
333//! of a report entry.  The Report Count specifies how many entries of Report
334//! Size are in a given item.  These can be individual bits or bit fields.
335//!
336//! \return Not a function.
337//
338//*****************************************************************************
339#define ReportSize(ui8Value) 0x75, ((ui8Value)&0xff)
340
341//*****************************************************************************
342//
343//! This is a macro to assist adding Input entries in HID report descriptors.
344//!
345//! \param ui8Value is bit mask to specify the type of a set of input report
346//! items.  Note that if the USB_HID_INPUT_BITF flag is required, the Input2
347//! macro (which uses a 2 byte version of the Input item tag) must be used
348//! instead of this macro.
349//!
350//! This macro takes a value and prepares it to be placed as an Input entry
351//! into a HID report structure.  This specifies the type of an input item in
352//! a report structure.  These refer to a bit mask of flags that indicate the
353//! type of input for a set of items.
354//!
355//! \return Not a function.
356//
357//*****************************************************************************
358#define Input(ui8Value) 0x81, ((ui8Value)&0xff)
359
360//*****************************************************************************
361//
362//! This is a macro to assist adding Input entries in HID report descriptors.
363//!
364//! \param ui16Value is bit mask to specify the type of a set of input report
365//! items.  Note that this macro uses a version of the Input item tag with a
366//! two byte payload and allows any of the 8 possible data bits for the tag to
367//! be used.  If USB_HID_INPUT_BITF (bit 8) is not required, the Input macro
368//! may be used instead.
369//!
370//! This macro takes a value and prepares it to be placed as an Input entry
371//! into a HID report structure.  This specifies the type of an input item in
372//! a report structure.  These refer to a bit mask of flags that indicate the
373//! type of input for a set of items.
374//!
375//! \return Not a function.
376//
377//*****************************************************************************
378#define Input2(ui16Value) 0x82, ((ui16Value)&0xff), (((ui16Value) >> 8) & 0xFF)
379
380//*****************************************************************************
381//
382//! This is a macro to assist adding Feature entries in HID report descriptors.
383//!
384//! \param ui8Value is bit mask to specify the type of a set of feature report
385//! items.  Note that if the \b USB_HID_FEATURE_BITF flag is required, the
386//! Feature2 macro (which uses a 2 byte version of the Feature item tag) must
387//! be used instead of this macro.
388//!
389//! This macro takes a value and prepares it to be placed as a Feature entry
390//! into a HID report structure.  This specifies the type of a feature item in
391//! a report structure.  These refer to a bit mask of flags that indicate the
392//! type of feature for a set of items.
393//!
394//! \return Not a function.
395//
396//*****************************************************************************
397#define Feature(ui8Value) 0xB1, ((ui8Value)&0xff)
398
399//*****************************************************************************
400//
401//! This is a macro to assist adding Feature entries in HID report descriptors.
402//!
403//! \param ui16Value is bit mask to specify the type of a set of feature report
404//! items.  Note that this macro uses a version of the Feature item tag with a
405//! two byte payload and allows any of the 8 possible data bits for the tag to
406//! be used.  If \b USB_HID_FEATURE_BITF (bit 8) is not required, the Feature
407//! macro may be used instead.
408//!
409//! This macro takes a value and prepares it to be placed as a Feature entry
410//! into a HID report structure.  This specifies the type of a feature item in
411//! a report structure.  These refer to a bit mask of flags that indicate the
412//! type of feature for a set of items.
413//!
414//! \return Not a function.
415//
416//*****************************************************************************
417#define Feature2(ui16Value)                                                    \
418    0xB2, ((ui16Value)&0xff), (((ui16Value) >> 8) & 0xFF)
419
420//*****************************************************************************
421//
422//! This is a macro to assist adding Output entries in HID report descriptors.
423//!
424//! \param ui8Value is bit mask to specify the type of a set of output report
425//! items.  Note that if the \b USB_HID_OUTPUT_BITF flag is required, the
426//! Output2 macro (which uses a 2 byte version of the Output item tag) must be
427//! used instead of this macro.
428//!
429//! This macro takes a value and prepares it to be placed as an Output entry
430//! into a HID report structure.  This specifies the type of an output item in
431//! a report structure.  These refer to a bit mask of flags that indicate the
432//! type of output for a set of items.
433//!
434//! \return Not a function.
435//
436//*****************************************************************************
437#define Output(ui8Value) 0x91, ((ui8Value)&0xff)
438
439//*****************************************************************************
440//
441//! This is a macro to assist adding Output entries in HID report descriptors.
442//!
443//! \param ui16Value is bit mask to specify the type of a set of output report
444//! items.  Note that this macro uses a version of the Output item tag with a
445//! two byte payload and allows any of the 8 possible data bits for the tag to
446//! be used.  If \b USB_HID_OUTPUT_BITF is not required, the Output macro
447//! may be used instead.
448//!
449//! This macro takes a value and prepares it to be placed as an Output entry
450//! into a HID report structure.  This specifies the type of an output item in
451//! a report structure.  These refer to a bit mask of flags that indicate the
452//! type of output for a set of items.
453//!
454//! \return Not a function.
455//
456//*****************************************************************************
457#define Output2(ui16Value) 0x92, ((ui16Value)&0xff), (((ui16Value) >> 8) & 0xFF)
458
459//*****************************************************************************
460//
461//! This is a macro to assist adding Unit Exponent entries in HID report
462//! descriptors.
463//!
464//! \param i8Value is the required exponent in the range [-8, 7].
465//!
466//! This macro takes a value and prepares it to be placed as a Unit Exponent
467//! entry into a HID report structure.  This is the exponent applied to
468//! PhysicalMinimum and PhysicalMaximum when scaling and converting control
469//! values to "real" units.
470//!
471//! \return Not a function.
472//
473//*****************************************************************************
474#define UnitExponent(i8Value) 0x55, ((i8Value)&0x0f)
475
476//*****************************************************************************
477//
478//! This is a macro to assist adding Unit entries for uncommon units in HID
479//! report descriptors.
480//!
481//! \param ui32Value is the definition of the unit required as defined in
482//! section 6.2.2.7 of the USB HID device class definition document.
483//!
484//! This macro takes a value and prepares it to be placed as a Unit entry into
485//! a HID report structure.  Note that individual macros are defined for common
486//! units and this macro is intended for use when a complex or uncommon unit
487//! is needed.  It allows entry of a 5 nibble unit definition into the report
488//! descriptor.
489//!
490//! \return Not a function.
491//
492//*****************************************************************************
493#define Unit(ui32Value)         0x67, (ui32Value) & 0x0f),                    \
494                                (((ui32Value) >> 8) & 0xFF),                  \
495                                (((ui32Value) >> 16) & 0xFF),                 \
496                                (((ui32Value) >> 24) & 0xFF)
497
498//*****************************************************************************
499//
500//! This macro inserts a Unit entry for centimeters into a report descriptor.
501//!
502//*****************************************************************************
503#define UnitDistance_cm 0x66, 0x11, 0x00
504
505//*****************************************************************************
506//
507//! This macro inserts a Unit entry for inches into a report descriptor.
508//!
509//*****************************************************************************
510#define UnitDistance_i 0x66, 0x13, 0x00
511
512//*****************************************************************************
513//
514//! This macro inserts a Unit entry for degrees into a report descriptor.
515//!
516//*****************************************************************************
517#define UnitRotation_deg 0x66, 0x14, 0x00
518
519//*****************************************************************************
520//
521//! This macro inserts a Unit entry for radians into a report descriptor.
522//!
523//*****************************************************************************
524#define UnitRotation_rad 0x66, 0x12, 0x00
525
526//*****************************************************************************
527//
528//! This macro inserts a Unit entry for grams into a report descriptor.
529//!
530//*****************************************************************************
531#define UnitMass_g 0x66, 0x01, 0x01
532
533//*****************************************************************************
534//
535//! This macro inserts a Unit entry for seconds into a report descriptor.
536//!
537//*****************************************************************************
538#define UnitTime_s 0x66, 0x01, 0x10
539
540//*****************************************************************************
541//
542//! This macro inserts a Unit entry for temperature in Kelvin into a report
543//! descriptor.
544//!
545//*****************************************************************************
546#define UnitTemp_K 0x67, 0x01, 0x00, 0x01, 0x00
547
548//*****************************************************************************
549//
550//! This macro inserts a Unit entry for temperature in Fahrenheit into a report
551//! descriptor.
552//!
553//*****************************************************************************
554#define UnitTemp_F 0x67, 0x03, 0x00, 0x01, 0x00
555
556//*****************************************************************************
557//
558//! This macro inserts a Unit entry for velocity in cm/s into a report
559//! descriptor.
560//!
561//*****************************************************************************
562#define UnitVelocitySI 0x66, 0x11, 0xF0
563
564//*****************************************************************************
565//
566//! This macro inserts a Unit entry for momentum in (grams * cm)/s into a
567//! report descriptor.
568//!
569//*****************************************************************************
570#define UnitMomentumSI 0x66, 0x11, 0xF1
571
572//*****************************************************************************
573//
574//! This macro inserts a Unit entry for acceleration in cm/s**2 into a
575//! report descriptor.
576//!
577//*****************************************************************************
578#define UnitAccelerationSI 0x66, 0x11, 0xE0
579
580//*****************************************************************************
581//
582//! This macro inserts a Unit entry for force in (cm * grams)/s**2 into a
583//! report descriptor.
584//!
585//*****************************************************************************
586#define UnitForceSI 0x66, 0x11, 0xE1
587
588//*****************************************************************************
589//
590//! This macro inserts a Unit entry for energy in (grams * cm^2)/(s^2) into a
591//! report descriptor.
592//!
593//*****************************************************************************
594#define UnitEnergySI 0x66, 0x21, 0xE1
595
596//*****************************************************************************
597//
598//! This macro inserts a Unit entry for angular acceleration in degrees/(s^2)
599//! into a report descriptor.
600//!
601//*****************************************************************************
602#define UnitAngAccelerationSI 0x66, 0x12, 0xE0
603
604//*****************************************************************************
605//
606//! This macro inserts a Unit entry for voltage into a a report descriptor.
607//!
608//*****************************************************************************
609#define UnitVoltage 0x67, 0x21, 0xD1, 0xF0, 0x00
610
611//*****************************************************************************
612//
613//! This macro inserts a Unit entry for voltage into a a report descriptor.
614//!
615//*****************************************************************************
616#define UnitCurrent_A 0x67, 0x01, 0x00, 0x10, 0x00
617
618//*****************************************************************************
619//
620// PRIVATE
621//
622// The first few sections of this header are private defines that are used by
623// the USB HID code and are here only to help with the application
624// allocating the correct amount of memory for the HID device code.
625//
626//*****************************************************************************
627#define USBDHID_MAX_PACKET 64
628
629//*****************************************************************************
630//
631// PRIVATE
632//
633// This enumeration holds the various states that the device can be in during
634// normal operation.
635//
636//*****************************************************************************
637typedef enum {
638    //
639    // Unconfigured.
640    //
641    eHIDStateUnconfigured,
642
643    //
644    // No outstanding transaction remains to be completed.
645    //
646    eHIDStateIdle,
647
648    //
649    // Waiting on completion of a send or receive transaction.
650    //
651    eHIDStateWaitData
652} tHIDState;
653
654//*****************************************************************************
655//
656// PRIVATE
657//
658// This structure defines the private instance data and state variables for
659// HID devices.  The memory for this structure is included in the
660// sPrivateData field in the tUSBDHIDDevice structure passed in the
661// USBDHIDInit() function.
662//
663//*****************************************************************************
664typedef struct {
665    //
666    // Base address for the USB controller.
667    //
668    uint32_t ui32USBBase;
669
670    //
671    // The device info to interact with the lower level DCD code.
672    //
673    tDeviceInfo sDevInfo;
674
675    //
676    // The state of the HID receive channel.
677    //
678    volatile tHIDState iHIDRxState;
679
680    //
681    // The state of the HID transmit channel.
682    //
683    volatile tHIDState iHIDTxState;
684
685    //
686    // State of any pending operations that could not be handled immediately
687    // upon receipt.
688    //
689    volatile uint16_t ui16DeferredOpFlags;
690
691    //
692    // Size of the HID IN report.
693    //
694    uint16_t ui16InReportSize;
695
696    //
697    // .
698    //
699    uint16_t ui16InReportIndex;
700
701    //
702    // Size of the HID OUT report.
703    //
704    uint16_t ui16OutReportSize;
705
706    //
707    // Pointer to the current HID IN report data.
708    //
709    uint8_t* pui8InReportData;
710
711    //
712    // Pointer to the current HID OUT report data.
713    //
714    uint8_t* pui8OutReportData;
715
716    //
717    // The connection status of the device.
718    //
719    volatile bool bConnected;
720
721    //
722    // Whether an IN transaction is in process.
723    //
724    volatile bool bSendInProgress;
725
726    //
727    // An HID request transaction is in process(Endpoint 0).
728    //
729    bool bGetRequestPending;
730
731    //
732    // The IN endpoint number, this is modified in composite devices.
733    //
734    uint8_t ui8INEndpoint;
735
736    //
737    // The OUT endpoint number, this is modified in composite devices.
738    //
739    uint8_t ui8OUTEndpoint;
740
741    //
742    // The bulk class interface number, this is modified in composite devices.
743    //
744    uint8_t ui8Interface;
745} tHIDInstance;
746
747//*****************************************************************************
748//
749//! The structure used to track idle time for reports.  An array of these
750//! structures is passed to the HID device class driver during USBDHIDInit and
751//! is used to track automatic resending of each report (if not disabled by
752//! the host).
753//
754//*****************************************************************************
755typedef struct {
756    //
757    //! The idle duration for the report expressed in units of 4mS.  0
758    //! indicates infinite and informs the class driver not to send the report
759    //! unless a state change occurs.
760    //
761    uint8_t ui8Duration4mS;
762
763    //
764    //! The ID of the report which this structure applies to.  This is the
765    //! report ID as specified using a ReportID tag in the report descriptor
766    //! rather than the index of the report in the HID class descriptor array.
767    //! If only a single Input report is supported and, thus, no ReportID tag
768    //! is present, this field should be set to 0.
769    //
770    uint8_t ui8ReportID;
771
772    //
773    //! The number of milliseconds before we need to send a copy of a given
774    //! report back to the host.  This field is updated by the HID driver and
775    //! used to time sending of \b USBD_HID_EVENT_IDLE_TIMEOUT.
776    //
777    uint16_t ui16TimeTillNextmS;
778
779    //
780    //! The number of milliseconds that have passed since the last time this
781    //! report was sent.  The HID class driver needs to track this since
782    //! Set_Idle requests are required to take effect as if issued immediately
783    //! after the last transmission of the report to which they refer.
784    //
785    uint32_t ui32TimeSinceReportmS;
786} tHIDReportIdle;
787
788//*****************************************************************************
789//
790//! The structure used by the application to define operating parameters for
791//! the HID device.
792//
793//*****************************************************************************
794typedef struct {
795    //
796    //! The vendor ID that this device is to present in the device descriptor.
797    //
798    uint16_t ui16VID;
799
800    //
801    //! The product ID that this device is to present in the device descriptor.
802    //
803    uint16_t ui16PID;
804
805    //
806    //! The maximum power consumption of the device, expressed in milliamps.
807    //
808    uint16_t ui16MaxPowermA;
809
810    //
811    //! Indicates whether the device is self- or bus-powered and whether or not
812    //! it supports remote wakeup.  Valid values are \b USB_CONF_ATTR_SELF_PWR
813    //! or \b USB_CONF_ATTR_BUS_PWR, optionally ORed with
814    //! \b USB_CONF_ATTR_RWAKE.
815    //
816    uint8_t ui8PwrAttributes;
817
818    //
819    //! The interface subclass to publish to the server for this HID device.
820    //
821    uint8_t ui8Subclass;
822
823    //
824    //! The interface protocol to publish to the server for this HID device.
825    //
826    uint8_t ui8Protocol;
827
828    //
829    //! The number of Input reports that this device supports.  This field
830    //! must equal the number of reports published in the HID class descriptors
831    //! for the device and also the number of entries in the array whose first
832    //! element is pointed to by field \e pi16ReportIdle below.
833    //
834    uint8_t ui8NumInputReports;
835
836    //
837    //! A pointer to the first element in an array of structures used to track
838    //! idle time for each Input report.  When USBDHIDInit() is called, the
839    //! ui8Duration4mS and ui8ReportID fields of each of these array members
840    //! should be initialized to indicate the default idle timeout for each
841    //! input report.  This array must be in RAM since the HID device class
842    //! driver updates values in it in response to requests from the host
843    //! and to track elapsed time.  The number of elements in the array must
844    //! match the number supplied in the ui8NumInputReports field above.
845    //
846    tHIDReportIdle* psReportIdle;
847
848    //! A pointer to the callback function which is called to notify
849    //! the application of general events, events related to report transfers
850    //! on endpoint zero and events related to reception of Output and Feature
851    //! reports via the (optional) interrupt OUT endpoint.
852    //
853    tUSBCallback pfnRxCallback;
854
855    //
856    //! A client-supplied pointer which is sent as the first
857    //! parameter in all calls made to the receive channel callback,
858    //! pfnRxCallback.
859    //
860    void* pvRxCBData;
861
862    //
863    //! A pointer to the callback function which is called to notify
864    //! the application of events related to transmission of Input reports
865    //! via the interrupt IN endpoint.
866    //
867    tUSBCallback pfnTxCallback;
868
869    //
870    //! A client-supplied pointer which is sent as the first
871    //! parameter in all calls made to the transmit channel callback,
872    //! pfnTxCallback.
873    //
874    void* pvTxCBData;
875
876    //
877    //! If set to true, this field indicates that the device should use a
878    //! dedicated interrupt OUT endpoint to receive reports from the host.  In
879    //! this case, reports from the host are passed to the application via the
880    //! receive callback using \b USB_EVENT_RX_AVAILABLE events.  If false,
881    //! reports from the host are received via endpoint zero and passed to the
882    //! application via \b USBD_HID_EVENT_REPORT_SENT events.
883    //
884    bool bUseOutEndpoint;
885
886    //
887    //! The HID descriptor that the device is to publish (following the
888    //! standard interface descriptor and prior to the endpoint descriptors for
889    //! the interface).
890    //
891    const tHIDDescriptor* psHIDDescriptor;
892
893    //
894    //! The HID class descriptors offered by the device are defined in an
895    //! array of byte pointers and this field points to that array.  The
896    //! order and number of elements in the array must match the associated
897    //! information provided in the HID descriptor in field by
898    //! \e pi16HIDDescriptor.
899    //
900    const uint8_t* const* ppui8ClassDescriptors;
901
902    //
903    //! A pointer to the string descriptor array for this device.  This array
904    //! must contain the following string descriptor pointers in this order.
905    //! Language descriptor, Manufacturer name string (language 1), Product
906    //! name string (language 1), Serial number string (language 1),HID
907    //! Interface description string (language 1), Configuration description
908    //! string (language 1), (optionally) First HID device-specific string
909    //! (language 1), (optionally) Second HID device-specific string (language
910    //! 1), etc.
911    //!
912    //! If supporting more than 1 language, the descriptor block (except for
913    //! string descriptor 0) must be repeated for each language defined in the
914    //! language descriptor.
915    //!
916    //! The number of HID device-specific strings is dependent upon the content
917    //! of the report descriptor passed to the interface and is, thus,
918    //! application controlled.
919    //
920    const uint8_t* const* ppui8StringDescriptors;
921
922    //
923    //! The number of descriptors provided in the \e ppStringDescriptors
924    //! array.  This must be 1 + ((5 + (num HID strings)) * (num languages)).
925    //
926    uint32_t ui32NumStringDescriptors;
927
928    //
929    // ! The configuration descriptor for this HID device.
930    //
931    const tConfigHeader* const* ppsConfigDescriptor;
932
933    //
934    //! The private instance data for this device instance.  This
935    //! memory must remain accessible for as long as the HID device is in
936    //! use and must not be modified by any code outside the HID class driver.
937    //
938    tHIDInstance sPrivateData;
939} tUSBDHIDDevice;
940
941//*****************************************************************************
942//
943// HID-specific device class driver events
944//
945//*****************************************************************************
946
947//*****************************************************************************
948//
949//! This event indicates that the host is requesting a particular report be
950//! returned via endpoint 0, the control endpoint.  The ui32MsgValue parameter
951//! contains the requested report type in the high byte and report ID in the
952//! low byte (as passed in the wValue field of the USB request structure).
953//! The pvMsgData parameter contains a pointer which must be written with the
954//! address of the first byte of the requested report.  The callback must
955//! return the size in bytes of the report pointed to by *pvMsgData.  The
956//! memory returned in response to this event must remain unaltered until
957//! \b USBD_HID_EVENT_REPORT_SENT is sent.
958//
959//*****************************************************************************
960#define USBD_HID_EVENT_GET_REPORT (USBD_HID_EVENT_BASE + 0)
961
962//*****************************************************************************
963//
964//! This event indicates that a report previously requested via a
965//! \b USBD_HID_EVENT_GET_REPORT has been successfully transmitted to the host.
966//! The application may now free or reuse the report memory passed on the
967//! previous event.  Although this would seem to be an event that would be
968//! passed to the transmit channel callback, it is actually passed to the
969//! receive channel callback.  This ensures that all events related to the
970//! request and transmission of reports via endpoint zero can be handled in
971//! a single function.
972//
973//*****************************************************************************
974#define USBD_HID_EVENT_REPORT_SENT (USBD_HID_EVENT_BASE + 1)
975
976//*****************************************************************************
977//
978//! This event indicates that the host has sent a Set_Report request to
979//! the device and requests that the device provide a buffer into which the
980//! report can be written.  The ui32MsgValue parameter contains the received
981//! report type in the high byte and report ID in the low byte (as passed in
982//! the wValue field of the USB request structure).  The pvMsgData parameter
983//! contains the length of buffer requested.  Note that this is the actual
984//! length value cast to a "void *" type and not a pointer in this case.
985//! The callback must return a pointer to a suitable buffer (cast to the
986//! standard "uint32_t" return type for the callback).
987//
988//*****************************************************************************
989#define USBD_HID_EVENT_GET_REPORT_BUFFER (USBD_HID_EVENT_BASE + 2)
990
991//*****************************************************************************
992//
993//! This event indicates that the host has sent the device a report via
994//! endpoint 0, the control endpoint.  The ui32MsgValue field indicates the
995//! size of the report and pvMsgData points to the first byte of the report.
996//! The report buffer was previously returned in response to an
997//! earlier \b USBD_HID_EVENT_GET_REPORT_BUFFER callback.  The HID device class
998//! driver does not access the memory pointed to by pvMsgData after this
999//! callback is made so the application is free to reuse or free it at this
1000//! point.
1001//
1002//*****************************************************************************
1003#define USBD_HID_EVENT_SET_REPORT (USBD_HID_EVENT_BASE + 3)
1004
1005//*****************************************************************************
1006//
1007//! This event is sent in response to a Get_Protocol request from the host.
1008//! The callback should provide the current protocol via the return code,
1009//! \b USB_HID_PROTOCOL_BOOT or \b USB_HID_PROTOCOL_REPORT.
1010//
1011//*****************************************************************************
1012#define USBD_HID_EVENT_GET_PROTOCOL (USBD_HID_EVENT_BASE + 4)
1013
1014//*****************************************************************************
1015//
1016//! This event is sent in response to a Set_Protocol request from the host.
1017//! The ui32MsgData value contains the requested protocol,
1018//! \b USB_HID_PROTOCOL_BOOT or \b USB_HID_PROTOCOL_REPORT.
1019//
1020//*****************************************************************************
1021#define USBD_HID_EVENT_SET_PROTOCOL (USBD_HID_EVENT_BASE + 5)
1022
1023//*****************************************************************************
1024//
1025//! This event indicates to an application that a report idle timeout has
1026//! occurred and requests a pointer to the report that must be sent back to
1027//! the host.  The ui32MsgData value contains the requested report ID and
1028//! pvMsgData contains a pointer that must be written with a pointer to the
1029//! report data that is to be sent.  The callback must return the number of
1030//! bytes in the report pointed to by *pvMsgData.
1031//
1032//*****************************************************************************
1033#define USBD_HID_EVENT_IDLE_TIMEOUT (USBD_HID_EVENT_BASE + 6)
1034
1035//*****************************************************************************
1036//
1037// API Function Prototypes
1038//
1039//*****************************************************************************
1040extern void* USBDHIDInit(uint32_t ui32Index, tUSBDHIDDevice* psHIDDevice);
1041extern void* USBDHIDCompositeInit(uint32_t ui32Index, tUSBDHIDDevice* psDevice,
1042                                  tCompositeEntry* psCompEntry);
1043extern void USBDHIDTerm(void* pvHIDInstance);
1044extern void* USBDHIDSetRxCBData(void* pvHIDInstance, void* pvCBData);
1045extern void* USBDHIDSetTxCBData(void* pvHIDInstance, void* pvCBData);
1046extern uint32_t USBDHIDReportWrite(void* pvHIDInstance, uint8_t* pi8Data,
1047                                   uint32_t ui32Length, bool bLast);
1048extern uint32_t USBDHIDPacketRead(void* pvHIDInstance, uint8_t* pi8Data,
1049                                  uint32_t ui32Length, bool bLast);
1050extern uint32_t USBDHIDTxPacketAvailable(void* pvHIDInstance);
1051extern uint32_t USBDHIDRxPacketAvailable(void* pvHIDInstance);
1052extern bool USBDHIDRemoteWakeupRequest(void* pvHIDInstance);
1053
1054//*****************************************************************************
1055//
1056// Close the Doxygen group.
1057//! @}
1058//
1059//*****************************************************************************
1060
1061//*****************************************************************************
1062//
1063// The following APIs are deprecated.
1064//
1065//*****************************************************************************
1066#ifndef DEPRECATED
1067
1068//
1069// Use USBDCDFeatureSet() or USBHCDFeatureSet() with \b USBLIB_FEATURE_POWER
1070// configuration option.
1071//
1072extern void USBDHIDPowerStatusSet(void* pvHIDInstance, uint8_t ui8Power);
1073#endif
1074
1075//*****************************************************************************
1076//
1077// Mark the end of the C bindings section for C++ compilers.
1078//
1079//*****************************************************************************
1080#ifdef __cplusplus
1081}
1082#endif
1083
1084#endif // __USBDHID_H__