///////////////////////////////////////////////////////////////////////////////
//
//    (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_Queue.cpp
//
//    ABSTRACT:
//
//      This file contains the routines that handle cancel processing for the 
//      OSR USB FX2 Learning Kit device driver
//
//    AUTHOR(S):
//
//      OSR Open Systems Resources, Inc.
// 
///////////////////////////////////////////////////////////////////////////////
#include "usbfx2lk.h"

#ifdef WPP_TRACING
//
// Include the necessary tmh file - this is 
//  just a matter of course if you're using WPP tracing.
//
extern "C" {
#include "usbfx2lk_queue.tmh"
}

#endif // WPP_TRACING



///////////////////////////////////////////////////////////////////////////////
//
// OsrCsqInsertIoIrp
//
//  This routine is called by the cancel safe queue library
//   when it has a new Irp for us to queue
//
//
//  INPUTS:
//
//      Csq  -  Our cancel safe queue
//
//      Irp  -  The Irp to enqueue
//
//  OUTPUTS:
//
//      None
//
//  RETURNS:
//
//      None
//
//  IRQL:
//
//      Because we're using a spinlcok for synchronization in
//       OsrCsqAcquireIoLock/OsrCsqReleaseIoLock, this 
//       routine will be called at IRQL == DISPATCH_LEVEL.. 
//
//  CONTEXT:
//
//      Arbitrary
//
//  NOTES:
//
//      **Enters and exits with the CancelSafeWriteLock held**
//
///////////////////////////////////////////////////////////////////////////////
#ifdef W2K3
NTSTATUS OsrCsqInsertIoIrpEx(PIO_CSQ Csq,PIRP Irp,PVOID InsertContext)
#else // W2K3
VOID OsrCsqInsertIoIrp(PIO_CSQ Csq,PIRP Irp) 
#endif // W2K3
{
    PUSBFX2LK_EXT      devExt;
//    PIO_STACK_LOCATION ioStack = IoGetCurrentIrpStackLocation(Irp);;

    //
    // We should never be here and not at DISPATCH_LEVEL
    //
    ASSERT(KeGetCurrentIrql() == DISPATCH_LEVEL);

    //
    // Get a pointer to our device extension...
    // 
#ifdef W2K3
    devExt = (PUSBFX2LK_EXT) InsertContext;
#else // W2K3
    devExt = (PUSBFX2LK_EXT)CONTAINING_RECORD(Csq,USBFX2LK_EXT,CancelSafeIoQueue);
#endif //W2K3


    OsrTracePrint(TRACE_LEVEL_INFORMATION,OSRDBG_READWRITE,
                 ("OsrCsqInsertIoIrp: Inserting Irp 0x%p into the cancel safe queue...\n",
                 Irp));


    //
    // Insert this entry into our write queue. No extra synchronization
    //  needs to be done here since this call will be wrapped in calls
    //  to OsrCsqAcquireIoLock/OsrCsqReleaseIoLock by the CSQ
    //  library...
    //
    InsertTailList(&devExt->IoQueue, &Irp->Tail.Overlay.ListEntry);

#ifdef W2K3
    return STATUS_SUCCESS;
#else // W2K3
    return;
#endif // W2K3
}


