Functions for queueung IRPs. More...

#include <wdm.h>
#include "cbm_driver.h"

Functions
VOID	QueueInit (PQUEUE Queue, PCBMDRIVER_STARTIO DriverStartIo)
	Initialize a QUEUE object. More...

NTSTATUS	QueueStartPacket (PQUEUE Queue, PIRP Irp, BOOLEAN FastStart, PDEVICE_OBJECT Fdo)
	Insert an IRP into a QUEUE object. More...

VOID	QueueStall (PQUEUE Queue)
	Sets a QUEUE into stalled state. More...

VOID	QueueUnstall (PQUEUE Queue)
	Sets a QUEUE into unstalled state. More...

BOOLEAN	QueueIsStalled (PQUEUE Queue)
	Check if a QUEUE is in stalled state. More...

BOOLEAN	QueueIsDropping (PQUEUE Queue)
	Check if a QUEUE is in DROPPING state. More...

NTSTATUS	QueueCompleteIrp (PQUEUE Queue, PIRP Irp, NTSTATUS NtStatus, ULONG_PTR Information)
	Complete an IRP which is on a QUEUE. More...

NTSTATUS	QueuePoll (PQUEUE Queue, PDEVICE_OBJECT Fdo)
	Poll the QUEUE. More...

NTSTATUS	QueueSignal (PQUEUE Queue)
	Signal to the QUEUE need for processing. More...

NTSTATUS	QueueCleanup (PQUEUE Queue, PFILE_OBJECT FileObject)
	Process an IRP_MJ_CLEANUP on the QUEUE. More...

BOOLEAN	QueueShouldCancelCurrentIrp (PQUEUE Queue)
	Should the current IRP be cancelled? More...

Detailed Description

Functions for queueung IRPs.

Author: Spiro Trikaliotis

Definition in file queue.c.

Function Documentation

NTSTATUS QueueCleanup	(	PQUEUE	Queue,
		PFILE_OBJECT	FileObject
	)

Process an IRP_MJ_CLEANUP on the QUEUE.

Whenever an IRP_MJ_CLEANUP is received by the driver, it has to complete all IRPs that belong to the given file object. This function takes all appropriate IRPs out of the QUEUE and completes them.

Parameters

Queue	Pointer to the QUEUE object.
FileObject	Pointer to the FILE_OBJECT of which the associated IRPs have to be cancelled.

Todo:: What if the current IRP is associated to that FILE_OBJECT? Will that one be cancelled separately?

Todo:: What if the current irp is associated with that FILE_OBJECT?

Definition at line 998 of file queue.c.

References FUNC_ENTER, QUEUE::IrpQueue, and QueueCompleteIrp().

Referenced by cbm_cleanup().

NTSTATUS QueueCompleteIrp	(	PQUEUE	Queue,
		PIRP	Irp,
		NTSTATUS	NtStatus,
		ULONG_PTR	Information
	)

Complete an IRP which is on a QUEUE.

This function completes an IRP which is on a QUEUE object

Parameters

Queue	Pointer to the QUEUE object, or NULL if the IRP is on no QUEUE at all.
Irp	Pointer to the Irp to be completed
NtStatus	The NTSTATUS code which is to be used for the completion
Information	The value to give the Information field of the IRP

Returns: Returns the given NtStatus

Without any further protection, the state which is reported could have changed at the time this function returns! Thus, handle with care.

Definition at line 756 of file queue.c.

References QUEUE::CurrentIrp, DBG_ASSERT, FUNC_ENTER, and PERF_EVENT_COMPLETEIRP.

Referenced by cbm_cleanup(), cbm_createopenclose(), cbm_devicecontrol(), cbm_execute_close(), cbm_execute_createopen(), cbm_execute_devicecontrol(), cbm_execute_readwrite(), cbm_readwrite(), QueueCleanup(), and QueueStartPacket().

VOID QueueInit	(	PQUEUE	Queue,
		PCBMDRIVER_STARTIO	DriverStartIo
	)

Initialize a QUEUE object.

This function initializes a QUEUE object before it can be used by the other Queue...() functions.

Parameters

Queue	Pointer to the QUEUE object.
DriverStartIo	Pointer to the StartIo function for this queue

Definition at line 388 of file queue.c.

References QUEUE::DriverStartIo, FUNC_ENTER, FUNC_LEAVE, QUEUE::IrpListHead, QUEUE::IrpListSpinlock, QUEUE::IrpQueue, QUEUE::IsDropping, QUEUE::IsStalled, and QUEUE::NotEmptyEvent.

Referenced by AddDeviceCommonInit().

BOOLEAN QueueIsDropping ( PQUEUE Queue )

Check if a QUEUE is in DROPPING state.

This function checks if the given QUEUE is in the DROPPING state.

Parameters

Queue Pointer to the QUEUE object.

Returns: TRUE if the QUEUE is currently dropping, FALSE else.

A QUEUE is in the DROPPING state if it does not take any new IRP, but completes it immediately with a given completion status.

Without any further protection, the state which is reported could have changed at the time this function returns! Thus, handle with care.

This function is needed for correct PnP management. As currently, we do not do any PnP, this function is unused currently.

Bug:: Currently, there is no function for setting a Queue into dropping state. So, this function is not needed at all (yet).

Definition at line 718 of file queue.c.

