rewrite comments into one, unified style

code/drivers/net/lwip/lwip_sys_arch.c

@@ -1,4 +1,5 @@
-// lwip_sys_arch.c - lwIP OS abstraction layer for the kernel.
+// lwIP OS-abstraction layer. This file maps lwIP synchronization and timing primitives onto kernel services.
+
 #include <stdint.h>
 #include <stddef.h>
 #include <stdbool.h>
@@ -42,18 +43,20 @@ struct sys_mbox {
 
 
 static uint64_t (*gLwipQueryTicksUs)(void) = 0;
-static uint32_t gRandState = 0x4b4e4554u; /* 'KNET' */
+static uint32_t gRandState = 0x4b4e4554u;  // 'KNET'
 
+// Implements the port Set Timer Query operation.
 void LwipPortSetTimerQuery(uint64_t (*query_ticks_us)(void)) {
     gLwipQueryTicksUs = query_ticks_us;
 }
 
 unsigned int lwip_port_rand(void) {
-    /* Tiny deterministic LCG. Good enough for ephemeral port randomisation. */
+    // Tiny deterministic LCG. Good enough for ephemeral port randomisation.
     gRandState = gRandState * 1664525u + 1013904223u;
     return gRandState;
 }
 
+// Implements the sys init operation.
 void sys_init(void) {
 }
 
@@ -67,22 +70,20 @@ u32_t sys_jiffies(void) {
     return sys_now();
 }
 
-/*
- * lwIP's core/sys.c provides sys_msleep() when it is not a macro.  Do not
- * define it here as well, or MSVC links both sys.obj and lwip_sys_arch.obj
- * with a duplicate sys_msleep symbol.
- */
+// lwIP's core/sys.c provides sys_msleep() when it is not a macro.  Do not
+// define it here as well, or MSVC links both sys.obj and lwip_sys_arch.obj
+// with a duplicate sys_msleep symbol.
 
-/*
- * First bring-up errno storage for lwIP's socket/netdb compatibility layer.
- * This is global, not per-thread; the kernel socket-object wrapper should
- * eventually translate lwIP errors to KSTATUS instead of exposing this.
- */
-// fuckass microsoft
+// First bring-up errno storage for lwIP's socket/netdb compatibility layer.
+// This is global, not per-thread; the kernel socket-object wrapper should
+// eventually translate lwIP errors to KSTATUS instead of exposing this.
+
+// fuckass microsoft.
 #ifdef errno
 #undef errno
 #endif
 int errno;
+// Implements the errno operation.
 int* __cdecl _errno(void) { return &errno; }
 
 err_t sys_sem_new(sys_sem_t* sem, u8_t count) {
@@ -105,6 +106,7 @@ err_t sys_sem_new(sys_sem_t* sem, u8_t count) {
     return ERR_OK;
 }
 
+// Implements the sys sem signal operation.
 void sys_sem_signal(sys_sem_t* sem) {
     if (sem && *sem && (*sem)->Sem)
         KeSignalSemaphore((*sem)->Sem);
@@ -132,6 +134,7 @@ u32_t sys_arch_sem_wait(sys_sem_t* sem, u32_t timeout) {
     }
 }
 
+// Implements the sys sem free operation.
 void sys_sem_free(sys_sem_t* sem) {
     if (!sem || !*sem)
         return;
@@ -161,16 +164,19 @@ err_t sys_mutex_new(sys_mutex_t* mutex) {
     return ERR_OK;
 }
 
+// Implements the sys mutex lock operation.
 void sys_mutex_lock(sys_mutex_t* mutex) {
     if (mutex && *mutex && (*mutex)->Sem)
         (void)KeWaitSemaphore((*mutex)->Sem);
 }
 
+// Implements the sys mutex unlock operation.
 void sys_mutex_unlock(sys_mutex_t* mutex) {
     if (mutex && *mutex && (*mutex)->Sem)
         KeSignalSemaphore((*mutex)->Sem);
 }
 
+// Implements the sys mutex free operation.
 void sys_mutex_free(sys_mutex_t* mutex) {
     if (!mutex || !*mutex)
         return;
@@ -180,6 +186,7 @@ void sys_mutex_free(sys_mutex_t* mutex) {
     *mutex = 0;
 }
 
+// Implements the mbox Try Post operation.
 static err_t LwipMboxTryPost(sys_mbox_t* mbox, void* msg) {
     if (!mbox || !*mbox || !(*mbox)->Valid)
         return ERR_ARG;
@@ -232,8 +239,9 @@ err_t sys_mbox_new(sys_mbox_t* mbox, int size) {
     return ERR_OK;
 }
 
+// Implements the sys mbox post operation.
 void sys_mbox_post(sys_mbox_t* mbox, void* msg) {
-    /* lwIP promises this is not called from ISR context. */
+    // lwIP promises this is not called from ISR context.
     while (LwipMboxTryPost(mbox, msg) != ERR_OK)
         KeYield();
 }
@@ -246,6 +254,7 @@ err_t sys_mbox_trypost_fromisr(sys_mbox_t* mbox, void* msg) {
     return LwipMboxTryPost(mbox, msg);
 }
 
+// Implements the mbox Pop After Item operation.
 static u32_t LwipMboxPopAfterItem(sys_mbox_t* mbox, void** msg, u32_t waited) {
     struct sys_mbox* m = *mbox;
     uintptr_t flags = KeAcquireSpinlock(&m->Lock);
@@ -299,6 +308,7 @@ u32_t sys_arch_mbox_tryfetch(sys_mbox_t* mbox, void** msg) {
     return LwipMboxPopAfterItem(mbox, msg, 0);
 }
 
+// Implements the sys mbox free operation.
 void sys_mbox_free(sys_mbox_t* mbox) {
     if (!mbox || !*mbox)
         return;
@@ -327,18 +337,17 @@ sys_thread_t sys_thread_new(const char* name, lwip_thread_fn thread, void* arg,
     else if (prio <= 0)
         kp = PriorityLow;
 
-    /*
-     * lwIP thread entries already use the same ABI as kernel worker threads:
-     *
-     *     void entry(void* arg)
-     *
-     * Do not bounce through a heap-allocated thunk. The first scaffold used a
-     * tiny { function, argument } heap block and a wrapper, but an early boot
-     * crash showed the wrapper sometimes loaded a bogus function pointer and
-     * jumped into lwIP's .rdata strings. Passing the lwIP entry directly keeps
-     * the initial thread stack simple: KeKernelThreadEntry calls exactly the
-     * function pointer that lwIP supplied, with exactly the argument it supplied.
-     */
+    // lwIP thread entries already use the same ABI as kernel worker threads:
+
+    // void entry(void* arg)
+
+    // Do not bounce through a heap-allocated thunk. The first scaffold used a
+    // tiny { function, argument } heap block and a wrapper, but an early boot
+    // crash showed the wrapper sometimes loaded a bogus function pointer and
+    // jumped into lwIP's .rdata strings. Passing the lwIP entry directly keeps
+    // the initial thread stack simple: KeKernelThreadEntry calls exactly the
+    // function pointer that lwIP supplied, with exactly the argument it supplied.
+
     THREAD* t = 0;
     KSTATUS st = KeCreateKernelThread((uintptr_t)thread,
                                       (uintptr_t)arg,
@@ -356,6 +365,7 @@ sys_prot_t sys_arch_protect(void) {
     return (sys_prot_t)flags;
 }
 
+// Implements the sys arch unprotect operation.
 void sys_arch_unprotect(sys_prot_t pval) {
     if (((uintptr_t)pval) & 0x200u)
         _enable();