///////////////////////////////////////////////////////////////////////////////
//
// OsrCsqRemoveIoIrp
//
//  This routine is called by the cancel safe queue library
//   when it wamts is to remove a Irp from our queue
//
//
//  INPUTS:
//
//      Csq  -  Our cancel safe queue
//
//      Irp  -  The Irp to dequeue
//
//
//  OUTPUTS:
//
//      None
//
//  RETURNS:
//
//      None
//
//  IRQL:
//
//      Because we're using a spinlcok for synchronization in
//       OsrCsqAcquireIoLock/OsrCsqReleaseIoLock, this 
//       routine will be called at IRQL == DISPATCH_LEVEL.. 
//
//  CONTEXT:
//
//      Arbitrary
//
//  NOTES:
//
//      **Enters and exits with the CancelSafeIoLock held**
//
//
///////////////////////////////////////////////////////////////////////////////
VOID OsrCsqRemoveIoIrp(PIO_CSQ Csq,PIRP Irp) 
{

    UNREFERENCED_PARAMETER(Csq);

    //
    // We should never be here and not at DISPATCH_LEVEL
    //
    ASSERT(KeGetCurrentIrql() == DISPATCH_LEVEL);


    OsrTracePrint(TRACE_LEVEL_INFORMATION,OSRDBG_READWRITE, 
        ("OsrCsqRemoveIoIrp: Removing Irp 0x%p from the cancel safe queue...\n",
                Irp));

    //
    // Remove this entry from our write queue. No extra synchronization
    //  needs to be done here since this call will be wrapped in calls
    //  to OsrCsqAcquireWriteLock/OsrCsqReleaseWriteLock by the CSQ
    //  library...
    //
    RemoveEntryList(&Irp->Tail.Overlay.ListEntry);

    return;

}


///////////////////////////////////////////////////////////////////////////////
//
// OsrCsqPeekNextIoIrp
//
//      We're called here when the CSQ library wants a pointer to the
//      next Irp in the queue
//
//  INPUTS:
//
//      Csq         -  Our cancel safe queue
//
//      Irp         -  The Irp to dequeue
//
//      PeekContext -  The context parameter passed to IoCsqRemoveNextIrp,
//                      in this driver it is not used
//
//  OUTPUTS:
//
//      None
//
//  RETURNS:
//
//      If there is another Irp in the queue, we return its address.
//      Otherwise we return NULL
//
//  IRQL:
//
//      Since we're using a spinlcok for synchronization in
//       OsrCsqAcquireIoLock/OsrCsqReleaseIoLock, this 
//       routine will be called at IRQL == DISPATCH_LEVEL.. 
//
//  CONTEXT:
//
//      Arbitrary
//
//  NOTES:
//
//      **Enters and exits with the CancelSafeIoLock held**
//
///////////////////////////////////////////////////////////////////////////////
PIRP OsrCsqPeekNextIoIrp(PIO_CSQ Csq,PIRP Irp,PVOID PeekContext)
{

    PUSBFX2LK_EXT   devExt;
    PIRP            nextIrp = NULL;
    PLIST_ENTRY     nextEntry;
    PLIST_ENTRY     listHead;

    //
    // We should never be here and not at DISPATCH_LEVEL
    //
    ASSERT(KeGetCurrentIrql() == DISPATCH_LEVEL);

    //
    // Get a pointer to our device extension...
    // 
    devExt = CONTAINING_RECORD(Csq,USBFX2LK_EXT,CancelSafeIoQueue);
    
    listHead = &devExt->IoQueue;

    //
    // If the Irp parameter is NULL, we start with the first Irp
    //  in the queue
    //
    if(Irp == NULL) {       

        OsrTracePrint(TRACE_LEVEL_INFORMATION,OSRDBG_READWRITE, 
                    ("OsrCsqPeekNextIoIrp: Peeking next Irp from the head of the queue...\n"));

        nextEntry = listHead->Flink;

    } else {

        //
        // Otherwise we start with the Irp after the supplied Irp
        //

        OsrTracePrint(TRACE_LEVEL_INFORMATION,OSRDBG_READWRITE, 
                    ("OsrCsqPeekNextIoIrp: Peeking next Irp starting at Irp 0x%p...\n",
                    Irp));

        nextEntry = Irp->Tail.Overlay.ListEntry.Flink;

    }
    
    while(nextEntry != listHead) {
        
        nextIrp = CONTAINING_RECORD(nextEntry, IRP, Tail.Overlay.ListEntry);

        if(PeekContext) {

            //
            // If you passed a PeekContext value when you called
            //  IoCsqRemoveNextIrp, you would do your driver
            //  defined processing here to figure out if 
            //  nextIrp matches the Irp you were looking for
            //

        } else {

            //
            // We don't have any match criteria - just return the 
            // first one we found...
            //
            break;

        }

        nextIrp = NULL;
        
        nextEntry = nextEntry->Flink;

    }