/*++

Copyright (c) Microsoft Corporation

Module Name:

    FxIrpQueue.hpp

Abstract:

    This module implements a common queue structure for the
    driver frameworks built around the Cancel Safe Queues pattern

Author:






Environment:

    Both kernel and user mode

Revision History:


--*/

#ifndef _FXIRPQUEUE_H_
#define _FXIRPQUEUE_H_

#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
#include "fxirpkm.hpp"
#else
#include "fxirpum.hpp"
#endif


//
// IRP DriverContext[] entry used.
//
// We use the same entry that the CSQ package does
// which is OK since we can't use CSQ if we implement the
// cancel handler ourselves
//
#define FX_IRP_QUEUE_CSQ_CONTEXT_ENTRY 3

//
// FxIrpQueue entry identifier
//
#define FX_IRP_QUEUE_ENTRY_IDENTIFIER 1

#if ((FX_CORE_MODE)==(FX_CORE_KERNEL_MODE))
#include "fxirpkm.hpp"
#elif ((FX_CORE_MODE)==(FX_CORE_USER_MODE))
#include "fxirpum.hpp"
#endif


//
// This is the cancel function callback for the IrpQueue to its caller/parent
// This is called holding the lock of the object owning the IrpQueue, and it
// is responsible for completing the IRP.
//

extern "C" {
__drv_functionClass(EVT_IRP_QUEUE_CANCEL)
__drv_requiresIRQL(DISPATCH_LEVEL)
typedef
VOID
EVT_IRP_QUEUE_CANCEL (
    __in FxIrpQueue* Queue,
    __in MdIrp        Irp,
    __in PMdIoCsqIrpContext pCsqContext,
    __in KIRQL CallerIrql
    );

typedef EVT_IRP_QUEUE_CANCEL *PFN_IRP_QUEUE_CANCEL;
}

class FxIrpQueue {

    friend VOID GetTriageInfo(VOID);

private:

    //
    // The Queue
    //
    LIST_ENTRY        m_Queue;

    //
    // The object whose lock controls the queue.
    // Provided by the client object.
    //
    FxNonPagedObject* m_LockObject;

    //
    // Callers registered cancel callback
    //
    PFN_IRP_QUEUE_CANCEL m_CancelCallback;

    //
    // Count of requests in the Queue
    //
    LONG              m_RequestCount;

public:

    FxIrpQueue(
        VOID
        );

    ~FxIrpQueue(
        VOID
        );

    VOID
    Initialize(
        __in FxNonPagedObject* LockObject,
        __in PFN_IRP_QUEUE_CANCEL Callback
        );

    _Must_inspect_result_
    NTSTATUS
    InsertTailRequest(
        __inout MdIrp Irp,
        __in_opt PMdIoCsqIrpContext CsqContext,
        __out_opt ULONG* pRequestCount
        );

    _Must_inspect_result_
    NTSTATUS
    InsertHeadRequest(
        __inout MdIrp Irp,
        __in_opt PMdIoCsqIrpContext CsqContext,
        __out_opt ULONG* pRequestCount
        );

    MdIrp
    GetNextRequest(
        __out PMdIoCsqIrpContext* pCsqContext
        );

    _Must_inspect_result_
    NTSTATUS
    GetNextRequest(
        __in_opt  PMdIoCsqIrpContext  TagContext,
        __in_opt  MdFileObject         FileObject,
        __out FxRequest**          ppOutRequest
        );

    _Must_inspect_result_
    NTSTATUS
    PeekRequest(
        __in_opt PMdIoCsqIrpContext  TagContext,
        __in_opt MdFileObject         FileObject,
        __out FxRequest**          ppOutRequest
        );

    MdIrp
    RemoveRequest(
        __in PMdIoCsqIrpContext Context
        );

    //
    // Return whether the queue is empty
    // (for optimizing the non-pending case in the caller)
    //
    inline
    BOOLEAN
    IsQueueEmpty() {

        if( IsListEmpty(&m_Queue) ) {

            ASSERT(m_RequestCount == 0);

            return TRUE;
        }
        else {
            ASSERT(m_RequestCount != 0);

            return FALSE;
        }
    }

    //
    // Return count of queued and driver pending requests.
    //
    inline
    LONG
    GetRequestCount() {
        return m_RequestCount;
    }

    BOOLEAN
    IsIrpInQueue(
        __in PMdIoCsqIrpContext Context
        );


private:

    //
    // Insert an IRP on the cancel list
    //
    _Must_inspect_result_
    NTSTATUS
    InsertIrpInQueue(
        __inout   MdIrp                Irp,
        __in_opt  PMdIoCsqIrpContext Context,
        __in      BOOLEAN             InsertInHead,
        __out_opt ULONG*              pRequestCount
        );

    // Do not specify argument names
    FX_DECLARE_VF_FUNCTION_P1(
    VOID,
    VerifyRemoveIrpFromQueueByContext,
        __in PMdIoCsqIrpContext
        );

    //
    // Ask to remove an IRP from the cancel list by Context,
    // and return NULL if its been cancelled
    //
    MdIrp
    RemoveIrpFromQueueByContext(
        __in PMdIoCsqIrpContext Context
        );

    //
    // Remove a request from the head of the queue if PeekContext == NULL,
    // or the next request after PeekContext if != NULL
    //
    MdIrp
    RemoveNextIrpFromQueue(
        __in_opt  PVOID                PeekContext,
        __out_opt PMdIoCsqIrpContext* pCsqContext
        );

    //
    // Peek an IRP in the queue
    //
    MdIrp
    PeekNextIrpFromQueue(
        __in_opt MdIrp  Irp,
        __in_opt PVOID  PeekContext
        );

    //
    // Unconditionally remove the IRP from the list entry
    //
    inline
    VOID
    RemoveIrpFromListEntry(
        __inout FxIrp*   Irp
        )
    {
      PLIST_ENTRY entry = Irp->ListEntry();
      RemoveEntryList(entry);
      InitializeListHead(entry);
      m_RequestCount--;
      ASSERT(m_RequestCount >= 0);
    }

    //
    // WDM IRP cancel function
    //
    static
    MdCancelRoutineType
    _WdmCancelRoutineInternal;

    //
    // Lock functions accessed from WDM cancel callback
    //
    __inline
    void
    LockFromCancel(
        __out PKIRQL PreviousIrql
        )
    {
        m_LockObject->Lock(PreviousIrql);
    }

    __inline
    void
    UnlockFromCancel(
        __in KIRQL PreviousIrql
        )
    {
        m_LockObject->Unlock(PreviousIrql);
    }
};

#endif // _FXIRPQUEUE_H