Use only 80 character wide lines in the comments. Modified: trunk/reactos/include/ddk/csq.h _____
Modified: trunk/reactos/include/ddk/csq.h --- trunk/reactos/include/ddk/csq.h 2005-02-06 07:56:45 UTC (rev 13430) +++ trunk/reactos/include/ddk/csq.h 2005-02-06 10:01:07 UTC (rev 13431) @@ -9,34 +9,37 @@
* * BACKGROUND * - * IRP queuing is a royal pain in the butt, due to the fact that there are tons of - * built-in race conditions. IRP handling is difficult in general, but the cancel - * logic has been particularly complicated due to some subtle races, coupled - * with the fact that the system interfaces have changed over time. + * IRP queuing is a royal pain in the butt, due to the fact that there are + * tons of built-in race conditions. IRP handling is difficult in general, + * but the cancel logic has been particularly complicated due to some subtle + * races, coupled with the fact that the system interfaces have changed over + * time. * - * Walter Oney (2nd. Ed. of Programming the Windows Driver Model) states a common - * opinion among driver developers when he says that it is foolish to try to roll - * your own cancel logic. There are only a very few people who have gotten it - * right in the past. He suggests, instead, that you either use his own well-tested - * code, or use the code in the Microsoft Cancel-Safe Queue Library. + * Walter Oney (2nd. Ed. of Programming the Windows Driver Model) states a + * common opinion among driver developers when he says that it is foolish + * to try to roll your own cancel logic. There are only a very few people + * who have gotten it right in the past. He suggests, instead, that you + * either use his own well-tested code, or use the code in the Microsoft + * Cancel-Safe Queue Library. * - * We cannot do either, of course, due to copyright issues. I have therefore created - * this clone of the Microsoft library in order to concentrate all of the IRP-queuing - * bugs in one place. I'm quite sure there are problems here, so if you are a - * driver writer, I'd be glad to hear your feedback. + * We cannot do either, of course, due to copyright issues. I have therefore + * created this clone of the Microsoft library in order to concentrate all + * of the IRP-queuing bugs in one place. I'm quite sure there are problems + * here, so if you are a driver writer, I'd be glad to hear your feedback. * - * Apart from that, please try to use these routines, rather than building your own. - * If you think you have found a bug, please bring it up with me or on-list, as this - * is complicated and non-obvious stuff. Don't just change this and hope for the best! + * Apart from that, please try to use these routines, rather than building + * your own. If you think you have found a bug, please bring it up with me + * or on-list, as this is complicated and non-obvious stuff. Don't just + * change this and hope for the best! * * USAGE * * This library follows exactly the same interface as the Microsoft Cancel-Safe Queue - * routines (IoCsqXxx()). As such, the authoritative reference is the current DDK. - * There is also a DDK sample called "cancel" that has an example of how to use this - * code. I have also provided a sample driver that makes use of this queue. Finally, - * please do read the header and the source if you're curious about the inner workings - * of these routines. + * routines (IoCsqXxx()). As such, the authoritative reference is the + * current DDK. There is also a DDK sample called "cancel" that has an + * example of how to use this code. I have also provided a sample driver + * that makes use of this queue. Finally, please do read the header and the + * source if you're curious about the inner workings of these routines. */
#ifndef _REACTOS_CSQ_H @@ -48,10 +51,11 @@ /* * CSQ Callbacks * - * The cancel-safe queue is implemented as a set of IoCsqXxx() OS routines copuled - * with a set of driver callbacks to handle the basic operations of the queue. You - * need to supply one of each of these functions in your own driver. These routines - * are also documented in the DDK under CsqXxx(). That is the authoritative documentation. + * The cancel-safe queue is implemented as a set of IoCsqXxx() OS routines + * copuled with a set of driver callbacks to handle the basic operations of + * the queue. You need to supply one of each of these functions in your own + * driver. These routines are also documented in the DDK under CsqXxx(). + * That is the authoritative documentation. */
/* @@ -60,11 +64,11 @@ * * Sample implementation: * - VOID NTAPI CsqInsertIrp(PIO_CSQ Csq, PIRP Irp) - { - KdPrint(("Inserting IRP 0x%x into CSQ\n", Irp)); - InsertTailList(&IrpQueue, &Irp->Tail.Overlay.ListEntry); - } + VOID NTAPI CsqInsertIrp(PIO_CSQ Csq, PIRP Irp) + { + KdPrint(("Inserting IRP 0x%x into CSQ\n", Irp)); + InsertTailList(&IrpQueue, &Irp->Tail.Overlay.ListEntry); + } * */ typedef VOID (NTAPI *PIO_CSQ_INSERT_IRP) (struct _IO_CSQ *Csq, @@ -73,16 +77,16 @@
/* * Function to insert an IRP into the queue with extended context information. - * This is useful if you need to be able to de-queue particular IRPs more easily - * in some cases. + * This is useful if you need to be able to de-queue particular IRPs more + * easily in some cases. * * Same deal as above; sample implementation: * - NTSTATUS NTAPI CsqInsertIrpEx(PIO_CSQ Csq, PIRP Irp, PVOID InsertContext) - { - CsqInsertIrp(Csq, Irp); - return STATUS_PENDING; - } + NTSTATUS NTAPI CsqInsertIrpEx(PIO_CSQ Csq, PIRP Irp, PVOID InsertContext) + { + CsqInsertIrp(Csq, Irp); + return STATUS_PENDING; + } * */ typedef NTSTATUS (NTAPI *PIO_CSQ_INSERT_IRP_EX) (struct _IO_CSQ *Csq, @@ -94,11 +98,11 @@ * * Sample: * - VOID NTAPI CsqRemoveIrp(PIO_CSQ Csq, PIRP Irp) - { - KdPrint(("Removing IRP 0x%x from CSQ\n", Irp)); - RemoveEntryList(&Irp->Tail.Overlay.ListEntry); - } + VOID NTAPI CsqRemoveIrp(PIO_CSQ Csq, PIRP Irp) + { + KdPrint(("Removing IRP 0x%x from CSQ\n", Irp)); + RemoveEntryList(&Irp->Tail.Overlay.ListEntry); + } * */ typedef VOID (NTAPI *PIO_CSQ_REMOVE_IRP) (struct _IO_CSQ *Csq, @@ -109,18 +113,18 @@ * * Sample: * - PIRP NTAPI CsqPeekNextIrp(PIO_CSQ Csq, PIRP Irp, PVOID PeekContext) - { - KdPrint(("Peeking for next IRP\n")); + PIRP NTAPI CsqPeekNextIrp(PIO_CSQ Csq, PIRP Irp, PVOID PeekContext) + { + KdPrint(("Peeking for next IRP\n"));
- if(Irp) - return CONTAINING_RECORD(&Irp->Tail.Overlay.ListEntry.Flink, IRP, Tail.Overlay.ListEntry); + if(Irp) + return CONTAINING_RECORD(&Irp->Tail.Overlay.ListEntry.Flink, IRP, Tail.Overlay.ListEntry);
- if(IsListEmpty(&IrpQueue)) - return NULL; + if(IsListEmpty(&IrpQueue)) + return NULL;
- return CONTAINING_RECORD(IrpQueue.Flink, IRP, Tail.Overlay.ListEntry); - } + return CONTAINING_RECORD(IrpQueue.Flink, IRP, Tail.Overlay.ListEntry); + } * */ typedef PIRP (NTAPI *PIO_CSQ_PEEK_NEXT_IRP) (struct _IO_CSQ *Csq, @@ -133,11 +137,11 @@ * * Sample: * - VOID NTAPI CsqAcquireLock(PIO_CSQ Csq, PKIRQL Irql) - { - KdPrint(("Acquiring spin lock\n")); - KeAcquireSpinLock(&IrpQueueLock, Irql); - } + VOID NTAPI CsqAcquireLock(PIO_CSQ Csq, PKIRQL Irql) + { + KdPrint(("Acquiring spin lock\n")); + KeAcquireSpinLock(&IrpQueueLock, Irql); + } * */ typedef VOID (NTAPI *PIO_CSQ_ACQUIRE_LOCK) (struct _IO_CSQ *Csq, @@ -146,11 +150,11 @@ /* * Unlock the queue: * - VOID NTAPI CsqReleaseLock(PIO_CSQ Csq, KIRQL Irql) - { - KdPrint(("Releasing spin lock\n")); - KeReleaseSpinLock(&IrpQueueLock, Irql); - } + VOID NTAPI CsqReleaseLock(PIO_CSQ Csq, KIRQL Irql) + { + KdPrint(("Releasing spin lock\n")); + KeReleaseSpinLock(&IrpQueueLock, Irql); + } * */ typedef VOID (NTAPI *PIO_CSQ_RELEASE_LOCK) (struct _IO_CSQ *Csq, @@ -162,13 +166,13 @@ * * Sample: * - VOID NTAPI CsqCompleteCancelledIrp(PIO_CSQ Csq, PIRP Irp) - { - KdPrint(("cancelling irp 0x%x\n", Irp)); - Irp->IoStatus.Status = STATUS_CANCELLED; - Irp->IoStatus.Information = 0; - IoCompleteRequest(Irp, IO_NO_INCREMENT); - } + VOID NTAPI CsqCompleteCancelledIrp(PIO_CSQ Csq, PIRP Irp) + { + KdPrint(("cancelling irp 0x%x\n", Irp)); + Irp->IoStatus.Status = STATUS_CANCELLED; + Irp->IoStatus.Information = 0; + IoCompleteRequest(Irp, IO_NO_INCREMENT); + } * */ typedef VOID (NTAPI *PIO_CSQ_COMPLETE_CANCELED_IRP) (struct _IO_CSQ *Csq, @@ -179,8 +183,8 @@ * STRUCTURES * * NOTE: Please do not use these directly. You will make incompatible code - * if you do. Always only use the documented IoCsqXxx() interfaces and you will - * amass much Good Karma. + * if you do. Always only use the documented IoCsqXxx() interfaces and you + * will amass much Good Karma. */ #define IO_TYPE_CSQ_IRP_CONTEXT 1 #define IO_TYPE_CSQ 2 @@ -213,9 +217,9 @@ /* * CANCEL-SAFE QUEUE DDIs * - * These device driver interfaces are called to make use of the queue. Again, authoritative - * documentation for these functions is in the DDK. The csqtest driver also makes use of - * some of them. + * These device driver interfaces are called to make use of the queue. Again, + * authoritative documentation for these functions is in the DDK. The csqtest + * driver also makes use of some of them. */
@@ -274,4 +278,3 @@ PVOID PeekContext);
#endif /* _REACTOS_CSQ_H */ -
-
navaraf＠svn.reactos.com