//
// 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:  

    debug.cpp

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

Functions:

Notes: 

--*/

#include "usbhid.h"
#include "hiddbg.h"


#ifdef DEBUG

// Debug Zones
#define DBG_ERROR              0x0001
#define DBG_WARNING            0x0002
#define DBG_INIT               0x0004
#define DBG_FUNCTION           0x0008

#define DBG_HID_DATA           0x0010

#define DBG_USB_PARSE          0x0100

#define DBG_USBCLIENT          0x8000

DBGPARAM dpCurSettings = {
        TEXT("Hid"), {
        TEXT("Errors"), TEXT("Warnings"), TEXT("Init"), TEXT("Function"),
        TEXT("HID Data"), TEXT(""), TEXT(""), TEXT(""),
        TEXT("Parsing"), TEXT(""), TEXT(""), TEXT(""),
        TEXT(""), TEXT(""), TEXT(""), TEXT("USB Client") },
        DBG_ERROR | DBG_WARNING };


//
// ***** Debug utility functions *****
//


// Global HID class data
extern CRITICAL_SECTION g_csHidLock; // Protects accesses to the following variables
extern BOOL g_fInitialized; // Has this global data been initialized?
extern PUSBHID_CONTEXT *g_rgpUsbHid; // Holds information for each HID interface
extern DWORD g_cpUsbHid; // Count of entries in g_rgpUsbHid
extern HANDLE g_hOSDevice; // The HID class device (HID0:)
#ifdef DEBUG
extern INT g_cInHidCS; // The current depth of g_csHidLock
#endif


// Debug Alloc
HLOCAL
HidAlloc(
    SIZE_T cb
    )
{
    LPVOID ptr;
    
    DEBUGCHK(cb != 0);

    ptr = LocalAlloc(LMEM_FIXED, cb);

    return ptr;
}


// Debug ReAlloc
HLOCAL
HidReAlloc(
    HLOCAL hMem,
    SIZE_T cb,
    UINT   uiFlags    
    )
{
    SETFNAME(_T("HidReAlloc"));
    
    LPVOID ptr;

    DEBUGCHK(hMem != NULL);
    DEBUGCHK(cb != 0);

    if ((uiFlags & LMEM_MOVEABLE) == 0) {
        DEBUGMSG(ZONE_WARNING, 
            (_T("%s: Are you sure you want to realloc without setting LMEM_MOVEABLE?\r\n"), 
            pszFname));
    }

    ptr = LocalReAlloc(hMem, cb, uiFlags);

    return ptr;
}


// Debug Free
HLOCAL
HidFree(
    LPVOID ptr
    )
{
    DEBUGCHK(ptr != NULL);
    
    return LocalFree(ptr);
}


// IsLocked helper function
static
BOOL
DebugIsLocked(
    INT cInCS
    )
{
    return cInCS > 0;
}


// Lock helper function
static
void
DebugLock(
    LPCRITICAL_SECTION pCS,
    INT *pcInCS
    )
{
    DEBUGCHK(*pcInCS < 10); // Check for cycle
    EnterCriticalSection(pCS);
    ++(*pcInCS);
}


// Release helper function
static
void
DebugRelease(
    LPCRITICAL_SECTION pCS,
    INT *pcInCS
    )
{
    DEBUGCHK(DebugIsLocked(*pcInCS) == TRUE);
    --(*pcInCS);
    LeaveCriticalSection(pCS);
}


// Checks to see if the global access cs is currently entered
BOOL
IsHidDataLocked(
    void
    )
{
    return DebugIsLocked(g_cInHidCS);
}


// Enters the global access cs
void
LockHidData(
    void
    )
{
    DebugLock(&g_csHidLock, &g_cInHidCS);
}


// Leaves the global access cs
void
ReleaseHidData(
    void
    )
{
    DebugRelease(&g_csHidLock, &g_cInHidCS);
}


// Returns true if the Hid context is locked
BOOL
IsHidContextLocked(
    const USBHID_CONTEXT *pUsbHid
    )
{
    DEBUGCHK(pUsbHid != NULL);
    return DebugIsLocked(pUsbHid->cInCS);
}


// Take the Hid context lock
void
LockHidContext(
    USBHID_CONTEXT *pUsbHid
    )
{
    DEBUGCHK(pUsbHid != NULL);
    DebugLock(&pUsbHid->csLock, &pUsbHid->cInCS);
}


// Release the Hid context lock
void
ReleaseHidContext(
    USBHID_CONTEXT *pUsbHid
    )
{
    DEBUGCHK(pUsbHid != NULL);
    DebugRelease(&pUsbHid->csLock, &pUsbHid->cInCS);
}


