///////////////////////////////////////////////////////////////////////////////
//
//    (C) Copyright 2005 OSR Open Systems Resources, Inc.
//    All Rights Reserved
//
//    This sofware is supplied for instructional purposes only.
//
//    OSR Open Systems Resources, Inc. (OSR) expressly disclaims any warranty
//    for this software.  THIS SOFTWARE IS PROVIDED  "AS IS" WITHOUT WARRANTY
//    OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION,
//    THE IMPLIED WARRANTIES OF MECHANTABILITY OR FITNESS FOR A PARTICULAR
//    PURPOSE.  THE ENTIRE RISK ARISING FROM THE USE OF THIS SOFTWARE REMAINS
//    WITH YOU.  OSR's entire liability and your exclusive remedy shall not
//    exceed the price paid for this material.  In no event shall OSR or its
//    suppliers be liable for any damages whatsoever (including, without
//    limitation, damages for loss of business profit, business interruption,
//    loss of business information, or any other pecuniary loss) arising out
//    of the use or inability to use this software, even if OSR has been
//    advised of the possibility of such damages.  Because some states/
//    jurisdictions do not allow the exclusion or limitation of liability for
//    consequential or incidental damages, the above limitation may not apply
//    to you.
//
//    OSR Open Systems Resources, Inc.
//    105 Route 101A Suite 19
//    Amherst, NH 03031  (603) 595-6500 FAX: (603) 595-6503
//    email bugs to: bugs@osr.com
//
//
//    MODULE:
//
//        USBFX2LK.H
//
//    ABSTRACT:
//
//		This is the general include file for the OSR USB FX2 Learning Kit Driver.
//
//    AUTHOR(S):
//
//        OSR Open Systems Resources, Inc.
// 
///////////////////////////////////////////////////////////////////////////////
#ifndef __USBFX2LK_H__
#define __USBFX2LK_H__ (1) // suppress duplicate loading of this file

extern "C" {

#include <ntddk.h>
#include <initguid.h>
#include <ntstrsafe.h>
#include <csq.h>
#include <limits.h>
#include <wmistr.h>
#include <wmilib.h>
#include <wmidata.h>

//
// 4200: nonstandard extension used.
//
// We like to build with the .CPP suffix in order to
//  get the strong type checking and various other benefits
//  of the C++ compiler, but unforunately the USB headers
//  don't compile correctly when included. We must disable
//  this warning in order to make things work properly.
//
#pragma warning(push)
#pragma warning(disable : 4200)
#include <usbdi.h>
#pragma warning(pop)

#include <usbdlib.h>

#ifndef W2K
#include <usbbusif.h>
#endif
};

#include "usbfx2lk_ioctl.h"
#include "usbfx2lk_mofdata.h"


//
// Define Driver Name to be used in outputting debug messages.
//
#define DRIVER_NAME "OSRUSBFX2"

//
// Debugging Output Levels
//

#ifndef TRACE_LEVEL_INFORMATION
#define TRACE_LEVEL_NONE        0   // Tracing is not on
#define TRACE_LEVEL_FATAL       1   // Abnormal exit or termination
#define TRACE_LEVEL_ERROR       2   // Severe errors that need logging
#define TRACE_LEVEL_WARNING     3   // Warnings such as allocation failure
#define TRACE_LEVEL_INFORMATION 4   // Includes non-error cases(e.g.,Entry-Exit)
#define TRACE_LEVEL_VERBOSE     5   // Detailed traces from intermediate steps
#define TRACE_LEVEL_RESERVED6   6
#define TRACE_LEVEL_RESERVED7   7
#define TRACE_LEVEL_RESERVED8   8
#define TRACE_LEVEL_RESERVED9   9
#endif // TRACE_LEVEL_INFORMATION

//
// WPP_TRACING is enabled or disabled in the SOURCES file
//
#ifdef WPP_TRACING

