setup.cpp

hidclass source code for windows ce use

//
// Copyright (c) Microsoft Corporation.  All rights reserved.
//
//
// Use of this source code is subject to the terms of the Microsoft end-user
// license agreement (EULA) under which you licensed this SOFTWARE PRODUCT.
// If you did not accept the terms of the EULA, you are not authorized to use
// this source code. For a copy of the EULA, please see the LICENSE.RTF on your
// install media.
//
/*++
THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE.

Module Name:  

    setup.cpp

Abstract:  
    USB Client Driver for Human Interface Device (HID) Class.

Functions:

Notes: 

--*/


#include "usbhid.h"


// Structure for queueing multiple USB transfers
struct USB_HID_TRANSFER {
    HANDLE hev; // Event signaled when transfer is complete
    USB_TRANSFER hTransfer; // Handle to the transfer
    PBYTE rgbBuffer; // Buffer for the HID report
};
typedef USB_HID_TRANSFER *PUSB_HID_TRANSFER;


#ifdef DEBUG
#define GARBAGE_BYTE   (0xCC)
#define GARBAGE_PVOID  ( (PVOID) 0xCCCCCCCC )
#endif

// The number of simultaneous interrupt transfers to issue
static BYTE g_bQueuedTransfers = DEFAULT_QUEUED_TRANSFERS;


// Helper function to close a pipe structure
static
void
ClosePipe(
    LPCUSB_FUNCS pUsbFuncs,
    PPIPE pPipe
    )
{
    PREFAST_DEBUGCHK(pUsbFuncs != NULL);
    PREFAST_DEBUGCHK(pPipe != NULL);

    if (pPipe->hPipe) {
        pUsbFuncs->lpClosePipe(pPipe->hPipe);
    }

    if (pPipe->hEvent) {
        CloseHandle(pPipe->hEvent);
    }
}


// Frees all device handles and removes it from the global list.
void
RemoveDeviceContext(
   PUSBHID_CONTEXT pUsbHid
   )
{
    SETFNAME(_T("RemoveDeviceContext"));

    DWORD cCollections = 0;
    
    DEBUGCHK(pUsbHid != NULL);
    
    if (VALID_CONTEXT(pUsbHid)) {
        // If nothing else, at least the CS was initialized.
        LockUsbHidContext(pUsbHid);
        pUsbHid->Flags.UnloadPending = TRUE;
        UnlockUsbHidContext(pUsbHid);

        if (pUsbHid->Flags.MddInitialized == TRUE) {
            // Tell the MDD about disconnect.
            // Do this before freeing resources since the MDD could currently
            // be in the process of calling us.
            HidMdd_Notifications(HID_MDD_CLOSE_DEVICE, 0, pUsbHid->pvNotifyParameter);
        }        

        if (pUsbHid->InterruptIn.hPipe != NULL) {
            pUsbHid->pUsbFuncs->lpAbortPipeTransfers(pUsbHid->InterruptIn.hPipe, 0);
        }

        ClosePipe(pUsbHid->pUsbFuncs, &pUsbHid->InterruptIn);

        if (pUsbHid->hThread != NULL) {
            WaitForSingleObject(pUsbHid->hThread, INFINITE);
            CloseHandle(pUsbHid->hThread);
        }
        
        if (pUsbHid->hEP0Event != NULL) CloseHandle(pUsbHid->hEP0Event);
        
        DeleteCriticalSection(&pUsbHid->csLock);

        if (pUsbHid->hHidDriver) {
            DeactivateDevice(pUsbHid->hHidDriver);
        }
        
        HidFree(pUsbHid);
    } 
    else {
        DEBUGMSG(ZONE_ERROR, (_T("%s: Invalid Parameter\r\n"), pszFname));
        DEBUGCHK(FALSE);
    }
}


// Returns the interface to use.
LPCUSB_INTERFACE
ParseUsbDescriptors(
    LPCUSB_INTERFACE pCurrInterface
    )
{
    SETFNAME(_T("ParseUsbDescriptors"));

    LPCUSB_INTERFACE pHidInterface = NULL;

    DEBUGMSG(ZONE_INIT, (_T("+%s"), pszFname));

    DEBUGCHK(pCurrInterface != NULL);
    
    if (pCurrInterface != NULL) 
    {        
        // If loaded as an interface driver, ignore non HID interfaces
        if (pCurrInterface->Descriptor.bInterfaceClass != USB_DEVICE_CLASS_HUMAN_INTERFACE) {
            DEBUGMSG(ZONE_INIT, (_T("%s: DeviceAttach, ignoring non HID interface class %u\r\n"),
                pszFname, pCurrInterface->Descriptor.bInterfaceClass));
        }
        else {
            pHidInterface = pCurrInterface;
        }
    }

    DEBUGMSG(ZONE_INIT, (_T("-%s"), pszFname));
    return pHidInterface;
}