// Verify the integrity of a device context.
void
ValidateHidContext(
    PUSBHID_CONTEXT pUsbHid 
    )
{
    DEBUGCHK(pUsbHid != NULL);

    LockHidContext(pUsbHid);

    DEBUGCHK(pUsbHid->Sig == USB_HID_SIG);
    DEBUGCHK(pUsbHid->hEP0Event != NULL);
    DEBUGCHK(pUsbHid->hThread != NULL);
    DEBUGCHK(pUsbHid->hUsbDevice != NULL);
    DEBUGCHK(pUsbHid->InterruptIn.hPipe != NULL);
    DEBUGCHK(pUsbHid->InterruptIn.hEvent != NULL);
    DEBUGCHK(pUsbHid->pUsbFuncs != NULL);
    DEBUGCHK(pUsbHid->pUsbInterface != NULL);
    DEBUGCHK(pUsbHid->phidpDeviceDesc != NULL);
    DEBUGCHK(LocalSize(pUsbHid->phidpDeviceDesc) == sizeof(HIDP_DEVICE_DESC));  
    DEBUGCHK(pUsbHid->pQueues != NULL);
    DEBUGCHK(pUsbHid->pClientHandles != NULL);

    ReleaseHidContext(pUsbHid);
}


// Verify the integrity of the global data
void
ValidateHidGlobals(
    void
    )
{
    LockHidData();
    
    if (g_fInitialized == TRUE)
    {
        DEBUGCHK(g_rgpUsbHid != NULL);
        DEBUGCHK(g_cpUsbHid != 0);
        DEBUGCHK(LocalSize(g_rgpUsbHid) == HID_ARRAY_BYTE_SIZE(g_cpUsbHid));    
        DEBUGCHK(g_hOSDevice != NULL);

        for (DWORD dwIdx = 0; dwIdx < g_cpUsbHid; ++dwIdx) {
            PUSBHID_CONTEXT pUsbHid = g_rgpUsbHid[dwIdx];
            if (pUsbHid != NULL) {
                ValidateHidContext(pUsbHid);
            }
        }
    }
    else
    {
        DEBUGCHK(g_rgpUsbHid == NULL);
        DEBUGCHK(g_cpUsbHid == 0);
        DEBUGCHK(g_hOSDevice == NULL);
    }

    ReleaseHidData();
}


// Verify the integrity of the HID client handle
void
ValidateClientHandle(
    PHID_CLIENT_HANDLE pHidClient 
    )
{
    DEBUGCHK(pHidClient != NULL);
    DEBUGCHK(IsBadReadPtr(pHidClient, sizeof(*pHidClient)) == FALSE);
    DEBUGCHK(pHidClient->Sig == USB_HID_CLIENT_SIG);
    DEBUGCHK(pHidClient->pQueue != NULL);
    pHidClient->pQueue->Validate();
    DEBUGCHK(pHidClient->phidpPreparsedData != NULL);
    DEBUGCHK(pHidClient->pUsbHid != NULL);
    ValidateHidContext(pHidClient->pUsbHid);
}


// Output a Hid device description
void 
DumpHIDDeviceDescription(
    const HIDP_DEVICE_DESC *phidpDeviceDesc
    )
{
    UINT ui;
    
    DEBUGCHK(phidpDeviceDesc != NULL);
    
    if (ZONE_USB_PARSE)
    {
        DEBUGMSG(1, (_T("\r\nHid Device Description:\r\n")));
        
        for (ui = 0; ui < phidpDeviceDesc->CollectionDescLength; ++ui)
        {
            const HIDP_COLLECTION_DESC *phidpCollDesc = phidpDeviceDesc->CollectionDesc + ui;
            DEBUGCHK(phidpCollDesc != NULL);

            DEBUGMSG(1, (_T("Collection #%u: Usage Page 0x%x Usage 0x%x\r\n"), 
                phidpCollDesc->CollectionNumber, phidpCollDesc->UsagePage, 
                phidpCollDesc->Usage));
            DEBUGMSG(1, (_T("Input Length 0x%x Output Length 0x%x Feature Length 0x%x\r\n"),
                phidpCollDesc->InputLength, phidpCollDesc->OutputLength, 
                phidpCollDesc->FeatureLength));
        }
        
        for (ui = 0; ui < phidpDeviceDesc->ReportIDsLength; ++ui)
        {
            const HIDP_REPORT_IDS *phidpReports = phidpDeviceDesc->ReportIDs + ui;
            DEBUGCHK(phidpReports != NULL);

            DEBUGMSG(1, (_T("Collection #%u, Report #%u\r\n"),
                phidpReports->CollectionNumber, phidpReports->ReportID));
            DEBUGMSG(1, (_T("Input Length 0x%x Output Length 0x%x Feature Length 0x%x\r\n"),
                phidpReports->InputLength, phidpReports->OutputLength, 
                phidpReports->FeatureLength));
        }

        DEBUGMSG(1, (_T("\r\n")));
    }
}


#endif // DEBUG