csq.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_IO_CSQ_IRP_CONTEXT
struct	_IO_CSQ

Macros
#define	_CSQ_H_
#define	IO_TYPE_CSQ_IRP_CONTEXT   1
#define	IO_TYPE_CSQ   2
#define	IO_TYPE_CSQ_EX   3

Typedefs
typedef struct _IO_CSQ	IO_CSQ
typedef struct _IO_CSQ *	PIO_CSQ
typedef struct _IO_CSQ_IRP_CONTEXT	IO_CSQ_IRP_CONTEXT
typedef struct _IO_CSQ_IRP_CONTEXT *	PIO_CSQ_IRP_CONTEXT
typedef _In_ PIRP	Irp
typedef IO_CSQ_INSERT_IRP *	PIO_CSQ_INSERT_IRP
typedef IO_CSQ_REMOVE_IRP *	PIO_CSQ_REMOVE_IRP
typedef _In_opt_ PIRP _In_opt_ PVOID	PeekContext
typedef IO_CSQ_PEEK_NEXT_IRP *	PIO_CSQ_PEEK_NEXT_IRP
typedef _Out_ PKIRQL	Irql
typedef IO_CSQ_ACQUIRE_LOCK *	PIO_CSQ_ACQUIRE_LOCK
typedef IO_CSQ_RELEASE_LOCK *	PIO_CSQ_RELEASE_LOCK
typedef IO_CSQ_COMPLETE_CANCELED_IRP *	PIO_CSQ_COMPLETE_CANCELED_IRP
typedef _In_ PIRP _In_ PVOID	InsertContext
typedef IO_CSQ_INSERT_IRP_EX *	PIO_CSQ_INSERT_IRP_EX