// Get the report descriptor from the device.
static
BOOL
GetReportDescriptor(
    PUSBHID_CONTEXT pUsbHid,
    PBYTE pbBuffer,
    WORD cbBuffer // This should be the exact size of the descriptor
    )
{
    SETFNAME(_T("GetReportDescriptor"));

    BOOL fRet = FALSE;
    USB_DEVICE_REQUEST udr;
    DWORD dwBytesTransferred;
    DWORD dwUsbErr;
    DWORD dwErr;

    PREFAST_DEBUGCHK(pUsbHid != NULL);
    DEBUGCHK(cbBuffer > 0);

    // Do we send this to the endpoint or the interface?
    DetermineDestination(pUsbHid, &udr.bmRequestType, &udr.wIndex);
    udr.bmRequestType |= USB_REQUEST_DEVICE_TO_HOST;

    udr.bRequest = USB_REQUEST_GET_DESCRIPTOR;
    udr.wValue   = USB_DESCRIPTOR_MAKE_TYPE_AND_INDEX(HID_REPORT_DESCRIPTOR_TYPE, 0);
    udr.wLength  = cbBuffer;

    dwErr = IssueVendorTransfer(
        pUsbHid->pUsbFuncs,
        pUsbHid->hUsbDevice,
        NULL, 
        NULL,
        (USB_IN_TRANSFER | USB_SHORT_TRANSFER_OK),
        &udr,
        pbBuffer,
        0,
        &dwBytesTransferred,
        0,
        &dwUsbErr);

    if ( (ERROR_SUCCESS != dwErr) || (USB_NO_ERROR != dwUsbErr) || 
         (dwBytesTransferred != cbBuffer) ) 
    {
        DEBUGMSG(ZONE_ERROR, (_T("%s: IssueVendorTransfer ERROR:%d 0x%x\n"), 
            pszFname, dwErr, dwUsbErr));
        goto EXIT;
    }
  
    fRet = TRUE;
    
EXIT:
    return fRet;
}


// Setup the pipes for this interface
static
BOOL
SetUsbInterface(
   PUSBHID_CONTEXT pUsbHid
   )
{
    SETFNAME(_T("SetUsbInterface"));

    BOOL fRet = FALSE;
    DWORD dwIndex;
    BYTE bNumEndpoints;

    PREFAST_DEBUGCHK(pUsbHid != NULL);
    DEBUGCHK(pUsbHid->pUsbInterface != NULL);

    // Parse the endpoints
    bNumEndpoints = pUsbHid->pUsbInterface->Descriptor.bNumEndpoints;
    for (dwIndex = 0; dwIndex < bNumEndpoints; ++dwIndex) 
    {
        LPCUSB_ENDPOINT pEndpoint;
        pEndpoint = pUsbHid->pUsbInterface->lpEndpoints + dwIndex;
        PREFAST_DEBUGCHK(pEndpoint != NULL);
        USB_ENDPOINT_DESCRIPTOR const * pEPDesc = &pEndpoint->Descriptor;

        DUMP_USB_ENDPOINT_DESCRIPTOR((*pEPDesc));

        // 
        // HID Class supports 1 mandatory Interrupt IN, and 1 optional Interrupt OUT
        // 
        if (USB_ENDPOINT_DIRECTION_IN(pEndpoint->Descriptor.bEndpointAddress))
        {            
            if ( (NULL == pUsbHid->InterruptIn.hPipe) &&
               ( (pEPDesc->bmAttributes & USB_ENDPOINT_TYPE_MASK) != 0) )
            {
                // create the Interrupt In pipe
                pUsbHid->InterruptIn.hPipe = 
                    pUsbHid->pUsbFuncs->lpOpenPipe(pUsbHid->hUsbDevice, pEPDesc);
                if (pUsbHid->InterruptIn.hPipe == NULL) {
                    DEBUGMSG(ZONE_ERROR, (_T("%s: OpenPipe error:%d\r\n"), 
                        pszFname, GetLastError()));
                    goto EXIT;
                }

                // setup any endpoint specific timers, buffers, context, etc.
                pUsbHid->InterruptIn.hEvent = CreateEvent(NULL, 
                    MANUAL_RESET_EVENT, FALSE, NULL);
                if (pUsbHid->InterruptIn.hEvent == NULL) {
                    DEBUGMSG(ZONE_ERROR, (_T("%s: CreateEvent error:%d\r\n"), 
                        pszFname, GetLastError()));
                    goto EXIT;
                }

                pUsbHid->InterruptIn.bIndex         = pEPDesc->bEndpointAddress;
                pUsbHid->InterruptIn.wMaxPacketSize = pEPDesc->wMaxPacketSize;
            }
            else {
                // The HID spec does not allow for this condition. 
                // You should not get here!
                DEBUGCHK(FALSE); 
            }
        } 
        else if (USB_ENDPOINT_DIRECTION_OUT(pEPDesc->bEndpointAddress)) 
        {
            DEBUGMSG(ZONE_WARNING, 
                (_T("%s: USB HID Driver does not support optional Interrupt Out\r\n"),
                pszFname));      
        }
        else {
            // The HID spec does not allow for this condition. 
            // You should not get here!
            DEBUGCHK(FALSE); 
        }
    }

    // Did we find our endpoint?
    if (pUsbHid->InterruptIn.hPipe == NULL) {
        DEBUGMSG(ZONE_ERROR, (_T("%s: No Interrupt In endpoint\r\n"), pszFname));
        goto EXIT;
    }

    // If we failed to find all of our endpoints then cleanup will occur later

    fRet = TRUE;

EXIT:
    return fRet;
}


