rewrite comments into one, unified style

code/drivers/net/rtl816x/rtl816x.c

@@ -1,4 +1,5 @@
-// rtl816x.c - rtl8168/rtl8169 packet I/O, interrupt, and PCI function-driver path.
+// Realtek RTL816x network driver. This file owns PCI attachment, descriptor rings, and net-device registration.
+
 #include "rtl816x.h"
 
 const HAL_API* gHal;
@@ -17,45 +18,53 @@ static const IO_DRIVER_ID_TABLE gRtl816xIdTable = {
     sizeof(gRtl816xIds) / sizeof(gRtl816xIds[0]),
 };
 
+// Implements the rtl Memory Barrier operation.
 static __forceinline void RtlMemoryBarrier(void) {
     _ReadWriteBarrier();
     _mm_mfence();
     _ReadWriteBarrier();
 }
 
+// Implements the rtl Read8 operation.
 static uint8_t RtlRead8(RTL816X_DEVICE* r, uint32_t reg) {
     if (r->UseMmio)
         return *(volatile uint8_t*)(r->Mmio + reg);
     return __inbyte((unsigned short)(r->IoBase + reg));
 }
 
+// Implements the rtl Read16 operation.
 static uint16_t RtlRead16(RTL816X_DEVICE* r, uint32_t reg) {
     if (r->UseMmio)
         return *(volatile uint16_t*)(r->Mmio + reg);
     return __inword((unsigned short)(r->IoBase + reg));
 }
 
+// Implements the rtl Read32 operation.
 static uint32_t RtlRead32(RTL816X_DEVICE* r, uint32_t reg) {
     if (r->UseMmio)
         return *(volatile uint32_t*)(r->Mmio + reg);
     return __indword((unsigned short)(r->IoBase + reg));
 }
 
+// Implements the rtl Write8 operation.
 static void RtlWrite8(RTL816X_DEVICE* r, uint32_t reg, uint8_t value) {
     if (r->UseMmio) *(volatile uint8_t*)(r->Mmio + reg) = value;
     else __outbyte((unsigned short)(r->IoBase + reg), value);
 }
 
+// Implements the rtl Write16 operation.
 static void RtlWrite16(RTL816X_DEVICE* r, uint32_t reg, uint16_t value) {
     if (r->UseMmio) *(volatile uint16_t*)(r->Mmio + reg) = value;
     else __outword((unsigned short)(r->IoBase + reg), value);
 }
 
+// Implements the rtl Write32 operation.
 static void RtlWrite32(RTL816X_DEVICE* r, uint32_t reg, uint32_t value) {
     if (r->UseMmio) *(volatile uint32_t*)(r->Mmio + reg) = value;
     else __outdword((unsigned short)(r->IoBase + reg), value);
 }
 