#define WPP_CONTROL_GUIDS \
  WPP_DEFINE_CONTROL_GUID(USBFX2LK,(AC072299,57FA,46e9,BF59,E9E649182794), \
    WPP_DEFINE_BIT(OSRDBG_PNP_INFO)                /*0x00000001*/ \
    WPP_DEFINE_BIT(OSRDBG_IOCTL_INFO)              /*0x00000002*/ \
    WPP_DEFINE_BIT(OSRDBG_CREATE_CLOSE_INFO)       /*0x00000004*/ \
    WPP_DEFINE_BIT(OSRDBG_POWER_INFO)              /*0x00000008*/ \
    WPP_DEFINE_BIT(OSRDBG_WMI_INFO)                /*0x00000010*/ \
    WPP_DEFINE_BIT(OSRDBG_READWRITE)               /*0x00000020*/ \
    WPP_DEFINE_BIT(OSRDBG_REFERENCE_COUNT)         /*0x00000040*/ \
    WPP_DEFINE_BIT(OSRDBG_USB)                     /*0x00000080*/ \
    WPP_DEFINE_BIT(OSRDBG_SELECTIVE_SUSPEND)       /*0x00000100*/ \
    WPP_DEFINE_BIT(OSRDBG_WAIT_WAKE)               /*0x00000200*/ \
    WPP_DEFINE_BIT(OSRDBG_WAIT_FOR_OBJECT)         /*0x00000400*/ \
    )

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
    WPP_LEVEL_LOGGER(flags)

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
    (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

#else // WPP_TRACING

#define OSRDBG_PNP_INFO                0x00000001
#define OSRDBG_IOCTL_INFO              0x00000002
#define OSRDBG_CREATE_CLOSE_INFO       0x00000004
#define OSRDBG_POWER_INFO              0x00000008
#define OSRDBG_WMI_INFO                0x00000010
#define OSRDBG_READWRITE               0x00000020
#define OSRDBG_REFERENCE_COUNT         0x00000040
#define OSRDBG_USB                     0x00000080
#define OSRDBG_SELECTIVE_SUSPEND       0x00000100
#define OSRDBG_WAIT_WAKE               0x00000200
#define OSRDBG_WAIT_FOR_OBJECT         0x00000400

#define OsrTracePrint(_level,_flag_,_msg_)      \
    if (OsrDebugLevel & (_flag_)) {     \
        DbgPrint (DRIVER_NAME": ");    \
        DbgPrint _msg_;                 \
    }

#endif //WPP_TRACING


////////////////////
// Shared Globals //
////////////////////

extern UNICODE_STRING GlobalRegistryPath;
extern ULONG          OsrDebugLevel;

//
// Handy Dandy Time Macros
//

#define ABSOLUTE(wait) (wait)

#define RELATIVE(wait) (-(wait))

#define NANOSECONDS(nanos) \
(((signed __int64)(nanos)) / 100L)

#define MICROSECONDS(micros) \
(((signed __int64)(micros)) * NANOSECONDS(1000L))

#define MILLISECONDS(milli) \
(((signed __int64)(milli)) * MICROSECONDS(1000L))

#define SECONDS(seconds) \
(((signed __int64)(seconds)) * MILLISECONDS(1000L))

#define IRP_MN_BOGUS 0xFF


//
// We are using a quad buffered buffer for bulk 
//  transfers on the USBFX2LK firmware. Therefore,
//  we'll limit our bulk transfers to the maximum
//  packet size returned from the device * 4
//
#define USBFX2LK_BULK_TRANSFER_FW_BUFFERING 4


typedef struct _USBFX2LK_PIPE_CONTEXT {

    USBD_PIPE_INFORMATION   PipeInformation;    // Information about Pipe

} USBFX2LK_PIPE_CONTEXT, *PUSBFX2LK_PIPE_CONTEXT;

//
// PnP Device States used by Driver.
//
typedef enum _PNP_DEVICE_STATE {

    //
    // In STATE_REMOVED, we immediately fail any received I/O requests
    //
    STATE_REMOVED                   = 0x00000000,

    //
    // In STATE_SURPRISE_REMOVED, we immediately fail all incoming requests
    //
    STATE_SURPRISE_REMOVED          = 0x00010000,

    //
    // In STATE_NEVER_STARTED, we immediately fail all incoming requests
    //
    STATE_NEVER_STARTED             = 0x00020000,

    //
    // Dummy State -- When the state is < this value, no H/W access is
    // allowed
    //
    STATE_ALL_BELOW_NO_HW           = 0x00030000,   // ******************

    //
    // Dummy state -- When an IRP arrives at the driver, if the current
    // device state is below this value, it is immediately failed
    //
    STATE_ALL_BELOW_FAIL            = 0x00FF0000,   // ******************

    //
    // In STATE_STARTED, requests are processed and removed from the
    // queues normally
    //
    STATE_STARTED                   = 0x01210000,

    //
    // Dummy state -- When an IRP arrives at the driver, if the current
    // device state is above this value, it is queued, not initiated on
    // the device (even if the device is free)
    //
    STATE_ALL_ABOVE_QUEUE           = 0x0FFF0000,   // ******************

    //
    // Dummy State -- When an IRP is COMPLETED on the device, if
    // the device state is below this value, we'll start another
    // IRP in an attempt to drain the queue of pending requests.
    //
    STATE_ALL_BELOW_DRAIN           = STATE_ALL_ABOVE_QUEUE,    // ******************

    //
    // In STATE_STOP_PENDING, we queue incoming requests
    //
    STATE_STOP_PENDING              = 0x10000000,


    //
    // In STATE_REMOVE_PENDING, we queue incoming requests
    //
    STATE_REMOVE_PENDING            = 0x10010000,


    //
    // In STATE_STOPPED, we queue incoming requests
    //
    STATE_STOPPED                   = 0x10100000,

    //
    // In STATE_POWER_PROCESSING, we queue incoming requests
    //
    STATE_POWER_PROCESSING          = 0x11000000,

} PNP_DEVICESTATE, *PPNPDEVICE_STATE;

//
// Define the vendor commands supported by our device
//
#define USBFX2LK_READ_7SEGMENT_DISPLAY      0xD4
#define USBFX2LK_READ_SWITCHES              0xD6
#define USBFX2LK_READ_BARGRAPH_DISPLAY      0xD7
#define USBFX2LK_SET_BARGRAPH_DISPLAY       0xD8
#define USBFX2LK_IS_HIGH_SPEED              0xD9
#define USBFX2LK_REENUMERATE                0xDA
#define USBFX2LK_SET_7SEGMENT_DISPLAY       0xDB

//
// Define the features that we can clear
//  and set on our device
//
#define USBFX2LK_FEATURE_EPSTALL            0x00
#define USBFX2LK_FEATURE_WAKE               0x01

//
// Define the constants used in selective 
//  suspend
//

//
// Our selective suspend states
//
#define SS_NOT_STARTED              0x7777
#define SS_PROCESSING               0x8888
#define SS_SUSPENDED                0x9999

//
// The amount of time that the device should
//  be idle before suspending
//  
// We'll use 5 seconds
//
#define SS_DEVICE_IDLE_DELAY        (ABSOLUTE(SECONDS(5)))




//
// USBFx2Lk Device Extension
//
typedef struct _USBFX2LK_EXT {
    ULONG                           MagicNumber;

    // 
    // Address of Our Device Object
    //
    PDEVICE_OBJECT                  FunctionalDeviceObject;

    //
    // Address of PDO that was passed to our AddDevice Entry Point
    //
    PDEVICE_OBJECT                  PhysicalDeviceObject;

    //
    // Address of PDO that we actually attached to in our
    // AddDevice Entry Point.  This is who we forward PnP and Power
    // Irps to.
    //
    PDEVICE_OBJECT                  DeviceToSendIrpsTo;

    //
    // Name buffer for our named Functional device object link
    // The name is generated based on the driver's class GUID
    //
    UNICODE_STRING                  InterfaceName;
    ULONG                           InstanceNumber;
    BOOLEAN                         Opened;

    //
    // Bus drivers set the appropriate values in this structure in response
    // to an IRP_MN_QUERY_CAPABILITIES IRP. Function and filter drivers might
    // alter the capabilities set by the bus driver.
    //
    DEVICE_CAPABILITIES             DeviceCapabilities;
    BOOLEAN                         DeviceCapabilitiesInitialized;

    //
    // Device descriptor
    //
    PUSB_DEVICE_DESCRIPTOR          UsbDeviceDescriptor;

    //
    // Configuration Descriptor
    //
    PUSB_CONFIGURATION_DESCRIPTOR   UsbConfigurationDescriptor;

    //
    // Interface Information structure