// Set the device protocol to report (not boot)
static
BOOL
SetReportProtocol(
    PUSBHID_CONTEXT pUsbHid
    )
{
    SETFNAME(_T("SetReportProtocol"));
    
    DWORD dwErr, dwBytesTransferred;
    USB_ERROR usbErr;
    USB_DEVICE_REQUEST udr;
    
    PREFAST_DEBUGCHK(pUsbHid != NULL);
    ValidateUsbHidContext(pUsbHid);
    DEBUGCHK(pUsbHid->pUsbInterface->Descriptor.bInterfaceSubClass == 
        HID_INTERFACE_BOOT_SUBCLASS);

    // Do we send this to the endpoint or the interface?
    DetermineDestination(pUsbHid, &udr.bmRequestType, &udr.wIndex);
    udr.bmRequestType |= USB_REQUEST_HOST_TO_DEVICE | USB_REQUEST_CLASS;

    udr.bRequest = USB_REQUEST_HID_SET_PROTOCOL;
    udr.wValue   = HID_REPORT_PROTOCOL;
    udr.wLength  = 0;

    dwErr = IssueVendorTransfer(
        pUsbHid->pUsbFuncs,
        pUsbHid->hUsbDevice,
        NULL, 
        NULL,
        USB_OUT_TRANSFER,
        &udr,
        NULL,
        0,
        &dwBytesTransferred,
        0,
        &usbErr);

    if ((dwErr != ERROR_SUCCESS) || (usbErr != USB_NO_ERROR) ) {
        DEBUGMSG(ZONE_ERROR, (_T("%s: Set report protocol error: 0x%x 0x%x\r\n"), 
            pszFname, dwErr, usbErr));
    }

    return (dwErr == ERROR_SUCCESS);
}


// Sets the number of interrupt transfers to queue at one time
static
void
SetQueuedTransfers(
    LPCTSTR pszReg
    )
{
    SETFNAME(_T("SetQueuedTransfers"));
    
    DEBUGCHK(pszReg);
    DEBUGCHK(MAX_QUEUED_TRANSFERS < UCHAR_MAX);

    HKEY hkey;
    
    LONG iErr = RegOpenKeyEx(HKEY_LOCAL_MACHINE, pszReg, NULL, NULL, &hkey);
    
    if (iErr == ERROR_SUCCESS) {
        DWORD dwType;
        DWORD dwValue;
        DWORD cbValue = sizeof(dwValue);
        
        iErr = RegQueryValueEx(hkey, QUEUED_TRANSFERS_SZ, NULL, 
            &dwType, (PBYTE) &dwValue, &cbValue);

        if ( (iErr == ERROR_SUCCESS) && (dwType == REG_DWORD) ) {
            dwValue = max(MIN_QUEUED_TRANSFERS, dwValue);
            dwValue = min(MAX_QUEUED_TRANSFERS, dwValue);

            DEBUGMSG(ZONE_COMMENT, (_T("%s: Setting to %u queued USB transfers\r\n"), 
                pszFname, dwValue));
            g_bQueuedTransfers = (BYTE) dwValue;
        }
    }
}


// Creates and returns the HID device context.
// Returns NULL if error.
PUSBHID_CONTEXT
CreateUsbHidDevice(
    USB_HANDLE hUsbDevice,
    PCUSB_FUNCS pUsbFuncs,
    PCUSB_INTERFACE pUsbInterface
    )
{
    SETFNAME(_T("CreateHidInterface"));
    PUSBHID_CONTEXT pUsbHid = NULL;
    BOOL fErr = TRUE;
    PCUSB_DEVICE pDeviceInfo = NULL;
    PHID_DESCRIPTOR pHidDescriptor = NULL;
    PCUSB_ENDPOINT pEndpoint = NULL;
    PBYTE pbReportDescriptor = NULL;
    WORD  cbReportDescriptor;

    DEBUGMSG(ZONE_INIT, (_T("+%s\r\n"), pszFname));

    PREFAST_DEBUGCHK(pUsbFuncs != NULL);
    PREFAST_DEBUGCHK(pUsbInterface != NULL);

    pDeviceInfo = (*pUsbFuncs->lpGetDeviceInfo)(hUsbDevice);
    if (pDeviceInfo == NULL) {
        DEBUGMSG(ZONE_ERROR, (_T("%s: Failure getting USB device info\r\n"), 
            pszFname));
        goto EXIT;
    }