Functions
typedef	VOID (NTAPI IO_CSQ_INSERT_IRP)(_In_ struct _IO_CSQ *Csq
typedef	PIRP (NTAPI IO_CSQ_PEEK_NEXT_IRP)(_In_ struct _IO_CSQ *Csq
typedef	NTSTATUS (NTAPI IO_CSQ_INSERT_IRP_EX)(_In_ struct _IO_CSQ *Csq
NTKERNELAPI NTSTATUS NTAPI	IoCsqInitialize (_Out_ PIO_CSQ Csq, _In_ PIO_CSQ_INSERT_IRP CsqInsertIrp, _In_ PIO_CSQ_REMOVE_IRP CsqRemoveIrp, _In_ PIO_CSQ_PEEK_NEXT_IRP CsqPeekNextIrp, _In_ PIO_CSQ_ACQUIRE_LOCK CsqAcquireLock, _In_ PIO_CSQ_RELEASE_LOCK CsqReleaseLock, _In_ PIO_CSQ_COMPLETE_CANCELED_IRP CsqCompleteCanceledIrp)
	Set up a CSQ struct to initialize the queue. More...
NTKERNELAPI NTSTATUS NTAPI	IoCsqInitializeEx (_Out_ PIO_CSQ Csq, _In_ PIO_CSQ_INSERT_IRP_EX CsqInsertIrpEx, _In_ PIO_CSQ_REMOVE_IRP CsqRemoveIrp, _In_ PIO_CSQ_PEEK_NEXT_IRP CsqPeekNextIrp, _In_ PIO_CSQ_ACQUIRE_LOCK CsqAcquireLock, _In_ PIO_CSQ_RELEASE_LOCK CsqReleaseLock, _In_ PIO_CSQ_COMPLETE_CANCELED_IRP CsqCompleteCanceledIrp)
	Set up a CSQ struct to initialize the queue (extended version) More...
NTKERNELAPI VOID NTAPI	IoCsqInsertIrp (_Inout_ PIO_CSQ Csq, _Inout_ PIRP Irp, _Out_opt_ PIO_CSQ_IRP_CONTEXT Context)
	Insert an IRP into the CSQ. More...
NTKERNELAPI NTSTATUS NTAPI	IoCsqInsertIrpEx (_Inout_ PIO_CSQ Csq, _Inout_ PIRP Irp, _Out_opt_ PIO_CSQ_IRP_CONTEXT Context, _In_opt_ PVOID InsertContext)
	Insert an IRP into the CSQ, with additional tracking context. More...
NTKERNELAPI PIRP NTAPI	IoCsqRemoveIrp (_Inout_ PIO_CSQ Csq, _Inout_ PIO_CSQ_IRP_CONTEXT Context)
	Remove anb IRP from the queue. More...
NTKERNELAPI PIRP NTAPI	IoCsqRemoveNextIrp (_Inout_ PIO_CSQ Csq, _In_opt_ PVOID PeekContext)
	IoCsqRemoveNextIrp - Removes the next IRP from the queue. More...

Macro Definition Documentation

_CSQ_H_

#define _CSQ_H_

Definition at line 57 of file csq.h.

IO_TYPE_CSQ

#define IO_TYPE_CSQ   2

Definition at line 79 of file csq.h.

IO_TYPE_CSQ_EX

#define IO_TYPE_CSQ_EX   3

Definition at line 238 of file csq.h.

IO_TYPE_CSQ_IRP_CONTEXT

#define IO_TYPE_CSQ_IRP_CONTEXT   1

Definition at line 78 of file csq.h.

Typedef Documentation

InsertContext

typedef _In_ PIRP _In_ PVOID InsertContext

Definition at line 257 of file csq.h.

IO_CSQ

typedef struct _IO_CSQ IO_CSQ

Definition at line 69 of file csq.h.

IO_CSQ_IRP_CONTEXT

typedef struct _IO_CSQ_IRP_CONTEXT IO_CSQ_IRP_CONTEXT

Irp

_Must_inspect_result_ _In_ WDFDEVICE _In_ PIRP Irp

Initial value:

{
    return ((PFN_WDFDEVICEWDMDISPATCHPREPROCESSEDIRP) WdfFunctions[WdfDeviceWdmDispatchPreprocessedIrpTableIndex])(WdfDriverGlobals, Device, Irp)

Definition at line 116 of file csq.h.

Irql

typedef _In_ KIRQL Irql

Definition at line 179 of file csq.h.

PeekContext

typedef _In_opt_ PIRP _In_opt_ PVOID PeekContext

Definition at line 159 of file csq.h.

PIO_CSQ

typedef struct _IO_CSQ * PIO_CSQ

Definition at line 69 of file csq.h.

PIO_CSQ_ACQUIRE_LOCK

typedef IO_CSQ_ACQUIRE_LOCK* PIO_CSQ_ACQUIRE_LOCK

Definition at line 180 of file csq.h.

PIO_CSQ_COMPLETE_CANCELED_IRP

typedef IO_CSQ_COMPLETE_CANCELED_IRP* PIO_CSQ_COMPLETE_CANCELED_IRP

Definition at line 217 of file csq.h.

PIO_CSQ_INSERT_IRP

typedef IO_CSQ_INSERT_IRP* PIO_CSQ_INSERT_IRP

Definition at line 117 of file csq.h.

PIO_CSQ_INSERT_IRP_EX

typedef IO_CSQ_INSERT_IRP_EX* PIO_CSQ_INSERT_IRP_EX

Definition at line 259 of file csq.h.

PIO_CSQ_IRP_CONTEXT

typedef struct _IO_CSQ_IRP_CONTEXT * PIO_CSQ_IRP_CONTEXT

PIO_CSQ_PEEK_NEXT_IRP

typedef IO_CSQ_PEEK_NEXT_IRP* PIO_CSQ_PEEK_NEXT_IRP

Definition at line 161 of file csq.h.

PIO_CSQ_RELEASE_LOCK

typedef IO_CSQ_RELEASE_LOCK* PIO_CSQ_RELEASE_LOCK

Definition at line 196 of file csq.h.

PIO_CSQ_REMOVE_IRP

typedef IO_CSQ_REMOVE_IRP* PIO_CSQ_REMOVE_IRP

Definition at line 135 of file csq.h.

Function Documentation

IoCsqInitialize()

NTKERNELAPI NTSTATUS NTAPI IoCsqInitialize	(	_Out_ PIO_CSQ	Csq,
		_In_ PIO_CSQ_INSERT_IRP	CsqInsertIrp,
		_In_ PIO_CSQ_REMOVE_IRP	CsqRemoveIrp,
		_In_ PIO_CSQ_PEEK_NEXT_IRP	CsqPeekNextIrp,
		_In_ PIO_CSQ_ACQUIRE_LOCK	CsqAcquireLock,
		_In_ PIO_CSQ_RELEASE_LOCK	CsqReleaseLock,
		_In_ PIO_CSQ_COMPLETE_CANCELED_IRP	CsqCompleteCanceledIrp
	)

Set up a CSQ struct to initialize the queue.

Parameters

Csq	- Caller-allocated non-paged space for our IO_CSQ to be initialized
CsqInsertIrp	- Insert routine
CsqRemoveIrp	- Remove routine
CsqPeekNextIrp	- Routine to paeek at the next IRP in queue
CsqAcquireLock	- Acquire the queue's lock
CsqReleaseLock	- Release the queue's lock
CsqCompleteCanceledIrp	- Routine to complete IRPs when they are canceled

Returns

• STATUS_SUCCESS in all cases

Note

• Csq must be non-paged, as the queue is manipulated with a held spinlock

Definition at line 103 of file csq.c.

{
    Csq->Type = IO_TYPE_CSQ;
    Csq->CsqInsertIrp = CsqInsertIrp;
    Csq->CsqRemoveIrp = CsqRemoveIrp;
    Csq->CsqPeekNextIrp = CsqPeekNextIrp;
    Csq->CsqAcquireLock = CsqAcquireLock;
    Csq->CsqReleaseLock = CsqReleaseLock;
    Csq->CsqCompleteCanceledIrp = CsqCompleteCanceledIrp;
    Csq->ReservePointer = NULL;

    return STATUS_SUCCESS;
}

Referenced by DriverEntry(), MsfsCreateMailslot(), and USBPORT_StartDevice().

IoCsqInitializeEx()

NTKERNELAPI NTSTATUS NTAPI IoCsqInitializeEx	(	_Out_ PIO_CSQ	Csq,
		_In_ PIO_CSQ_INSERT_IRP_EX	CsqInsertIrpEx,
		_In_ PIO_CSQ_REMOVE_IRP	CsqRemoveIrp,
		_In_ PIO_CSQ_PEEK_NEXT_IRP	CsqPeekNextIrp,
		_In_ PIO_CSQ_ACQUIRE_LOCK	CsqAcquireLock,
		_In_ PIO_CSQ_RELEASE_LOCK	CsqReleaseLock,
		_In_ PIO_CSQ_COMPLETE_CANCELED_IRP	CsqCompleteCanceledIrp
	)

Set up a CSQ struct to initialize the queue (extended version)

Parameters

Csq	- Caller-allocated non-paged space for our IO_CSQ to be initialized
CsqInsertIrpEx	- Extended insert routine
CsqRemoveIrp	- Remove routine
CsqPeekNextIrp	- Routine to paeek at the next IRP in queue
CsqAcquireLock	- Acquire the queue's lock
CsqReleaseLock	- Release the queue's lock
CsqCompleteCanceledIrp	- Routine to complete IRPs when they are canceled

Returns

• STATUS_SUCCESS in all cases

Note

• Csq must be non-paged, as the queue is manipulated with a held spinlock

Definition at line 143 of file csq.c.

{
    Csq->Type = IO_TYPE_CSQ_EX;
    Csq->CsqInsertIrp = (PIO_CSQ_INSERT_IRP)CsqInsertIrpEx;
    Csq->CsqRemoveIrp = CsqRemoveIrp;
    Csq->CsqPeekNextIrp = CsqPeekNextIrp;
    Csq->CsqAcquireLock = CsqAcquireLock;
    Csq->CsqReleaseLock = CsqReleaseLock;
    Csq->CsqCompleteCanceledIrp = CsqCompleteCanceledIrp;
    Csq->ReservePointer = NULL;

    return STATUS_SUCCESS;
}

Referenced by FsRtlPrivateLock(), and InitializeMessageWaiterQueue().

IoCsqInsertIrp()

NTKERNELAPI VOID NTAPI IoCsqInsertIrp	(	_Inout_ PIO_CSQ	Csq,
		_Inout_ PIRP	Irp,
		_Out_opt_ PIO_CSQ_IRP_CONTEXT	Context
	)

Insert an IRP into the CSQ.

Parameters

Csq	- Pointer to the initialized CSQ
Irp	- Pointer to the IRP to queue
Context	- Context record to track the IRP while queued

Returns

• Just passes through to IoCsqInsertIrpEx, with no InsertContext

Definition at line 177 of file csq.c.

{
    IoCsqInsertIrpEx(Csq, Irp, Context, 0);
}

Referenced by DeviceIoctl(), DispatchReadWrite(), MsfsRead(), ReadWrite(), USBPORT_DoIdleNotificationCallback(), USBPORT_HandleSubmitURB(), and USBPORT_IdleNotification().

IoCsqInsertIrpEx()

NTKERNELAPI NTSTATUS NTAPI IoCsqInsertIrpEx	(	_Inout_ PIO_CSQ	Csq,
		_Inout_ PIRP	Irp,
		_Out_opt_ PIO_CSQ_IRP_CONTEXT	Context,
		_In_opt_ PVOID	InsertContext
	)

Insert an IRP into the CSQ, with additional tracking context.

Parameters

Csq	- Pointer to the initialized CSQ
Irp	- Pointer to the IRP to queue
Context	- Context record to track the IRP while queued
InsertContext	- additional data that is passed through to CsqInsertIrpEx

Note

• Passes the additional context through to the driver-supplied callback, which can be used with more sophistocated queues
• Marks the IRP pending in all cases
• Guaranteed to not queue a canceled IRP
• This is complicated logic, and is patterend after the Microsoft library. I'm sure I have gotten the details wrong on a fine point or two, but basically this works with the MS-supplied samples.

Definition at line 205 of file csq.c.

{
    NTSTATUS Retval = STATUS_SUCCESS;
    KIRQL Irql;

    Csq->CsqAcquireLock(Csq, &Irql);

    do
    {
        /* mark all irps pending -- says so in the cancel sample */
        IoMarkIrpPending(Irp);

        /* set up the context if we have one */
        if(Context)
        {
            Context->Type = IO_TYPE_CSQ_IRP_CONTEXT;
            Context->Irp = Irp;
            Context->Csq = Csq;
            Irp->Tail.Overlay.DriverContext[3] = Context;
        }
        else
            Irp->Tail.Overlay.DriverContext[3] = Csq;

        /*
         * NOTE!  This is very sensitive to order.  If you set the cancel routine
         * *before* you queue the IRP, our cancel routine will get called back for
         * an IRP that isn't in its queue.
         *
         * There are three possibilities:
         * 1) We get an IRP, we queue it, and it is valid the whole way
         * 2) We get an IRP, and the IO manager cancels it before we're done here
         * 3) We get an IRP, queue it, and the IO manager cancels it.
         *
         * #2 is is a booger.
         *
         * When the IO manger receives a request to cancel an IRP, it sets the cancel
         * bit in the IRP's control byte to TRUE.  Then, it looks to see if a cancel
         * routine is set.  If it isn't, the IO manager just returns to the caller.
         * If there *is* a routine, it gets called.
         *
         * If we test for cancel first and then set the cancel routine, there is a spot
         * between test and set that the IO manager can cancel us without our knowledge,
         * so we miss a cancel request.  That is bad.
         *
         * If we set a routine first and then test for cancel, we race with our completion
         * routine:  We set the routine, the IO Manager sets cancel, we test cancel and find
         * it is TRUE.  Meanwhile the IO manager has called our cancel routine already, so
         * we can't complete the IRP because it'll rip it out from under the cancel routine.
         *
         * The IO manager does us a favor though: it nulls out the cancel routine in the IRP
         * before calling it.  Therefore, if we test to see if the cancel routine is NULL
         * (after we have just set it), that means our own cancel routine is already working
         * on the IRP, and we can just return quietly.  Otherwise, we have to de-queue the
         * IRP and cancel it ourselves.
         *
         * We have to go through all of this mess because this API guarantees that we will
         * never return having left a canceled IRP in the queue.
         */

        /* Step 1: Queue the IRP */
        if(Csq->Type == IO_TYPE_CSQ)
            Csq->CsqInsertIrp(Csq, Irp);
        else
        {
            PIO_CSQ_INSERT_IRP_EX pCsqInsertIrpEx = (PIO_CSQ_INSERT_IRP_EX)Csq->CsqInsertIrp;
            Retval = pCsqInsertIrpEx(Csq, Irp, InsertContext);
            if(Retval != STATUS_SUCCESS)
                break;
        }

        /* Step 2: Set our cancel routine */
        (void)IoSetCancelRoutine(Irp, IopCsqCancelRoutine);

        /* Step 3: Deal with an IRP that is already canceled */
        if(!Irp->Cancel)
            break;

        /*
         * Since we're canceled, see if our cancel routine is already running
         * If this is NULL, the IO Manager has already called our cancel routine
         */
        if(!IoSetCancelRoutine(Irp, NULL))
            break;


        Irp->Tail.Overlay.DriverContext[3] = 0;

        /* OK, looks like we have to de-queue and complete this ourselves */
        Csq->CsqRemoveIrp(Csq, Irp);
        Csq->CsqCompleteCanceledIrp(Csq, Irp);

        if(Context)
            Context->Irp = NULL;
    }
    while(0);

    Csq->CsqReleaseLock(Csq, Irql);

    return Retval;
}

Referenced by FsRtlFastUnlockSingle(), and FsRtlPrivateLock().

IoCsqRemoveIrp()

NTKERNELAPI PIRP NTAPI IoCsqRemoveIrp	(	_Inout_ PIO_CSQ	Csq,
		_Inout_ PIO_CSQ_IRP_CONTEXT	Context
	)

Remove anb IRP from the queue.

Parameters

Csq	- Queue to remove the IRP from
Context	- Context record containing the IRP to be dequeued

Returns

• Pointer to an IRP if we found it

Note

• Don't forget that we can be canceled any time up to the point where we unset our cancel routine

Definition at line 326 of file csq.c.

{
    KIRQL Irql;
    PIRP Irp = NULL;

    Csq->CsqAcquireLock(Csq, &Irql);

    do
    {
        /* It's possible that this IRP could have been canceled */
        Irp = Context->Irp;

        if(!Irp)
            break;

        ASSERT(Context->Csq == Csq);

        /* Unset the cancel routine and see if it has already been canceled */
        if(!IoSetCancelRoutine(Irp, NULL))
        {
            /*
             * already gone, return NULL  --> NOTE  that we cannot touch this IRP *or* the context,
             * since the context is being simultaneously twiddled by the cancel routine
             */
            Irp = NULL;
            break;
        }

        ASSERT(Context == Irp->Tail.Overlay.DriverContext[3]);

        /* This IRP is valid and is ours.  Dequeue it, fix it up, and return */
        Csq->CsqRemoveIrp(Csq, Irp);

        Context = (PIO_CSQ_IRP_CONTEXT)InterlockedExchangePointer(&Irp->Tail.Overlay.DriverContext[3], NULL);

        if (Context && Context->Type == IO_TYPE_CSQ_IRP_CONTEXT)
        {
            Context->Irp = NULL;

            ASSERT(Context->Csq == Csq);
        }

        Irp->Tail.Overlay.DriverContext[3] = 0;
    }
    while(0);

    Csq->CsqReleaseLock(Csq, Irql);

    return Irp;
}

Referenced by MsfsTimeout().

IoCsqRemoveNextIrp()

NTKERNELAPI PIRP NTAPI IoCsqRemoveNextIrp	(	_Inout_ PIO_CSQ	Csq,
		_In_opt_ PVOID	PeekContext
	)

IoCsqRemoveNextIrp - Removes the next IRP from the queue.

Parameters

Csq	- Queue to remove the IRP from
PeekContext	- Identifier of the IRP to be removed

Returns

Pointer to the IRP that was removed, or NULL if one could not be found

Note

• This function is sensitive to yet another race condition. The basic idea is that we have to return the first IRP that we get that matches the PeekContext >that is not already canceled<. Therefore, we have to do a trick similar to the one done in Insert above.

Definition at line 398 of file csq.c.

{
    KIRQL Irql;
    PIRP Irp = NULL;
    PIO_CSQ_IRP_CONTEXT Context;

    Csq->CsqAcquireLock(Csq, &Irql);

    while((Irp = Csq->CsqPeekNextIrp(Csq, Irp, PeekContext)))
    {
        /*
         * If the cancel routine is gone, we're already canceled,
         * and are spinning on the queue lock in our own cancel
         * routine.  Move on to the next candidate.  It'll get
         * removed by the cance routine.
         */
        if(!IoSetCancelRoutine(Irp, NULL))
            continue;

        Csq->CsqRemoveIrp(Csq, Irp);

        /* Unset the context stuff and return */
        Context = (PIO_CSQ_IRP_CONTEXT)InterlockedExchangePointer(&Irp->Tail.Overlay.DriverContext[3], NULL);

        if (Context && Context->Type == IO_TYPE_CSQ_IRP_CONTEXT)
        {
            Context->Irp = NULL;

            ASSERT(Context->Csq == Csq);
        }

        Irp->Tail.Overlay.DriverContext[3] = 0;

        break;
    }

    Csq->CsqReleaseLock(Csq, Irql);

    return Irp;
}

Referenced by DispatchCreateCloseCleanup(), DispatchIoctl(), FsRtlFastUnlockSingle(), FsRtlUninitializeFileLock(), MsfsWrite(), QueueThread(), USBPORT_BadRequestFlush(), USBPORT_CompletePendingIdleIrp(), and USBPORT_DoIdleNotificationCallback().

NTSTATUS()

typedef NTSTATUS

(

NTAPI

IO_CSQ_INSERT_IRP_EX

)

PIRP()

typedef PIRP

(

NTAPI

IO_CSQ_PEEK_NEXT_IRP

)

VOID()

typedef VOID

(

NTAPI

IO_CSQ_INSERT_IRP

)