References FUNC_ENTER, FUNC_LEAVE_BOOLEAN, and QUEUE::IsDropping.

BOOLEAN QueueIsStalled ( PQUEUE Queue )

Check if a QUEUE is in stalled state.

This function cheks if the given QUEUE is in the stalled state.

Parameters

Queue Pointer to the QUEUE object.

Returns: TRUE if the QUEUE is currently stalled, FALSE else.

Without any further protection, the state which is reported could have changed at the time this function returns! Thus, handle with care. This means, the caller has to make sure that QueueIsStalled() cannot compete with QueueStall() and/or QueueUnstall().

Definition at line 679 of file queue.c.

References FUNC_ENTER, FUNC_LEAVE_BOOLEAN, and QUEUE::IsStalled.

NTSTATUS QueuePoll	(	PQUEUE	Queue,
		PDEVICE_OBJECT	Fdo
	)

Poll the QUEUE.

This function polls the QUEUE object. If there is an IRP in there, the IRP is executed by calling the specified DriverStartIo() function.

If there is no IRP, this function just sleeps until there is one.

Parameters

Queue	Pointer to the QUEUE object.
Fdo	Pointer to the DEVICE_OBJECT on which the Queue is located. This parameter is given to the call of StartIo().

Bug:: This function does not perform any synchronization other than what ExInterlockedRemoveHeadList() provides. Because of this, it is not safe to be used directly from a driver.

Definition at line 816 of file queue.c.

References QUEUE::CurrentIrp, DBG_ASSERT, QUEUE::DriverStartIo, FUNC_ENTER, and QUEUE::NotEmptyEvent.

Referenced by cbm_thread().

BOOLEAN QueueShouldCancelCurrentIrp ( PQUEUE Queue )

Should the current IRP be cancelled?

Find out if the caller of the current IRP is not interested anymore in the result.

Parameters

Queue Pointer to the QUEUE object.

This function should be called in the processing of an IRP whenever there is a change that some processing will take some considerable time. An alternative to polling this function is to install a cancel routine.

Definition at line 1041 of file queue.c.

References QUEUE::CurrentIrp, FUNC_ENTER, and FUNC_LEAVE_BOOLEAN.

Referenced by cbmiec_i_raw_read(), cbmiec_i_raw_write(), cbmiec_iec_wait(), cbmiec_parallel_burst_read(), cbmiec_parallel_burst_read_track(), cbmiec_parallel_burst_read_track_var(), cbmiec_parallel_burst_write(), and cbmiec_wait_for_listener().

NTSTATUS QueueSignal ( PQUEUE Queue )

Signal to the QUEUE need for processing.

This function signals the QUEUE object that there is something to be processed. In general, this means that some IRP has been queued.

Parameters

Queue Pointer to the QUEUE object.

Definition at line 900 of file queue.c.

References FUNC_ENTER, and QUEUE::NotEmptyEvent.

Referenced by cbm_stop_thread(), and QueueStartPacket().

VOID QueueStall ( PQUEUE Queue )

Sets a QUEUE into stalled state.

This function unconditionally stalls the given QUEUE.

Parameters

Queue Pointer to the QUEUE object.

This function is not to be called recursively.

This function is needed for correct PnP management. As currently, we do not do any PnP, this function is unused currently.

Definition at line 615 of file queue.c.

References DBG_ASSERT, FUNC_ENTER, FUNC_LEAVE, and QUEUE::IsStalled.

NTSTATUS QueueStartPacket	(	PQUEUE	Queue,
		PIRP	Irp,
		BOOLEAN	FastStart,
		PDEVICE_OBJECT	Fdo
	)

Insert an IRP into a QUEUE object.

This function inserts an IRP into the given QUEUE object.

Parameters

Queue	Pointer to the QUEUE object.
Irp	Pointer to the IRP to be queued.
FastStart	If this value is TRUE, than this IRP does not last long. Thus, it can be started immediately if the QUEUE is empty. If this value is FALSE, this IRP can take much time, so a fast start is not allowed
Fdo	Pointer to the DEVICE_OBJECT. This is only needed if FastStart is TRUE.

Returns: If the IRP has been successfully inserted into the QUEUE, this function returns STATUS_PENDING. If the IRP could not be inserted, it returns the status code given by the abortion status.

If the queue is in the dropping state, this function does not insert the IRP into the queue, but it immediately completes the IRP with the given abortion status.

The return value can be directly used in the dispatch function which calls QueueStartPacket() as the return status.

Definition at line 467 of file queue.c.

References QUEUE::CurrentIrp, DBG_ASSERT, QUEUE::DriverStartIo, QUEUE::DroppingReturnStatus, FUNC_ENTER, QUEUE::IrpQueue, QUEUE::IsDropping, QueueCompleteIrp(), and QueueSignal().

Referenced by cbm_createopenclose(), cbm_devicecontrol(), and cbm_readwrite().

VOID QueueUnstall ( PQUEUE Queue )

Sets a QUEUE into unstalled state.

This function unstalls the given QUEUE.

Parameters

Queue Pointer to the QUEUE object.

This function is not to be called recursively.

This function is needed for correct PnP management. As currently, we do not do any PnP, this function is unused currently.

Definition at line 644 of file queue.c.

References DBG_ASSERT, FUNC_ENTER, FUNC_LEAVE, and QUEUE::IsStalled.