queue.c File Reference

Functions for queueung IRPs. More...

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

Go to the source code of this file.

Functions
VOID	QueueInit (PQUEUE Queue, PCBMDRIVER_STARTIO DriverStartIo)
	Initialize a QUEUE object.
NTSTATUS	QueueStartPacket (PQUEUE Queue, PIRP Irp, BOOLEAN FastStart, PDEVICE_OBJECT Fdo)
	Insert an IRP into a QUEUE object.
VOID	QueueStall (PQUEUE Queue)
	Sets a QUEUE into stalled state.
VOID	QueueUnstall (PQUEUE Queue)
	Sets a QUEUE into unstalled state.
NTSTATUS	QueueCompleteIrp (PQUEUE Queue, PIRP Irp, NTSTATUS NtStatus, ULONG_PTR Information)
	Complete an IRP which is on a QUEUE.
NTSTATUS	QueuePoll (PQUEUE Queue, PDEVICE_OBJECT Fdo)
	Poll the QUEUE.
NTSTATUS	QueueSignal (PQUEUE Queue)
	Signal to the QUEUE need for processing.
NTSTATUS	QueueCleanup (PQUEUE Queue, PFILE_OBJECT FileObject)
	Process an IRP_MJ_CLEANUP on the QUEUE.
BOOLEAN	QueueShouldCancelCurrentIrp (PQUEUE Queue)
	Should the current IRP be cancelled?

---

Detailed Description

Functions for queueung IRPs.

**************************************************************

Author:

Spiro Trikaliotis

Version:

Id

queue.c,v 1.29 2006/03/09 11:24:26 trikalio Exp

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 999 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 757 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 389 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 817 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 1042 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(), 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 901 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 616 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 468 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 645 of file queue.c. References DBG_ASSERT, FUNC_ENTER, FUNC_LEAVE, and QUEUE::IsStalled.

---