+/rtos
git clone https://git.julia.blue/+/rtos
326af29
master
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// 641eHIDStateUnconfigured , 642 643// 644// No outstanding transaction remains to be completed. 645// 646eHIDStateIdle , 647 648// 649// Waiting on completion of a send or receive transaction. 650// 651eHIDStateWaitData 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// 668uint32_t ui32USBBase ; 669 670// 671// The device info to interact with the lower level DCD code. 672// 673tDeviceInfo sDevInfo ; 674 675// 676// The state of the HID receive channel. 677// 678volatile tHIDState iHIDRxState ; 679 680// 681// The state of the HID transmit channel. 682// 683volatile tHIDState iHIDTxState ; 684 685// 686// State of any pending operations that could not be handled immediately 687// upon receipt. 688// 689volatile uint16_t ui16DeferredOpFlags ; 690 691// 692// Size of the HID IN report. 693// 694uint16_t ui16InReportSize ; 695 696// 697// . 698// 699uint16_t ui16InReportIndex ; 700 701// 702// Size of the HID OUT report. 703// 704uint16_t ui16OutReportSize ; 705 706// 707// Pointer to the current HID IN report data. 708// 709uint8_t * pui8InReportData ; 710 711// 712// Pointer to the current HID OUT report data. 713// 714uint8_t * pui8OutReportData ; 715 716// 717// The connection status of the device. 718// 719volatile bool bConnected ; 720 721// 722// Whether an IN transaction is in process. 723// 724volatile bool bSendInProgress ; 725 726// 727// An HID request transaction is in process(Endpoint 0). 728// 729bool bGetRequestPending ; 730 731// 732// The IN endpoint number, this is modified in composite devices. 733// 734uint8_t ui8INEndpoint ; 735 736// 737// The OUT endpoint number, this is modified in composite devices. 738// 739uint8_t ui8OUTEndpoint ; 740 741// 742// The bulk class interface number, this is modified in composite devices. 743// 744uint8_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// 761uint8_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// 770uint8_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// 777uint16_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// 785uint32_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// 798uint16_t ui16VID ; 799 800// 801//! The product ID that this device is to present in the device descriptor. 802// 803uint16_t ui16PID ; 804 805// 806//! The maximum power consumption of the device, expressed in milliamps. 807// 808uint16_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// 816uint8_t ui8PwrAttributes ; 817 818// 819//! The interface subclass to publish to the server for this HID device. 820// 821uint8_t ui8Subclass ; 822 823// 824//! The interface protocol to publish to the server for this HID device. 825// 826uint8_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// 834uint8_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// 846tHIDReportIdle * 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// 853tUSBCallback 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// 860void * 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// 867tUSBCallback 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// 874void * 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// 884bool 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// 891const 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// 900const 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// 920const 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// 926uint32_t ui32NumStringDescriptors ; 927 928// 929// ! The configuration descriptor for this HID device. 930// 931const 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// 938tHIDInstance 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 , 1042tCompositeEntry * 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 , 1047uint32_t ui32Length ,bool bLast ); 1048extern uint32_t USBDHIDPacketRead (void * pvHIDInstance ,uint8_t * pi8Data , 1049uint32_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__