Definitions for the queueing functions. More...

Data Structures
struct	QUEUE
	A QUEUE object A QUEUE object is an object which can be used to queue IRPs for processing. This QUEUE object is optimized for being polled from an own worker thread. Anyway, a concept called FastStart is also implemented, which allows some IRPs to be completed immediately, without being queued, if no IRP is executed yet and the caller has stated that he wants this IRP to be started fast if possible. More...

Typedefs
typedef NTSTATUS(*	PCBMDRIVER_STARTIO )(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp)

typedef struct QUEUE	QUEUE
	A QUEUE object A QUEUE object is an object which can be used to queue IRPs for processing. This QUEUE object is optimized for being polled from an own worker thread. Anyway, a concept called FastStart is also implemented, which allows some IRPs to be completed immediately, without being queued, if no IRP is executed yet and the caller has stated that he wants this IRP to be started fast if possible.

typedef struct QUEUE *	PQUEUE

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

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

NTSTATUS	QueueStartPacket (PQUEUE Queue, PIRP Irp, BOOLEAN FastStart, PDEVICE_OBJECT Fdo)
	Insert an IRP into a QUEUE object. 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

Definitions for the queueing functions.

Author: Spiro Trikaliotis

Definition in file queue.h.

Typedef Documentation

typedef NTSTATUS(* PCBMDRIVER_STARTIO)(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp)

This type specifies a StartIo function for the Queue

Definition at line 28 of file queue.h.

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().

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().

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().

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation