rewrite comments into one, unified style

code/drivers/net/rtl8139/rtl8139.c

@@ -1,4 +1,5 @@
-// rtl8139.c - packet I/O, interrupt, and DriverEntry path.
+// Realtek RTL8139 network driver. This file owns PCI attachment, MMIO setup, RX/TX rings, and net-device registration.
+
 #include "rtl8139.h"
 
 const HAL_API* gHal;
@@ -16,40 +17,47 @@ static const IO_DRIVER_ID_TABLE gRtl8139IdTable = {
     sizeof(gRtl8139Ids) / sizeof(gRtl8139Ids[0]),
 };
 
+// Implements the memory Barrier operation.
 static __forceinline void Rtl8139MemoryBarrier(void) {
     _ReadWriteBarrier();
     _mm_mfence();
     _ReadWriteBarrier();
 }
 
+// Implements the read8 operation.
 static uint8_t Rtl8139Read8(RTL8139_DEVICE* r, uint32_t reg) {
     if (r->UseMmio)
         return *(volatile uint8_t*)(r->Mmio + reg);
     return __inbyte((unsigned short)(r->IoBase + reg));
 }
 
+// Implements the read16 operation.
 static uint16_t Rtl8139Read16(RTL8139_DEVICE* r, uint32_t reg) {
     if (r->UseMmio)
         return *(volatile uint16_t*)(r->Mmio + reg);
     return __inword((unsigned short)(r->IoBase + reg));
 }
 
+// Implements the read32 operation.
 static uint32_t Rtl8139Read32(RTL8139_DEVICE* r, uint32_t reg) {
     if (r->UseMmio)
         return *(volatile uint32_t*)(r->Mmio + reg);
     return __indword((unsigned short)(r->IoBase + reg));
 }
 
