rewrite comments into one, unified style

code/kernel/ke_thread.c

@@ -1,4 +1,5 @@
-// ke_thread.c - thread model
+// Thread manager. This file owns thread allocation, kernel/user startup contexts, and lifecycle transitions.
+
 #include <string.h>
 #include <stddef.h>
 #include <intrin.h>
@@ -31,6 +32,7 @@ STATIC_ASSERT_OFFSET(THREAD, FpuContext, 168);
 static uint32_t gNextThreadId = 1;
 extern void KeThreadEntry(void);
 
+// Implements the thread Destroy operation.
 static void KiThreadDestroy(OBJECT* obj) {
     THREAD* thread = CONTAINING_RECORD(obj, THREAD, Header);
 
@@ -65,6 +67,7 @@ static void KiThreadDestroy(OBJECT* obj) {
         KeReleaseSpinlock(&owner->HandleLock, flags);
 
         if (remaining == 0 && owner->Terminating &&
+            // Implements the interlocked Exchange operation.
             _InterlockedExchange(&owner->Exited, 1) == 0) {
             if (owner->ExitEvent) KeSignalEvent(owner->ExitEvent);
         }
@@ -213,6 +216,7 @@ __declspec(dllexport) KSTATUS KeCreateThread(PROCESS* owner, uintptr_t entry, ui
     return STATUS_SUCCESS;
 }
 
+// Implements the exit Thread operation.
 __declspec(dllexport) void KeExitThread(THREAD* thread, int code) {
     (void)code;
     if (!thread) return;
@@ -229,18 +233,15 @@ __declspec(dllexport) void KeExitThread(THREAD* thread, int code) {
     KeYield();
 }
 
-// ---------------------------------------------------------------------------
 // KeCreateKernelThread
-// ---------------------------------------------------------------------------
 // Kernel threads never go to ring 3: they have no user stack, no TEB, and
 // their entry stub (KeKernelThreadEntry) calls the function directly then
 // calls KeExitThread instead of IRETQ-ing.
-//
+
 // Stack layout built here (from KernelStackTop downward):
 //   [ksp - 8 ]  arg          <-- popped by KeKernelThreadEntry as r12
 //   [ksp - 16]  fn           <-- popped by KeKernelThreadEntry as rbx
-//   [ksp - 16 - sizeof(KCONTEXT)]  KCONTEXT { .Rip = KeKernelThreadEntry }
-// ---------------------------------------------------------------------------
+//   [ksp - 16 - sizeof(KCONTEXT)]  KCONTEXT { .Rip = KeKernelThreadEntry }.
 extern void KeKernelThreadEntry(void);
 
 static KSTATUS KiCreateKernelThreadWithAffinity(uintptr_t fn, uintptr_t arg,
@@ -338,6 +339,7 @@ __declspec(dllexport) KSTATUS KeCreateKernelThreadWithAffinity(uintptr_t fn, uin
     return KiCreateKernelThreadWithAffinity(fn, arg, priority, affinityMask, out);
 }
 
+// Prepares block Thread.
 void KePrepareBlockThread(THREAD* thread, OBJECT* waitObject, uint8_t alertable) {
     // Called with the synchronization object's spinlock held, so the caller is
     // normally at DISPATCH_LEVEL here. This function only marks intent to
@@ -353,12 +355,14 @@ void KePrepareBlockThread(THREAD* thread, OBJECT* waitObject, uint8_t alertable)
 }
 
 
+// Updates thread Wait List.
 void KeSetThreadWaitList(THREAD* thread, LIST_ENTRY* waitListHead) {
     KeAssertIrqlAtOrBelow(DISPATCH_LEVEL);
     if (!thread) return;
     thread->WaitListHead = waitListHead;
 }
 
+// Implements the finish Wait operation.
 static void KiFinishWait(THREAD* thread, KSTATUS status) {
     thread->WaitObject    = (OBJECT*)0;
     thread->WaitStatus    = status;
@@ -366,6 +370,7 @@ static void KiFinishWait(THREAD* thread, KSTATUS status) {
     thread->AlertableWait = 0;
 }
 
+// Implements the commit Block Thread operation.
 KSTATUS KeCommitBlockThread(THREAD* thread, uint8_t alertable) {
     KeAssertIrql(PASSIVE_LEVEL);
     if (!thread) return STATUS_INVALID_PARAMETER;
@@ -405,21 +410,25 @@ KSTATUS KeCommitBlockThread(THREAD* thread, uint8_t alertable) {
 }
 
 
+// Implements the block Thread operation.
 KSTATUS KeBlockThread(THREAD* thread, OBJECT* waitObject, uint8_t alertable) {
     KePrepareBlockThread(thread, waitObject, alertable);
     return KeCommitBlockThread(thread, alertable);
 }
 
 
+// Implements the unblock Thread With Status operation.
 void KeUnblockThreadWithStatus(THREAD* thread, KSTATUS status) {
     if (!thread) return;
     KiSchedulerWakeThread(thread, status);
 }
 
+// Implements the unblock Thread operation.
 void KeUnblockThread(THREAD* thread) {
     KeUnblockThreadWithStatus(thread, STATUS_SUCCESS);
 }
 
+// Implements the alert Thread With Status operation.
 static KSTATUS KiAlertThreadWithStatus(THREAD* thread, KSTATUS status) {
     if (!thread) return STATUS_INVALID_PARAMETER;
 
@@ -433,14 +442,17 @@ static KSTATUS KiAlertThreadWithStatus(THREAD* thread, KSTATUS status) {
     return STATUS_SUCCESS;
 }
 
+// Implements the alert Thread operation.
 KSTATUS KeAlertThread(THREAD* thread) {
     return KiAlertThreadWithStatus(thread, STATUS_ALERTED);
 }
 
+// Implements the wake Thread For Kernel Apc operation.
 void KiWakeThreadForKernelApc(THREAD* thread) {
     (void)KiAlertThreadWithStatus(thread, STATUS_KERNEL_APC);
 }
 
+// Implements the wake Thread For User Apc operation.
 void KiWakeThreadForUserApc(THREAD* thread) {
     (void)KiAlertThreadWithStatus(thread, STATUS_USER_APC);
 }