+/rtos

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

Joseph RyanRe-add usblib files83915e3

master
32.2 KiB930 linesraw
1//*****************************************************************************
2//
3// usbdhidmouse.c - USB HID Mouse device class driver.
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#include "usblib/device/usbdhidmouse.h"
26#include "tivaware/hw_types.h"
27#include "tivaware/usb.h"
28#include "usblib/device/usbdevice.h"
29#include "usblib/device/usbdhid.h"
30#include "usblib/usbhid.h"
31#include "usblib/usblib.h"
32#include "usblib/usblibpriv.h"
33#include <stdbool.h>
34#include <stdint.h>
35
36#define ASSERT(X)
37
38//*****************************************************************************
39//
40//! \addtogroup hid_mouse_device_class_api
41//! @{
42//
43//*****************************************************************************
44
45//*****************************************************************************
46//
47// HID device configuration descriptor.
48//
49// It is vital that the configuration descriptor bConfigurationValue field
50// (byte 6) is 1 for the first configuration and increments by 1 for each
51// additional configuration defined here.  This relationship is assumed in the
52// device stack for simplicity even though the USB 2.0 specification imposes
53// no such restriction on the bConfigurationValue values.
54//
55// Note that this structure is deliberately located in RAM since we need to
56// be able to patch some values in it based on client requirements.
57//
58//*****************************************************************************
59uint8_t g_pui8MouseDescriptor[] = {
60    //
61    // Configuration descriptor header.
62    //
63    9,                       // Size of the configuration descriptor.
64    USB_DTYPE_CONFIGURATION, // Type of this descriptor.
65    USBShort(34),            // The total size of this full structure.
66    1,                       // The number of interfaces in this
67                             // configuration.
68    1,                       // The unique value for this configuration.
69    5,                       // The string identifier that describes this
70                             // configuration.
71    USB_CONF_ATTR_SELF_PWR,  // Bus Powered, Self Powered, remote wake up.
72    250,                     // The maximum power in 2mA increments.
73};
74
75//*****************************************************************************
76//
77// The remainder of the configuration descriptor is stored in flash since we
78// don't need to modify anything in it at runtime.
79//
80//*****************************************************************************
81uint8_t g_pui8HIDInterface[HIDINTERFACE_SIZE] = {
82    //
83    // HID Device Class Interface Descriptor.
84    //
85    9,                      // Size of the interface descriptor.
86    USB_DTYPE_INTERFACE,    // Type of this descriptor.
87    0,                      // The index for this interface.
88    0,                      // The alternate setting for this interface.
89    1,                      // The number of endpoints used by this
90                            // interface.
91    USB_CLASS_HID,          // The interface class
92    USB_HID_SCLASS_BOOT,    // The interface sub-class.
93    USB_HID_PROTOCOL_MOUSE, // The interface protocol for the sub-class
94                            // specified above.
95    4,                      // The string index for this interface.
96};
97
98const uint8_t g_pui8HIDInEndpoint[HIDINENDPOINT_SIZE] = {
99    //
100    // Interrupt IN endpoint descriptor
101    //
102    7,                  // The size of the endpoint descriptor.
103    USB_DTYPE_ENDPOINT, // Descriptor type is an endpoint.
104    USB_EP_DESC_IN | USBEPToIndex(USB_EP_1),
105    USB_EP_ATTR_INT, // Endpoint is an interrupt endpoint.
106    USBShort(USBFIFOSizeToBytes(USB_FIFO_SZ_64)),
107    // The maximum packet size.
108    16, // The polling interval for this endpoint.
109};
110
111//*****************************************************************************
112//
113// The report descriptor for the mouse class device.
114//
115//*****************************************************************************
116static const uint8_t g_pui8MouseReportDescriptor[] = {
117    UsagePage(USB_HID_GENERIC_DESKTOP),
118    Usage(USB_HID_MOUSE),
119    Collection(USB_HID_APPLICATION),
120    Usage(USB_HID_POINTER),
121    Collection(USB_HID_PHYSICAL),
122
123    //
124    // The buttons.
125    //
126    UsagePage(USB_HID_BUTTONS),
127    UsageMinimum(1),
128    UsageMaximum(3),
129    LogicalMinimum(0),
130    LogicalMaximum(1),
131
132    //
133    // 3 - 1 bit values for the buttons.
134    //
135    ReportSize(1),
136    ReportCount(3),
137    Input(USB_HID_INPUT_DATA | USB_HID_INPUT_VARIABLE | USB_HID_INPUT_ABS),
138
139    //
140    // 1 - 5 bit unused constant value to fill the 8 bits.
141    //
142    ReportSize(5),
143    ReportCount(1),
144    Input(USB_HID_INPUT_CONSTANT | USB_HID_INPUT_ARRAY | USB_HID_INPUT_ABS),
145
146    //
147    // The X and Y axis.
148    //
149    UsagePage(USB_HID_GENERIC_DESKTOP),
150    Usage(USB_HID_X),
151    Usage(USB_HID_Y),
152    LogicalMinimum(-127),
153    LogicalMaximum(127),
154
155    //
156    // 2 - 8 bit Values for x and y.
157    //
158    ReportSize(8),
159    ReportCount(2),
160    Input(USB_HID_INPUT_DATA | USB_HID_INPUT_VARIABLE | USB_HID_INPUT_RELATIVE),
161
162    EndCollection,
163    EndCollection,
164};
165
166//*****************************************************************************
167//
168// The HID descriptor for the mouse device.
169//
170//*****************************************************************************
171static const tHIDDescriptor g_sMouseHIDDescriptor = {
172    9,                 // bLength
173    USB_HID_DTYPE_HID, // bDescriptorType
174    0x111,             // bcdHID (version 1.11 compliant)
175    0,                 // bCountryCode (not localized)
176    1,                 // bNumDescriptors
177    {{
178        USB_HID_DTYPE_REPORT, // Report descriptor
179        sizeof(g_pui8MouseReportDescriptor)
180        // Size of report descriptor
181    }}};
182
183//*****************************************************************************
184//
185// The HID configuration descriptor is defined as four or five sections
186// depending upon the client's configuration choice.  These sections are:
187//
188// 1.  The 9 byte configuration descriptor (RAM).
189// 2.  The interface descriptor (RAM).
190// 3.  The HID report and physical descriptors (provided by the client)
191//     (FLASH).
192// 4.  The mandatory interrupt IN endpoint descriptor (FLASH).
193// 5.  The optional interrupt OUT endpoint descriptor (FLASH).
194//
195//*****************************************************************************
196const tConfigSection g_sHIDConfigSection = {sizeof(g_pui8MouseDescriptor),
197                                            g_pui8MouseDescriptor};
198
199const tConfigSection g_sHIDInterfaceSection = {sizeof(g_pui8HIDInterface),
200                                               g_pui8HIDInterface};
201
202const tConfigSection g_sHIDInEndpointSection = {sizeof(g_pui8HIDInEndpoint),
203                                                g_pui8HIDInEndpoint};
204
205//*****************************************************************************
206//
207// Place holder for the user's HID descriptor block.
208//
209//*****************************************************************************
210tConfigSection g_sHIDDescriptorSection = {
211    sizeof(g_sMouseHIDDescriptor), (const uint8_t*)&g_sMouseHIDDescriptor};
212
213//*****************************************************************************
214//
215// This array lists all the sections that must be concatenated to make a
216// single, complete HID configuration descriptor.
217//
218//*****************************************************************************
219const tConfigSection* g_psHIDSections[] = {
220    &g_sHIDConfigSection,
221    &g_sHIDInterfaceSection,
222    &g_sHIDDescriptorSection,
223    &g_sHIDInEndpointSection,
224};
225
226#define NUM_HID_SECTIONS (sizeof(g_psHIDSections) / sizeof(g_psHIDSections[0]))
227
228//*****************************************************************************
229//
230// The header for the single configuration we support.  This is the root of
231// the data structure that defines all the bits and pieces that are pulled
232// together to generate the configuration descriptor.  Note that this must be
233// in RAM since we need to include or exclude the final section based on
234// client supplied initialization parameters.
235//
236//*****************************************************************************
237tConfigHeader g_sHIDConfigHeader = {NUM_HID_SECTIONS, g_psHIDSections};
238
239//*****************************************************************************
240//
241// Configuration Descriptor.
242//
243//*****************************************************************************
244const tConfigHeader* const g_ppsHIDConfigDescriptors[] = {&g_sHIDConfigHeader};
245
246//*****************************************************************************
247//
248// The HID class descriptor table.  For the mouse class, we have only a single
249// report descriptor.
250//
251//*****************************************************************************
252static const uint8_t* const g_pui8MouseClassDescriptors[] = {
253    g_pui8MouseReportDescriptor};
254
255//*****************************************************************************
256//
257// Forward references for mouse device callback functions.
258//
259//*****************************************************************************
260static uint32_t HIDMouseRxHandler(void* pvMouseDevice, uint32_t ui32Event,
261                                  uint32_t ui32MsgData, void* pvMsgData);
262static uint32_t HIDMouseTxHandler(void* pvMouseDevice, uint32_t ui32Event,
263                                  uint32_t ui32MsgData, void* pvMsgData);
264
265//*****************************************************************************
266//
267// The HID mouse report offsets for this mouse application.
268//
269//*****************************************************************************
270#define HID_REPORT_BUTTONS 0
271#define HID_REPORT_X 1
272#define HID_REPORT_Y 2
273
274//*****************************************************************************
275//
276// Main HID device class event handler function.
277//
278// \param pvMouseDevice is the event callback pointer provided during
279// USBDHIDInit().  This is a pointer to our HID device structure
280// (&g_sHIDMouseDevice).
281// \param ui32Event identifies the event we are being called back for.
282// \param ui32MsgData is an event-specific value.
283// \param pvMsgData is an event-specific pointer.
284//
285// This function is called by the HID device class driver to inform the
286// application of particular asynchronous events related to operation of the
287// mouse HID device.
288//
289// \return Returns a value which is event-specific.
290//
291//*****************************************************************************
292static uint32_t HIDMouseRxHandler(void* pvMouseDevice, uint32_t ui32Event,
293                                  uint32_t ui32MsgData, void* pvMsgData) {
294    tHIDMouseInstance* psInst;
295    tUSBDHIDMouseDevice* psMouseDevice;
296
297    //
298    // Make sure we did not get a NULL pointer.
299    //
300    ASSERT(pvMouseDevice);
301
302    //
303    // Get a pointer to our instance data
304    //
305    psMouseDevice = (tUSBDHIDMouseDevice*)pvMouseDevice;
306    psInst = &psMouseDevice->sPrivateData;
307
308    //
309    // Which event were we sent?
310    //
311    switch (ui32Event) {
312    //
313    // The host has connected to us and configured the device.
314    //
315    case USB_EVENT_CONNECTED: {
316        psInst->ui8USBConfigured = true;
317
318        //
319        // Pass the information on to the client.
320        //
321        psMouseDevice->pfnCallback(psMouseDevice->pvCBData, USB_EVENT_CONNECTED,
322                                   0, (void*)0);
323
324        break;
325    }
326
327    //
328    // The host has disconnected from us.
329    //
330    case USB_EVENT_DISCONNECTED: {
331        psInst->ui8USBConfigured = false;
332
333        //
334        // Pass the information on to the client.
335        //
336        psMouseDevice->pfnCallback(psMouseDevice->pvCBData,
337                                   USB_EVENT_DISCONNECTED, 0, (void*)0);
338
339        break;
340    }
341
342    //
343    // The host is polling us for a particular report and the HID driver
344    // is asking for the latest version to transmit.
345    //
346    case USBD_HID_EVENT_IDLE_TIMEOUT:
347    case USBD_HID_EVENT_GET_REPORT: {
348        //
349        // We only support a single input report so we don't need to check
350        // the ui32MsgValue parameter in this case.  Set the report pointer
351        // in *pvMsgData and return the length of the report in bytes.
352        //
353        *(uint8_t**)pvMsgData = psInst->pui8Report;
354        return (8);
355    }
356
357    //
358    // The device class driver has completed sending a report to the
359    // host in response to a Get_Report request.
360    //
361    case USBD_HID_EVENT_REPORT_SENT: {
362        //
363        // We have nothing to do here.
364        //
365        break;
366    }
367
368    //
369    // This event is sent in response to a host Set_Report request.  The
370    // mouse device has no output reports so we return a NULL pointer and
371    // zero length to cause this request to be stalled.
372    //
373    case USBD_HID_EVENT_GET_REPORT_BUFFER: {
374        //
375        // We are being asked for a report that does not exist for
376        // this device.  Return 0 to indicate that we are not providing
377        // a buffer.
378        //
379        return (0);
380    }
381
382    //
383    // The host is asking us to set either boot or report protocol (not
384    // that it makes any difference to this particular mouse).
385    //
386    case USBD_HID_EVENT_SET_PROTOCOL: {
387        psInst->ui8Protocol = ui32MsgData;
388        break;
389    }
390
391    //
392    // The host is asking us to tell it which protocol we are currently
393    // using, boot or request.
394    //
395    case USBD_HID_EVENT_GET_PROTOCOL: {
396        return (psInst->ui8Protocol);
397    }
398
399    //
400    // Pass ERROR, SUSPEND and RESUME to the client unchanged.
401    //
402    case USB_EVENT_ERROR:
403    case USB_EVENT_SUSPEND:
404    case USB_EVENT_RESUME:
405    case USB_EVENT_LPM_RESUME:
406    case USB_EVENT_LPM_SLEEP:
407    case USB_EVENT_LPM_ERROR: {
408        return (psMouseDevice->pfnCallback(psMouseDevice->pvCBData, ui32Event,
409                                           ui32MsgData, pvMsgData));
410    }
411
412    //
413    // We ignore all other events.
414    //
415    default: {
416        break;
417    }
418    }
419    return (0);
420}
421
422//*****************************************************************************
423//
424// HID device class transmit channel event handler function.
425//
426// \param pvMouseDevice is the event callback pointer provided during
427// USBDHIDInit(). This is a pointer to our HID device structure
428// (&g_sHIDMouseDevice).
429// \param ui32Event identifies the event we are being called back for.
430// \param ui32MsgData is an event-specific value.
431// \param pvMsgData is an event-specific pointer.
432//
433// This function is called by the HID device class driver to inform the
434// application of particular asynchronous events related to report
435// transmissions made using the interrupt IN endpoint.
436//
437// \return Returns a value which is event-specific.
438//
439//*****************************************************************************
440static uint32_t HIDMouseTxHandler(void* pvMouseDevice, uint32_t ui32Event,
441                                  uint32_t ui32MsgData, void* pvMsgData) {
442    tHIDMouseInstance* psInst;
443    tUSBDHIDMouseDevice* psMouseDevice;
444
445    //
446    // Make sure we did not get a NULL pointer.
447    //
448    ASSERT(pvMouseDevice);
449
450    //
451    // Get a pointer to our instance data
452    //
453    psMouseDevice = (tUSBDHIDMouseDevice*)pvMouseDevice;
454    psInst = &psMouseDevice->sPrivateData;
455
456    //
457    // Which event were we sent?
458    //
459    switch (ui32Event) {
460    //
461    // A report transmitted via the interrupt IN endpoint was acknowledged
462    // by the host.
463    //
464    case USB_EVENT_TX_COMPLETE: {
465        //
466        // Our last transmission is complete.
467        //
468        psInst->iMouseState = eHIDMouseStateIdle;
469
470        //
471        // Pass the event on to the client.
472        //
473        psMouseDevice->pfnCallback(psMouseDevice->pvCBData,
474                                   USB_EVENT_TX_COMPLETE, ui32MsgData,
475                                   (void*)0);
476
477        break;
478    }
479
480    //
481    // We ignore all other events related to transmission of reports via
482    // the interrupt IN endpoint.
483    //
484    default: {
485        break;
486    }
487    }
488
489    return (0);
490}
491
492//*****************************************************************************
493//
494//! Initializes HID mouse device operation for a given USB controller.
495//!
496//! \param ui32Index is the index of the USB controller which is to be
497//! initialized for HID mouse device operation.
498//! \param psMouseDevice points to a structure containing parameters
499//! customizing the operation of the HID mouse device.
500//!
501//! An application wishing to offer a USB HID mouse interface to a USB host
502//! must call this function to initialize the USB controller and attach the
503//! mouse device to the USB bus.  This function performs all required USB
504//! initialization.
505//!
506//! On successful completion, this function returns the \e psMouseDevice
507//! pointer passed to it.  This must be passed on all future calls to the HID
508//! mouse device driver.
509//!
510//! When a host connects and configures the device, the application callback
511//! receives \b USB_EVENT_CONNECTED after which calls can be made to
512//! USBDHIDMouseStateChange() to report pointer movement and button presses
513//! to the host.
514//!
515//! \note The application must not make any calls to the lower level USB device
516//! interfaces if interacting with USB via the USB HID mouse device API.
517//! Doing so causes unpredictable (though almost certainly unpleasant)
518//! behavior.
519//!
520//! \return Returns NULL on failure or the psMouseDevice pointer on success.
521//
522//*****************************************************************************
523void* USBDHIDMouseInit(uint32_t ui32Index, tUSBDHIDMouseDevice* psMouseDevice) {
524    void* pvRetcode;
525    tUSBDHIDDevice* psHIDDevice;
526    tConfigDescriptor* pConfigDesc;
527
528    //
529    // Check parameter validity.
530    //
531    ASSERT(psMouseDevice);
532    ASSERT(psMouseDevice->ppui8StringDescriptors);
533    ASSERT(psMouseDevice->pfnCallback);
534
535    //
536    // Get a pointer to the HID device data.
537    //
538    psHIDDevice = &psMouseDevice->sPrivateData.sHIDDevice;
539
540    pConfigDesc = (tConfigDescriptor*)g_pui8MouseDescriptor;
541    pConfigDesc->bmAttributes = psMouseDevice->ui8PwrAttributes;
542    pConfigDesc->bMaxPower = (uint8_t)(psMouseDevice->ui16MaxPowermA / 2);
543
544    //
545    // Call the common initialization routine.
546    //
547    pvRetcode = USBDHIDMouseCompositeInit(ui32Index, psMouseDevice, 0);
548
549    //
550    // If we initialized the HID layer successfully, pass our device pointer
551    // back as the return code, otherwise return NULL to indicate an error.
552    //
553    if (pvRetcode) {
554        //
555        // Initialize the lower layer HID driver and pass it the various
556        // structures and descriptors necessary to declare that we are a
557        // keyboard.
558        //
559        pvRetcode = USBDHIDInit(ui32Index, psHIDDevice);
560
561        return ((void*)psMouseDevice);
562    } else {
563        return ((void*)0);
564    }
565}
566
567//*****************************************************************************
568//
569//! Initializes HID mouse device operation for a given USB controller.
570//!
571//! \param ui32Index is the index of the USB controller which is to be
572//! initialized for HID mouse device operation.
573//! \param psMouseDevice points to a structure containing parameters
574//! customizing the operation of the HID mouse device.
575//! \param psCompEntry is the composite device entry to initialize when
576//! creating a composite device.
577//!
578//! This call is very similar to USBDHIDMouseInit() except that it is used for
579//! initializing an instance of the HID mouse device for use in a composite
580//! device.  If this HID mouse is part of a composite device, then the
581//! \e psCompEntry should point to the composite device entry to initialize.
582//! This is part of the array that is passed to the USBDCompositeInit()
583//! function.
584//!
585//! \return Returns zero on failure or a non-zero instance value that should be
586//! used with the remaining USB HID Mouse APIs.
587//
588//*****************************************************************************
589void* USBDHIDMouseCompositeInit(uint32_t ui32Index,
590                                tUSBDHIDMouseDevice* psMouseDevice,
591                                tCompositeEntry* psCompEntry) {
592    tHIDMouseInstance* psInst;
593    tUSBDHIDDevice* psHIDDevice;
594
595    //
596    // Check parameter validity.
597    //
598    ASSERT(psMouseDevice);
599    ASSERT(psMouseDevice->ppui8StringDescriptors);
600    ASSERT(psMouseDevice->pfnCallback);
601
602    //
603    // Get a pointer to our instance data
604    //
605    psInst = &psMouseDevice->sPrivateData;
606
607    //
608    // Get a pointer to the HID device data.
609    //
610    psHIDDevice = &psMouseDevice->sPrivateData.sHIDDevice;
611
612    //
613    // Initialize the various fields in our instance structure.
614    //
615    psInst->ui8USBConfigured = 0;
616    psInst->ui8Protocol = USB_HID_PROTOCOL_REPORT;
617    psInst->sReportIdle.ui8Duration4mS = 0;
618    psInst->sReportIdle.ui8ReportID = 0;
619    psInst->sReportIdle.ui32TimeSinceReportmS = 0;
620    psInst->sReportIdle.ui16TimeTillNextmS = 0;
621    psInst->iMouseState = eHIDMouseStateUnconfigured;
622
623    //
624    // Initialize the HID device class instance structure based on input from
625    // the caller.
626    //
627    psHIDDevice->ui16PID = psMouseDevice->ui16PID;
628    psHIDDevice->ui16VID = psMouseDevice->ui16VID;
629    psHIDDevice->ui16MaxPowermA = psMouseDevice->ui16MaxPowermA;
630    psHIDDevice->ui8PwrAttributes = psMouseDevice->ui8PwrAttributes;
631    psHIDDevice->ui8Subclass = USB_HID_SCLASS_BOOT;
632    psHIDDevice->ui8Protocol = USB_HID_PROTOCOL_MOUSE;
633    psHIDDevice->ui8NumInputReports = 1;
634    psHIDDevice->psReportIdle = &psInst->sReportIdle;
635    psHIDDevice->pfnRxCallback = HIDMouseRxHandler;
636    psHIDDevice->pvRxCBData = (void*)psMouseDevice;
637    psHIDDevice->pfnTxCallback = HIDMouseTxHandler;
638    psHIDDevice->pvTxCBData = (void*)psMouseDevice;
639    psHIDDevice->bUseOutEndpoint = false;
640    psHIDDevice->psHIDDescriptor = &g_sMouseHIDDescriptor;
641    psHIDDevice->ppui8ClassDescriptors = g_pui8MouseClassDescriptors;
642    psHIDDevice->ppui8StringDescriptors = psMouseDevice->ppui8StringDescriptors;
643    psHIDDevice->ui32NumStringDescriptors =
644        psMouseDevice->ui32NumStringDescriptors;
645    psHIDDevice->ppsConfigDescriptor = g_ppsHIDConfigDescriptors;
646
647    //
648    // Initialize the lower layer HID driver and pass it the various structures
649    // and descriptors necessary to declare that we are a keyboard.
650    //
651    return (USBDHIDCompositeInit(ui32Index, psHIDDevice, psCompEntry));
652}
653
654//*****************************************************************************
655//
656//! Shuts down the HID mouse device.
657//!
658//! \param pvMouseDevice is the pointer to the device instance structure.
659//!
660//! This function terminates HID mouse operation for the instance supplied
661//! and removes the device from the USB bus.  Following this call, the
662//! \e pvMouseDevice instance may not me used in any other call to the HID
663//! mouse device other than USBDHIDMouseInit().
664//!
665//! \return None.
666//
667//*****************************************************************************
668void USBDHIDMouseTerm(void* pvMouseDevice) {
669    tUSBDHIDMouseDevice* psMouseDevice;
670    tUSBDHIDDevice* psHIDDevice;
671
672    ASSERT(pvMouseDevice);
673
674    //
675    // Get a pointer to the device.
676    //
677    psMouseDevice = (tUSBDHIDMouseDevice*)pvMouseDevice;
678
679    //
680    // Get a pointer to the HID device data.
681    //
682    psHIDDevice = &psMouseDevice->sPrivateData.sHIDDevice;
683
684    //
685    // Mark our device as no longer configured.
686    //
687    psMouseDevice->sPrivateData.ui8USBConfigured = 0;
688
689    //
690    // Terminate the low level HID driver.
691    //
692    USBDHIDTerm(psHIDDevice);
693}
694
695//*****************************************************************************
696//
697//! Sets the client-specific pointer parameter for the mouse callback.
698//!
699//! \param pvMouseDevice is the pointer to the mouse device instance structure.
700//! \param pvCBData is the pointer that client wishes to be provided on
701//! each event sent to the mouse callback function.
702//!
703//! The client uses this function to change the callback pointer passed in
704//! the first parameter on all callbacks to the \e pfnCallback function
705//! passed on USBDHIDMouseInit().
706//!
707//! If a client wants to make runtime changes in the callback pointer, it must
708//! ensure that the pvMouseDevice structure passed to USBDHIDMouseInit()
709//! resides in RAM.  If this structure is in flash, callback data changes are
710//! not possible.
711//!
712//! \return Returns the previous callback pointer that was set for this
713//! instance.
714//
715//*****************************************************************************
716void* USBDHIDMouseSetCBData(void* pvMouseDevice, void* pvCBData) {
717    void* pvOldCBData;
718    tUSBDHIDMouseDevice* psMouse;
719
720    //
721    // Check for a NULL pointer in the device parameter.
722    //
723    ASSERT(pvMouseDevice);
724
725    //
726    // Get a pointer to our mouse device.
727    //
728    psMouse = (tUSBDHIDMouseDevice*)pvMouseDevice;
729
730    //
731    // Save the old callback pointer and replace it with the new value.
732    //
733    pvOldCBData = psMouse->pvCBData;
734    psMouse->pvCBData = pvCBData;
735
736    //
737    // Pass the old callback pointer back to the caller.
738    //
739    return (pvOldCBData);
740}
741
742//*****************************************************************************
743//
744//! Reports a mouse state change, pointer movement or button press, to the USB
745//! host.
746//!
747//! \param pvMouseDevice is the pointer to the mouse device instance structure.
748//! \param i8DeltaX is the relative horizontal pointer movement that the
749//! application wishes to report.  Valid values are in the range [-127, 127]
750//! with positive values indicating movement to the right.
751//! \param i8DeltaY is the relative vertical pointer movement that the
752//! application wishes to report.  Valid values are in the range [-127, 127]
753//! with positive values indicating downward movement.
754//! \param ui8Buttons is a bit mask indicating which (if any) of the three
755//! mouse buttons is pressed.  Valid values are logical OR combinations of
756//! \b MOUSE_REPORT_BUTTON_1, \b MOUSE_REPORT_BUTTON_2 and
757//! \b MOUSE_REPORT_BUTTON_3.
758//!
759//! This function is called to report changes in the mouse state to the USB
760//! host.  These changes can be movement of the pointer, reported relative to
761//! its previous position, or changes in the states of up to 3 buttons that
762//! the mouse may support.  The return code indicates whether or not the
763//! mouse report could be sent to the host.  In cases where a previous
764//! report is still being transmitted, \b MOUSE_ERR_TX_ERROR is returned
765//! and the state change is ignored.
766//!
767//! \return Returns \b MOUSE_SUCCESS on success, \b MOUSE_ERR_TX_ERROR if an
768//! error occurred while attempting to schedule transmission of the mouse
769//! report to the host (typically due to a previous report which has not yet
770//! completed transmission or due to disconnection of the host) or \b
771//! MOUSE_ERR_NOT_CONFIGURED if called before a host has connected to and
772//! configured the device.
773//
774//*****************************************************************************
775uint32_t USBDHIDMouseStateChange(void* pvMouseDevice, int8_t i8DeltaX,
776                                 int8_t i8DeltaY, uint8_t ui8Buttons) {
777    uint32_t ui32Retcode, ui32Count;
778    tHIDMouseInstance* psInst;
779    tUSBDHIDMouseDevice* psMouseDevice;
780    tUSBDHIDDevice* psHIDDevice;
781
782    //
783    // Get a pointer to the device.
784    //
785    psMouseDevice = (tUSBDHIDMouseDevice*)pvMouseDevice;
786
787    //
788    // Get a pointer to the HID device data.
789    //
790    psHIDDevice = &psMouseDevice->sPrivateData.sHIDDevice;
791
792    //
793    // Get a pointer to our instance data
794    //
795    psInst = &psMouseDevice->sPrivateData;
796
797    //
798    // Update the global mouse report with the information passed.
799    //
800    psInst->pui8Report[HID_REPORT_BUTTONS] = ui8Buttons;
801    psInst->pui8Report[HID_REPORT_X] = (uint8_t)i8DeltaX;
802    psInst->pui8Report[HID_REPORT_Y] = (uint8_t)i8DeltaY;
803
804    //
805    // If we are not configured, return an error here before trying to send
806    // anything.
807    //
808    if (!psInst->ui8USBConfigured) {
809        return (MOUSE_ERR_NOT_CONFIGURED);
810    }
811
812    //
813    // Only send a report if the transmitter is currently free.
814    //
815    if (USBDHIDTxPacketAvailable((void*)psHIDDevice)) {
816        //
817        // Send the report to the host.
818        //
819        psInst->iMouseState = eHIDMouseStateSend;
820        ui32Count = USBDHIDReportWrite((void*)psHIDDevice, psInst->pui8Report,
821                                       MOUSE_REPORT_SIZE, true);
822
823        //
824        // Did we schedule a packet for transmission correctly?
825        //
826        if (!ui32Count) {
827            //
828            // No - report the error to the caller.
829            //
830            ui32Retcode = MOUSE_ERR_TX_ERROR;
831        } else {
832            ui32Retcode = MOUSE_SUCCESS;
833        }
834    } else {
835        ui32Retcode = MOUSE_ERR_TX_ERROR;
836    }
837    //
838    // Return the relevant error code to the caller.
839    //
840    return (ui32Retcode);
841}
842#ifndef DEPRECATED
843
844//*****************************************************************************
845//
846//! Reports the device power status (bus- or self-powered) to the USB library.
847//!
848//! \param pvMouseDevice is the pointer to the mouse device instance structure.
849//! \param ui8Power indicates the current power status, either \b
850//! USB_STATUS_SELF_PWR or \b USB_STATUS_BUS_PWR.
851//!
852//! Applications which support switching between bus- or self-powered
853//! operation should call this function whenever the power source changes
854//! to indicate the current power status to the USB library.  This information
855//! is required by the USB library to allow correct responses to be provided
856//! when the host requests status from the device.
857//!
858//! \return None.
859//
860//*****************************************************************************
861void USBDHIDMousePowerStatusSet(void* pvMouseDevice, uint8_t ui8Power) {
862    tUSBDHIDMouseDevice* psMouseDevice;
863    tUSBDHIDDevice* psHIDDevice;
864
865    ASSERT(pvMouseDevice);
866
867    //
868    // Get the keyboard device pointer.
869    //
870    psMouseDevice = (tUSBDHIDMouseDevice*)pvMouseDevice;
871
872    //
873    // Get a pointer to the HID device data.
874    //
875    psHIDDevice = &psMouseDevice->sPrivateData.sHIDDevice;
876
877    //
878    // Pass the request through to the lower layer.
879    //
880    USBDHIDPowerStatusSet((void*)psHIDDevice, ui8Power);
881}
882#endif
883
884//*****************************************************************************
885//
886//! Requests a remote wake up to resume communication when in suspended state.
887//!
888//! \param pvMouseDevice is the pointer to the mouse device instance structure.
889//!
890//! When the bus is suspended, an application which supports remote wake up
891//! (advertised to the host via the configuration descriptor) may call this
892//! function to initiate remote wake up signaling to the host.  If the remote
893//! wake up feature has not been disabled by the host, this causes the bus
894//! to resume operation within 20mS.  If the host has disabled remote wake up,
895//! \b false is returned to indicate that the wake up request was not
896//! successful.
897//!
898//! \return Returns \b true if the remote wake up is not disabled and the
899//! signaling was started or \b false if remote wake up is disabled or if
900//! signaling is currently ongoing following a previous call to this function.
901//
902//*****************************************************************************
903bool USBDHIDMouseRemoteWakeupRequest(void* pvMouseDevice) {
904    tUSBDHIDMouseDevice* psMouseDevice;
905    tUSBDHIDDevice* psHIDDevice;
906
907    ASSERT(pvMouseDevice);
908
909    //
910    // Get the keyboard device pointer.
911    //
912    psMouseDevice = (tUSBDHIDMouseDevice*)pvMouseDevice;
913
914    //
915    // Get a pointer to the HID device data.
916    //
917    psHIDDevice = &psMouseDevice->sPrivateData.sHIDDevice;
918
919    //
920    // Pass the request through to the lower layer.
921    //
922    return (USBDHIDRemoteWakeupRequest((void*)&psHIDDevice));
923}
924
925//*****************************************************************************
926//
927// Close the Doxygen group.
928//! @}
929//
930//*****************************************************************************