+// Implements the write8 operation.
 static void Rtl8139Write8(RTL8139_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 write16 operation.
 static void Rtl8139Write16(RTL8139_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 write32 operation.
 static void Rtl8139Write32(RTL8139_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);
@@ -59,6 +67,7 @@ static void Rtl8139Write32(RTL8139_DEVICE* r, uint32_t reg, uint32_t value) {
 
 
 
+// Implements the reset operation.
 static KSTATUS Rtl8139Reset(RTL8139_DEVICE* r) {
     Rtl8139Write8(r, RTL8139_REG_CMD, RTL8139_CMD_RST);
     for (uint32_t i = 0; i < 1000; i++) {
@@ -70,12 +79,14 @@ static KSTATUS Rtl8139Reset(RTL8139_DEVICE* r) {
     return STATUS_TIMEOUT;
 }
 
+// Returns mac.
 static void Rtl8139ReadMac(RTL8139_DEVICE* r) {
     for (uint32_t i = 0; i < 6; i++)
         r->NetDevice.HardwareAddress[i] = Rtl8139Read8(r, RTL8139_REG_IDR0 + i);
     r->NetDevice.HardwareAddressLength = 6;
 }
 
+// Creates dma.
 static KSTATUS Rtl8139AllocateDma(RTL8139_DEVICE* r) {
     r->RxPhys = MmAllocateContiguous(RTL8139_RX_PAGES);
     r->TxPhys = MmAllocateContiguous(RTL8139_TX_PAGES);
@@ -101,6 +112,7 @@ static KSTATUS Rtl8139AllocateDma(RTL8139_DEVICE* r) {
     return STATUS_SUCCESS;
 }
 
+// Implements the rx Read16 operation.
 static uint16_t Rtl8139RxRead16(RTL8139_DEVICE* r, uint32_t offset) {
     offset %= RTL8139_RX_RING_SIZE;
     uint16_t lo = r->RxBuffer[offset];
@@ -108,6 +120,7 @@ static uint16_t Rtl8139RxRead16(RTL8139_DEVICE* r, uint32_t offset) {
     return (uint16_t)(lo | (hi << 8));
 }
 
+// Implements the rx Copy operation.
 static void Rtl8139RxCopy(RTL8139_DEVICE* r, uint32_t offset, void* dst, uint32_t length) {
     uint8_t* out = (uint8_t*)dst;
     offset %= RTL8139_RX_RING_SIZE;
@@ -120,6 +133,7 @@ static void Rtl8139RxCopy(RTL8139_DEVICE* r, uint32_t offset, void* dst, uint32_
         memcpy(out + first, r->RxBuffer, length - first);
 }
 
+// Implements the program Hardware operation.
 static void Rtl8139ProgramHardware(RTL8139_DEVICE* r) {
     // Wake the device and clear stale interrupts before installing buffers.
     Rtl8139Write8(r, RTL8139_REG_CONFIG1, 0x00);
@@ -148,6 +162,7 @@ static void Rtl8139ProgramHardware(RTL8139_DEVICE* r) {
     Rtl8139Write16(r, RTL8139_REG_IMR, RTL8139_INTR_ENABLES);
 }
 
+// Handles rx.
 static void Rtl8139HandleRx(RTL8139_DEVICE* r) {
     for (uint32_t budget = 0; budget < 64; budget++) {
         uint8_t cmd = Rtl8139Read8(r, RTL8139_REG_CMD);
@@ -192,6 +207,7 @@ static void Rtl8139HandleRx(RTL8139_DEVICE* r) {
     }
 }
 
+// Implements the dpc Routine operation.
 static void Rtl8139DpcRoutine(KDPC* dpc, void* context, void* systemArgument1, void* systemArgument2) {
     (void)dpc;
     (void)systemArgument1;
@@ -212,6 +228,7 @@ static void Rtl8139DpcRoutine(KDPC* dpc, void* context, void* systemArgument1, v
         DbgPrint("RTL8139: interrupt error bits=0x%04x\n", status);
 }
 
+// Registers device.
 static KSTATUS Rtl8139RegisterDevice(RTL8139_DEVICE* r) {
     if (!r) return STATUS_INVALID_PARAMETER;
 
@@ -233,6 +250,7 @@ static KSTATUS Rtl8139RegisterDevice(RTL8139_DEVICE* r) {
     return STATUS_SUCCESS;
 }
 
+// Implements the unregister Device operation.
 static void Rtl8139UnregisterDevice(RTL8139_DEVICE* r) {
     if (!r) return;
 
@@ -248,6 +266,7 @@ static void Rtl8139UnregisterDevice(RTL8139_DEVICE* r) {
     KeReleaseSpinlock(&gRtl8139RegistryLock, flags);
 }
 
+// Implements the isr operation.
 static void Rtl8139Isr(void) {
     RTL8139_DEVICE* snapshot[RTL8139_MAX_DEVICES];
     uint32_t count = 0;
@@ -276,6 +295,7 @@ static void Rtl8139Isr(void) {
     }
 }
 
+// Implements the send Frame operation.
 static KSTATUS Rtl8139SendFrame(NET_DEVICE* device, const void* frame, size_t length) {
     if (!device || !frame)
         return STATUS_INVALID_PARAMETER;
@@ -312,6 +332,7 @@ static KSTATUS Rtl8139SendFrame(NET_DEVICE* device, const void* frame, size_t le
     return STATUS_SUCCESS;
 }
 
+// Implements the select Register Bar operation.
 static KSTATUS Rtl8139SelectRegisterBar(RTL8139_DEVICE* r) {
     if (!r || !r->Pdo)
         return STATUS_INVALID_PARAMETER;
@@ -377,6 +398,7 @@ static KSTATUS Rtl8139SelectRegisterBar(RTL8139_DEVICE* r) {
     return STATUS_NOT_FOUND;
 }
 
+// Starts device.
 static KSTATUS Rtl8139StartDevice(RTL8139_DEVICE* r) {
     if (!r || r->Magic != RTL8139_DEVICE_MAGIC || !r->Pdo || !r->Fdo)
         return STATUS_INVALID_PARAMETER;
@@ -462,6 +484,7 @@ static KSTATUS Rtl8139StartDevice(RTL8139_DEVICE* r) {
     return STATUS_SUCCESS;
 }
 
+// Dispatches pnp.
 KSTATUS Rtl8139DispatchPnp(DEVICE_OBJECT* device, IRP* irp) {
     if (!device || !irp || !device->DeviceExtension)
         return STATUS_INVALID_PARAMETER;
@@ -504,6 +527,7 @@ KSTATUS Rtl8139DispatchPnp(DEVICE_OBJECT* device, IRP* irp) {
     }
 }
 
+// Implements the add Device operation.
 KSTATUS Rtl8139AddDevice(DRIVER_OBJECT* driver, DEVICE_OBJECT* physicalDeviceObject) {
     if (!driver || !physicalDeviceObject || physicalDeviceObject->Type != DeviceObjectPhysical)
         return STATUS_INVALID_PARAMETER;
@@ -532,6 +556,7 @@ KSTATUS Rtl8139AddDevice(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/rtl8139/rtl8139.h

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

code/drivers/net/rtl8139/rtl8139_pci.c

@@ -1,2 +1,2 @@
-// rtl8139_pci.c intentionally empty.
-// PCI enumeration, BAR decoding, mapping, and command-register policy now live in pci.sys.
+// Driver support for rtl8139 pci.
+