rewrite comments into one, unified style

code/kernel/ke_irp.c

@@ -1,4 +1,4 @@
-// ke_irp.c  -  I/O Request Packet dispatch, queue, cancellation, remove-locks
+// I/O request packet infrastructure. This file owns IRP dispatch, queuing, cancellation, and remove-lock helpers.
 
 #include <string.h>
 #include <intrin.h>
@@ -10,9 +10,7 @@
 #include <kernel/mm_virt.h>
 #include <ntlite/ddi/io_driver.h>
 
-// -------------------------------------------------------------------------
-// IRP_QUEUE operations
-// -------------------------------------------------------------------------
+// IRP_QUEUE operations.
 
 __declspec(dllexport) void IrpQueueInit(IRP_QUEUE* q, struct SEMAPHORE* sem) {
     q->Lock      = (SPINLOCK)SPINLOCK_INIT;
@@ -20,6 +18,7 @@ __declspec(dllexport) void IrpQueueInit(IRP_QUEUE* q, struct SEMAPHORE* sem) {
     LIST_INIT(&q->Head);
 }
 
+// Implements the irp Queue Enqueue operation.
 __declspec(dllexport) void IrpQueueEnqueue(IRP_QUEUE* q, IRP* irp) {
     uintptr_t flags = KeAcquireSpinlock(&q->Lock);
     if (irp->Flags & IRP_FLAG_PRIORITY)
@@ -30,6 +29,7 @@ __declspec(dllexport) void IrpQueueEnqueue(IRP_QUEUE* q, IRP* irp) {
     KeSignalSemaphore((SEMAPHORE*)q->Semaphore);
 }
 
+// Implements the irp Queue Dequeue operation.
 __declspec(dllexport) IRP* IrpQueueDequeue(IRP_QUEUE* q) {
     uintptr_t flags = KeAcquireSpinlock(&q->Lock);
     LIST_ENTRY* node = ListPopHead(&q->Head);
@@ -58,13 +58,12 @@ __declspec(dllexport) void IrpQueueCancelAllEx(IRP_QUEUE* q,
     }
 }
 
+// Implements the irp Queue Cancel All operation.
 __declspec(dllexport) void IrpQueueCancelAll(IRP_QUEUE* q, KSTATUS status) {
     IrpQueueCancelAllEx(q, status, (IRP_QUEUE_CANCEL_CALLBACK)0, (void*)0);
 }
 
-// -------------------------------------------------------------------------
-// Remove locks
-// -------------------------------------------------------------------------
+// Remove locks.
 
 __declspec(dllexport) KSTATUS IoInitializeRemoveLock(IO_REMOVE_LOCK* lock) {
     if (!lock) return STATUS_INVALID_PARAMETER;
@@ -76,6 +75,7 @@ __declspec(dllexport) KSTATUS IoInitializeRemoveLock(IO_REMOVE_LOCK* lock) {
     return STATUS_SUCCESS;
 }
 
+// Releases remove Lock.
 __declspec(dllexport) void IoDestroyRemoveLock(IO_REMOVE_LOCK* lock) {
     if (!lock) return;
     if (lock->RemovedEvent) {
@@ -84,6 +84,7 @@ __declspec(dllexport) void IoDestroyRemoveLock(IO_REMOVE_LOCK* lock) {
     }
 }
 
+// Implements the acquire Remove Lock operation.
 __declspec(dllexport) KSTATUS IoAcquireRemoveLock(IO_REMOVE_LOCK* lock, IRP* irp) {
     (void)irp;
     if (!lock) return STATUS_INVALID_PARAMETER;
@@ -97,6 +98,7 @@ __declspec(dllexport) KSTATUS IoAcquireRemoveLock(IO_REMOVE_LOCK* lock, IRP* irp
     return STATUS_SUCCESS;
 }
 
+// Releases remove Lock.
 __declspec(dllexport) void IoReleaseRemoveLock(IO_REMOVE_LOCK* lock, IRP* irp) {
     (void)irp;
     if (!lock) return;
@@ -105,6 +107,7 @@ __declspec(dllexport) void IoReleaseRemoveLock(IO_REMOVE_LOCK* lock, IRP* irp) {
         KeSignalEvent(lock->RemovedEvent);
 }
 
+// Releases remove Lock And Wait.
 __declspec(dllexport) void IoReleaseRemoveLockAndWait(IO_REMOVE_LOCK* lock, IRP* removeIrp) {
     (void)removeIrp;
     if (!lock) return;
@@ -124,15 +127,14 @@ __declspec(dllexport) void IoReleaseRemoveLockAndWait(IO_REMOVE_LOCK* lock, IRP*
         KeWaitForEvent(lock->RemovedEvent, 0);
 }
 
-// -------------------------------------------------------------------------
-// IRP helpers
-// -------------------------------------------------------------------------
+// IRP helpers.
 
 static size_t IoIrpSize(uint8_t stackCount) {
     if (stackCount == 0) stackCount = 1;
     return sizeof(IRP) + ((size_t)stackCount - 1u) * sizeof(IO_STACK_LOCATION);
 }
 
+// Creates irp.
 __declspec(dllexport) KSTATUS IoAllocateIrp(uint8_t stackCount, IRP** outIrp) {
     if (!outIrp) return STATUS_INVALID_PARAMETER;
     if (stackCount == 0) stackCount = 1;
@@ -143,10 +145,12 @@ __declspec(dllexport) KSTATUS IoAllocateIrp(uint8_t stackCount, IRP** outIrp) {
     return STATUS_SUCCESS;
 }
 
+// Releases irp.
 __declspec(dllexport) void IoFreeIrp(IRP* irp) {
     if (irp) MmFreePool(irp);
 }
 
+// Initializes irp.
 __declspec(dllexport) void IoInitializeIrp(IRP* irp, uint8_t stackCount) {
     if (!irp) return;
     if (stackCount == 0) stackCount = 1;
@@ -159,22 +163,26 @@ __declspec(dllexport) void IoInitializeIrp(IRP* irp, uint8_t stackCount) {
     irp->CurrentLocation = 0;
 }
 
+// Returns current Irp Stack Location.
 __declspec(dllexport) IO_STACK_LOCATION* IoGetCurrentIrpStackLocation(IRP* irp) {
     if (!irp || irp->CurrentLocation >= irp->StackCount) return (IO_STACK_LOCATION*)0;
     return &irp->Stack[irp->CurrentLocation];
 }
 
+// Returns next Irp Stack Location.
 __declspec(dllexport) IO_STACK_LOCATION* IoGetNextIrpStackLocation(IRP* irp) {
     if (!irp || irp->CurrentLocation + 1u >= irp->StackCount) return (IO_STACK_LOCATION*)0;
     return &irp->Stack[irp->CurrentLocation + 1u];
 }
 
+// Implements the skip Current Irp Stack Location operation.
 __declspec(dllexport) void IoSkipCurrentIrpStackLocation(IRP* irp) {
     if (!irp) return;
     if (irp->CurrentLocation + 1u < irp->StackCount)
         irp->CurrentLocation++;
 }
 
+// Copies current Irp Stack Location To Next.
 __declspec(dllexport) void IoCopyCurrentIrpStackLocationToNext(IRP* irp) {
     IO_STACK_LOCATION* cur = IoGetCurrentIrpStackLocation(irp);
     IO_STACK_LOCATION* next = IoGetNextIrpStackLocation(irp);
@@ -183,12 +191,14 @@ __declspec(dllexport) void IoCopyCurrentIrpStackLocationToNext(IRP* irp) {
     irp->CurrentLocation++;
 }
 
+// Updates completion Routine.
 __declspec(dllexport) void IoSetCompletionRoutine(IRP* irp, IRP_COMPLETION_FN fn, void* ctx) {
     if (!irp) return;
     irp->CompletionFn = fn;
     irp->CompletionCtx = ctx;
 }
 
+// Updates cancel Routine.
 __declspec(dllexport) IRP_CANCEL_ROUTINE IoSetCancelRoutine(IRP* irp, IRP_CANCEL_ROUTINE routine) {
     if (!irp) return (IRP_CANCEL_ROUTINE)0;
     uintptr_t flags = KeAcquireSpinlock(&irp->CancelLock);
@@ -198,6 +208,7 @@ __declspec(dllexport) IRP_CANCEL_ROUTINE IoSetCancelRoutine(IRP* irp, IRP_CANCEL
     return old;
 }
 
+// Cancels irp.
 __declspec(dllexport) void IoCancelIrp(IRP* irp) {
     if (!irp) return;
 
@@ -262,9 +273,7 @@ __declspec(dllexport) void IoBuildDeviceIoControlIrp(IRP* irp,
     ios->Parameters.DeviceIoControl.OutputLength = outputLength;
 }
 
-// -------------------------------------------------------------------------
-// Completion/submission
-// -------------------------------------------------------------------------
+// Completion/submission.
 
 __declspec(dllexport) KSTATUS IoCompleteRequest(IRP* irp, KSTATUS status, size_t information) {
     if (!irp) return STATUS_INVALID_PARAMETER;
@@ -293,6 +302,7 @@ __declspec(dllexport) KSTATUS IoCompleteRequest(IRP* irp, KSTATUS status, size_t
     return STATUS_SUCCESS;
 }
 
+// Submits irp.
 __declspec(dllexport) KSTATUS IoSubmitIrp(DEVICE_OBJECT* device, IRP* irp) {
     if (!device || !irp) return STATUS_INVALID_PARAMETER;
     irp->Status = STATUS_FAILURE;
@@ -301,6 +311,7 @@ __declspec(dllexport) KSTATUS IoSubmitIrp(DEVICE_OBJECT* device, IRP* irp) {
     return IoCallDriver(device, irp);
 }
 
+// Submits irp Sync.
 __declspec(dllexport) KSTATUS IoSubmitIrpSync(DEVICE_OBJECT* device, IRP* irp) {
     if (!device || !irp) return STATUS_INVALID_PARAMETER;