+// Implements the rtl Reset operation.
 static KSTATUS RtlReset(RTL816X_DEVICE* r) {
     RtlWrite8(r, RTL_REG_CHIP_CMD, RTL_CMD_RESET);
     for (uint32_t i = 0; i < 1000; i++) {
@@ -67,12 +76,14 @@ static KSTATUS RtlReset(RTL816X_DEVICE* r) {
     return STATUS_TIMEOUT;
 }
 
+// Implements the rtl Read Mac operation.
 static void RtlReadMac(RTL816X_DEVICE* r) {
     for (uint32_t i = 0; i < 6; i++)
         r->NetDevice.HardwareAddress[i] = RtlRead8(r, RTL_REG_MAC0 + i);
     r->NetDevice.HardwareAddressLength = 6;
 }
 
+// Implements the rtl Allocate Dma operation.
 static KSTATUS RtlAllocateDma(RTL816X_DEVICE* r) {
     r->RxRingPhys = MmAllocateContiguous(RTL_RING_PAGES);
     r->TxRingPhys = MmAllocateContiguous(RTL_RING_PAGES);
@@ -100,6 +111,7 @@ static KSTATUS RtlAllocateDma(RTL816X_DEVICE* r) {
     return STATUS_SUCCESS;
 }
 
+// Implements the rtl Init Descriptors operation.
 static void RtlInitDescriptors(RTL816X_DEVICE* r) {
     for (uint32_t i = 0; i < RTL_RX_COUNT; i++) {
         PHYSICAL_ADDRESS p = r->RxBuffersPhys + (PHYSICAL_ADDRESS)i * RTL_BUF_SIZE;
@@ -122,6 +134,7 @@ static void RtlInitDescriptors(RTL816X_DEVICE* r) {
     RtlMemoryBarrier();
 }
 
+// Implements the rtl Program Hardware operation.
 static void RtlProgramHardware(RTL816X_DEVICE* r) {
     RtlWrite8(r, RTL_REG_CFG9346, 0xC0);
 
@@ -151,6 +164,7 @@ static void RtlProgramHardware(RTL816X_DEVICE* r) {
     RtlWrite16(r, RTL_REG_INTR_MASK, RTL_INTR_ENABLES);
 }
 
+// Implements the rtl Handle Rx operation.
 static void RtlHandleRx(RTL816X_DEVICE* r) {
     for (uint32_t budget = 0; budget < RTL_RX_COUNT; budget++) {
         RTL_DESC* d = &r->RxRing[r->RxIndex];
@@ -188,6 +202,7 @@ static void RtlHandleRx(RTL816X_DEVICE* r) {
     }
 }
 
+// Implements the rtl Dpc Routine operation.
 static void RtlDpcRoutine(KDPC* dpc, void* context, void* systemArgument1, void* systemArgument2) {
     (void)dpc;
     (void)systemArgument1;
@@ -212,6 +227,7 @@ static void RtlDpcRoutine(KDPC* dpc, void* context, void* systemArgument1, void*
         DbgPrint("RTL816X: interrupt status error bits=0x%04x\n", status);
 }
 
+// Implements the rtl Register Device operation.
 static KSTATUS RtlRegisterDevice(RTL816X_DEVICE* r) {
     if (!r) return STATUS_INVALID_PARAMETER;
 
@@ -233,6 +249,7 @@ static KSTATUS RtlRegisterDevice(RTL816X_DEVICE* r) {
     return STATUS_SUCCESS;
 }
 
+// Implements the rtl Unregister Device operation.
 static void RtlUnregisterDevice(RTL816X_DEVICE* r) {
     if (!r) return;
 
@@ -248,6 +265,7 @@ static void RtlUnregisterDevice(RTL816X_DEVICE* r) {
     KeReleaseSpinlock(&gRtl816xRegistryLock, flags);
 }
 
+// Implements the rtl Isr operation.
 static void RtlIsr(void) {
     RTL816X_DEVICE* snapshot[RTL816X_MAX_DEVICES];
     uint32_t count = 0;
@@ -276,6 +294,7 @@ static void RtlIsr(void) {
     }
 }
 
+// Implements the rtl Send Frame operation.
 static KSTATUS RtlSendFrame(NET_DEVICE* device, const void* frame, size_t length) {
     if (!device || !frame)
         return STATUS_INVALID_PARAMETER;
@@ -315,6 +334,7 @@ static KSTATUS RtlSendFrame(NET_DEVICE* device, const void* frame, size_t length
     return STATUS_SUCCESS;
 }
 
+// Implements the rtl Select Register Bar operation.
 static KSTATUS RtlSelectRegisterBar(RTL816X_DEVICE* r) {
     if (!r || !r->Pdo)
         return STATUS_INVALID_PARAMETER;
@@ -380,6 +400,7 @@ static KSTATUS RtlSelectRegisterBar(RTL816X_DEVICE* r) {
     return STATUS_NOT_FOUND;
 }
 
+// Implements the rtl Start Device operation.
 static KSTATUS RtlStartDevice(RTL816X_DEVICE* r) {
     if (!r || r->Magic != RTL816X_DEVICE_MAGIC || !r->Pdo || !r->Fdo)
         return STATUS_INVALID_PARAMETER;
@@ -465,6 +486,7 @@ static KSTATUS RtlStartDevice(RTL816X_DEVICE* r) {
     return STATUS_SUCCESS;
 }
 
+// Dispatches pnp.
 KSTATUS Rtl816xDispatchPnp(DEVICE_OBJECT* device, IRP* irp) {
     if (!device || !irp || !device->DeviceExtension)
         return STATUS_INVALID_PARAMETER;
@@ -507,6 +529,7 @@ KSTATUS Rtl816xDispatchPnp(DEVICE_OBJECT* device, IRP* irp) {
     }
 }
 
+// Implements the add Device operation.
 KSTATUS Rtl816xAddDevice(DRIVER_OBJECT* driver, DEVICE_OBJECT* physicalDeviceObject) {
     if (!driver || !physicalDeviceObject || physicalDeviceObject->Type != DeviceObjectPhysical)
         return STATUS_INVALID_PARAMETER;
@@ -535,6 +558,7 @@ KSTATUS Rtl816xAddDevice(DRIVER_OBJECT* driver, DEVICE_OBJECT* physicalDeviceObj
     return STATUS_SUCCESS;
 }
 
+// Implements the driver Entry operation.
 KSTATUS DriverEntry(const HAL_API* hal) {
     if (!hal)
         return STATUS_INVALID_PARAMETER;

code/drivers/net/rtl816x/rtl816x.h

@@ -1,4 +1,5 @@
-// rtl816x.h - shared rtl8168/rtl8169 driver internals.
+// Realtek RTL816x driver internals shared by the PCI and packet paths.
+
 #pragma once
 
 #include <stdint.h>