Merge branch 'feature/vtop-fix' into feature/tcp

- Fix for issue #32 in which the incorrect bitmask ($FFFFFF) is used where
  $3FFFFF should be used instead. (24 vs 22 bits).

.gitattributes

@@ -1 +1,8 @@
 * text=auto eol=lf
+lvglh/** linguist-vendored
+lvgl/** linguist-vendored
+.vscode/* linguist-vendored
+lib/* linguist-generated
+release/* linguist-generated
+iso/* linguist-generated
+*.asm linguist-detectable

.gitignore

@@ -15,3 +15,4 @@ localenv.json
 dockerout.txt
 AGENTS.md
 *.log
+/doc/*.md

src/driver/bus/PCI.pas

@@ -18,7 +18,7 @@
 	@author(Aaron Hance <[email protected]>)
 	@author(Kieron Morris <[email protected]>)
 }
-unit PCI;
+unit pci;
 
 interface
 

src/driver/bus/usb/OHCI.pas

@@ -7,7 +7,7 @@
 
     @author(Kieron Morris <[email protected]>)
 }
-unit OHCI;
+unit ohci;
 
 interface
 
@@ -23,6 +23,7 @@ uses
     drivermanagement,
     usbtypes,
     usbcore,
+    isrmanager,
     lists,
     strings;
 
@@ -234,6 +235,7 @@ type
         EDBulk      : POHCI_ED;   { Head of bulk ED list }
         EDInterrupt : POHCI_ED;   { Dummy head for interrupt ED list }
         NumPorts    : uint8;      { Number of downstream ports }
+        PollBusy    : boolean;    { Re-entrancy guard for poll }
         PCIBus      : uint8;      { PCI address }
         PCISlot     : uint8;
         PCIFunc     : uint8;
@@ -1022,6 +1024,60 @@ begin
     end;
 end;
 
+{ ========================= Interrupt-Driven Completion ========================= }
+
+const
+    OHCI_MAX_INSTANCES = 4;
+
+var
+    OHCIInstances     : array[0..OHCI_MAX_INSTANCES-1] of PUSBHCDriver;
+    OHCIInstanceCount : uint32;
+
+{ ISR handler — registered on the PCI interrupt line. }
+procedure ohci_isr;
+var
+    i      : uint32;
+    hc     : PUSBHCDriver;
+    priv   : POHCI_PrivData;
+    intSts : uint32;
+begin
+    for i := 0 to OHCIInstanceCount - 1 do begin
+        hc := OHCIInstances[i];
+        if hc = nil then continue;
+        priv := POHCI_PrivData(hc^.PrivData);
+        if priv = nil then continue;
+
+        { Check if this controller has pending interrupt status }
+        intSts := ohci_read(priv^.MMIOBase, OHCI_REG_INTSTATUS);
+        if intSts = 0 then continue;
+
+        { Acknowledge interrupt status NOW to de-assert level-triggered PCI line.
+          Must happen before ohci_poll, because PollBusy guard may skip the
+          acknowledge inside poll — leaving the line asserted = interrupt storm. }
+        ohci_write(priv^.MMIOBase, OHCI_REG_INTSTATUS, intSts);
+
+        { Process completions (walks ED lists) }
+        ohci_poll(hc);
+
+        { Hotplug: if RootHubStatusChange, flag for deferred processing }
+        if ((intSts AND OHCI_INT_RHSC) <> 0) and hc^.HotplugArmed then
+            hc^.PortChangePending := true;
+    end;
+    usbcore.fire_completion_hooks;
+end;
+
+{ Enable hardware interrupts: WritebackDoneHead, RootHubStatusChange, UnrecoverableError + MIE. }
+procedure ohci_enable_interrupts(hc : PUSBHCDriver);
+var
+    priv : POHCI_PrivData;
+begin
+    if (hc = nil) or (hc^.PrivData = nil) then exit;
+    priv := POHCI_PrivData(hc^.PrivData);
+    ohci_write(priv^.MMIOBase, OHCI_REG_INTENABLE,
+        OHCI_INT_WDH OR OHCI_INT_RHSC OR OHCI_INT_UE OR OHCI_INT_MIE);
+    syslog.logln('OHCI', 'Hardware interrupts enabled.');
+end;
+
 procedure ohci_poll(hc : PUSBHCDriver);
 var
     priv     : POHCI_PrivData;
@@ -1038,6 +1094,11 @@ var
 begin
     if (hc = nil) or (hc^.PrivData = nil) then exit;
     priv := POHCI_PrivData(hc^.PrivData);
+
+    { Re-entrancy guard }
+    if priv^.PollBusy then exit;
+    priv^.PollBusy := true;
+
     base := priv^.MMIOBase;
 
     { Read and acknowledge interrupt status }
@@ -1107,6 +1168,7 @@ begin
             ed := nextED;
         end;
     end;
+    priv^.PollBusy := false;
 end;
 
 { ========================= Load / Init ========================= }
@@ -1124,6 +1186,7 @@ var
 begin
     push_trace('OHCI.load');
     load := false;
+    OHCIInstanceCount := 0;
 
     devices := PCI.getDeviceInfo($0C, $03, $10, count);
     syslog.log('OHCI', 'Found ');
@@ -1220,9 +1283,24 @@ begin
         hcEntry := usbcore.register_hc(@hc);
 
         { Scan ports for connected devices (use the stable pointer, not stack-local @hc) }
-        if hcEntry <> nil then
-            usbcore.scan_ports(hcEntry)
-        else
+        if hcEntry <> nil then begin
+            { Track instance for ISR dispatch }
+            if OHCIInstanceCount < OHCI_MAX_INSTANCES then begin
+                OHCIInstances[OHCIInstanceCount] := hcEntry;
+                inc(OHCIInstanceCount);
+            end;
+
+            { Register ISR on PCI interrupt line }
+            syslog.log('OHCI', 'Registering ISR on IRQ ');
+            syslog.writeintln(devices[i].interrupt_line);
+            isrmanager.registerISR(32 + devices[i].interrupt_line, @ohci_isr);
+
+            { Enable hardware interrupts }
+            ohci_enable_interrupts(hcEntry);
+
+            { Scan for connected devices }
+            usbcore.scan_ports(hcEntry);
+        end else
             syslog.logln('OHCI', 'Failed to register HC with USB core.');
 
         syslog.logln('OHCI', 'Controller initialized and registered.');

src/driver/bus/usb/UHCI.pas

@@ -6,7 +6,7 @@
 
     @author(Kieron Morris <[email protected]>)
 }
-unit UHCI;
+unit uhci;
 
 interface
 
@@ -22,6 +22,7 @@ uses
     drivermanagement,
     usbtypes,
     usbcore,
+    isrmanager,
     lists,
     strings;
 
@@ -154,6 +155,7 @@ type
         QHControl   : PUHCI_QH; { Queue Head for control transfers }
         QHBulk      : PUHCI_QH; { Queue Head for bulk transfers }
         QHInterrupt : PUHCI_QH; { Queue Head for interrupt transfers }
+        PollBusy    : boolean;  { Re-entrancy guard for poll }
         PCIBus      : uint8;    { PCI bus/slot/func for bus mastering }
         PCISlot     : uint8;
         PCIFunc     : uint8;
@@ -750,6 +752,56 @@ begin
     pop_trace;
 end;
 
+{ ========================= Interrupt-Driven Completion ========================= }
+
+const
+    UHCI_MAX_INSTANCES = 4;
+
+var
+    UHCIInstances     : array[0..UHCI_MAX_INSTANCES-1] of PUSBHCDriver;
+    UHCIInstanceCount : uint32;
+
+{ ISR handler — registered on the PCI interrupt line. }
+procedure uhci_isr;
+var
+    i      : uint32;
+    hc     : PUSBHCDriver;
+    priv   : PUHCI_PrivData;
+    status : uint16;
+begin
+    for i := 0 to UHCIInstanceCount - 1 do begin
+        hc := UHCIInstances[i];
+        if hc = nil then continue;
+        priv := PUHCI_PrivData(hc^.PrivData);
+        if priv = nil then continue;
+
+        { Check if this controller has pending interrupt status }
+        status := uhci_read16(priv^.IOBase, UHCI_REG_USBSTS);
+        if (status AND (UHCI_STS_USBINT OR UHCI_STS_ERROR)) = 0 then continue;
+
+        { Acknowledge interrupt status NOW to de-assert level-triggered PCI line.
+          Must happen before uhci_poll, because PollBusy guard may skip the
+          acknowledge inside poll — leaving the line asserted = interrupt storm. }
+        uhci_write16(priv^.IOBase, UHCI_REG_USBSTS, status AND (UHCI_STS_USBINT OR UHCI_STS_ERROR));
+
+        { Process completions (walks QH/TD chains) }
+        uhci_poll(hc);
+    end;
+    usbcore.fire_completion_hooks;
+end;
+
+{ Enable hardware interrupts: Interrupt-on-Complete, Short Packet, Timeout/CRC. }
+procedure uhci_enable_interrupts(hc : PUSBHCDriver);
+var
+    priv : PUHCI_PrivData;
+begin
+    if (hc = nil) or (hc^.PrivData = nil) then exit;
+    priv := PUHCI_PrivData(hc^.PrivData);
+    uhci_write16(priv^.IOBase, UHCI_REG_USBINTR,
+        UHCI_INTR_IOC OR UHCI_INTR_SP OR UHCI_INTR_TIMEOUT);
+    syslog.logln('UHCI', 'Hardware interrupts enabled.');
+end;
+
 { ========================= Poll / Completion ========================= }
 
 procedure uhci_poll(hc : PUSBHCDriver);
@@ -768,6 +820,10 @@ begin
     if (hc = nil) or (hc^.PrivData = nil) then exit;
     priv := PUHCI_PrivData(hc^.PrivData);
 
+    { Re-entrancy guard }
+    if priv^.PollBusy then exit;
+    priv^.PollBusy := true;
+
     { Read and clear status register }
     status := uhci_read16(priv^.IOBase, UHCI_REG_USBSTS);
     if (status AND (UHCI_STS_USBINT OR UHCI_STS_ERROR)) <> 0 then
@@ -841,6 +897,7 @@ begin
         end;
         qh := qh^.SWNext;
     end;
+    priv^.PollBusy := false;
 end;
 
 { ========================= Load / Init ========================= }
@@ -857,6 +914,7 @@ var
 begin
     push_trace('UHCI.load');
     load := false;
+    UHCIInstanceCount := 0;
 
     devices := PCI.getDeviceInfo($0C, $03, $00, count);
     syslog.log('UHCI', 'Found ');
@@ -945,9 +1003,24 @@ begin
         hcEntry := usbcore.register_hc(@hc);
 
         { Scan ports for connected devices (use the stable pointer, not stack-local @hc) }
-        if hcEntry <> nil then
-            usbcore.scan_ports(hcEntry)
-        else
+        if hcEntry <> nil then begin
+            { Track instance for ISR dispatch }
+            if UHCIInstanceCount < UHCI_MAX_INSTANCES then begin
+                UHCIInstances[UHCIInstanceCount] := hcEntry;
+                inc(UHCIInstanceCount);
+            end;
+
+            { Register ISR on PCI interrupt line }
+            syslog.log('UHCI', 'Registering ISR on IRQ ');
+            syslog.writeintln(devices[i].interrupt_line);
+            isrmanager.registerISR(32 + devices[i].interrupt_line, @uhci_isr);
+
+            { Enable hardware interrupts }
+            uhci_enable_interrupts(hcEntry);
+
+            { Scan for connected devices }
+            usbcore.scan_ports(hcEntry);
+        end else
             syslog.logln('UHCI', 'Failed to register HC with USB core.');
 
         syslog.logln('UHCI', 'Controller initialized and registered.');

src/driver/bus/usb/USB.pas

@@ -17,7 +17,7 @@
 	
 	@author(Kieron Morris <[email protected]>)
 }
-unit USB;
+unit usb;
 
 interface
 
@@ -35,6 +35,7 @@ uses
     usbhub,
     usb_keyboard,
     usb_mouse,
+    usb_storage,
     OHCI, UHCI, EHCI, XHCI;
 
 procedure init;
@@ -90,6 +91,9 @@ begin
     usb_keyboard.init;
     usb_mouse.init;
 
+    { Initialize storage class driver }
+    usb_storage.init;
+    
     UHCI_ID.Bus:= biPCI;
     UHCI_ID.id0:= idANY;
     UHCI_ID.id1:= $0000000C;

src/driver/bus/usb/usbtypes.pas

@@ -217,6 +217,9 @@ type
     PUSBHCDriver = ^TUSBHCDriver;
     PUSBTransfer = ^TUSBTransfer;
 
+    { ---- Disconnect Callback ---- }
+    TUSBDisconnectCallback = procedure(dev : PUSBDevice);
+
     { ---- Transfer Request ---- }
 
     TUSBTransfer = record
@@ -246,6 +249,7 @@ type
         Endpoints    : array[0..USB_MAX_ENDPOINTS-1] of TUSBEndpoint;
         NumEndpoints : uint8;
         Configured   : boolean;
+        fnDisconnect : TUSBDisconnectCallback; { Called before device is freed on unplug }
     end;
 
     { ---- HC Driver Abstraction (Function Pointer Types) ---- }
@@ -269,6 +273,8 @@ type
         PrivData     : Pointer;     { HC-specific state }
         Devices      : PLinkedListBase; { List of PUSBDevice attached }
         NextAddress  : uint8;       { Next available USB address (1-127) }
+        PortChangePending : boolean; { Set by ISR when port status changes; processed in deferred context }
+        HotplugArmed : boolean;     { False during boot; set true after initial scan_ports to ignore spurious RHSC }
         { Operations }
         fnReset      : TUSBHCReset;
         fnStart      : TUSBHCStart;

src/driver/hid/ps2/ps2_keyboard.pas

@@ -33,31 +33,40 @@ uses
 procedure callback(scan_code : void);
 var
     info     : TKeyInfo;
+    raw      : uint8;
+    baseCode : uint8;
+    isBreak  : boolean;
 begin
+    raw := uint8(scan_code);
+
+    { In PS/2 scancode set 1, bit 7 set = key release (break code) }
+    isBreak  := (raw AND $80) <> 0;
+    baseCode := raw AND $7F;
+
+    { Update modifier state (use raw codes so both make/break are handled) }
+    if raw = 42  then keyboard.is_shift := true;
+    if raw = 170 then keyboard.is_shift := false;
+    if raw = 29  then keyboard.is_ctrl  := true;
+    if raw = 157 then keyboard.is_ctrl  := false;
+    if raw = 56  then keyboard.is_alt   := true;
+    if raw = 184 then keyboard.is_alt   := false;
+
     info.SHIFT_DOWN    := keyboard.is_shift;
     info.CTRL_DOWN     := keyboard.is_ctrl;
     info.ALT_DOWN      := keyboard.is_alt;
-    info.is_down_code := true;
+    info.is_down_code  := not isBreak;
 
     if keyboard.is_shift then begin
-        if key_matrix_shift[uint8(scan_code)].key_code <> 0 then begin
-            info.key_code := key_matrix_shift[uint8(scan_code)].key_code;
+        if key_matrix_shift[baseCode].key_code <> 0 then begin
+            info.key_code := key_matrix_shift[baseCode].key_code;
             keyboard.reportKeyEvent(info);
         end;
     end else begin
-        if key_matrix[uint8(scan_code)].key_code <> 0 then begin
-            info.key_code := key_matrix[uint8(scan_code)].key_code;
+        if key_matrix[baseCode].key_code <> 0 then begin
+            info.key_code := key_matrix[baseCode].key_code;
             keyboard.reportKeyEvent(info);
         end;
     end;
-
-    { Update modifier state }
-    if uint8(scan_code) = 42 then keyboard.is_shift := true;
-    if uint8(scan_code) = 170 then keyboard.is_shift := false;
-    if uint8(scan_code) = 29 then keyboard.is_ctrl := true;
-    if uint8(scan_code) = 157 then keyboard.is_ctrl := false;
-    if uint8(scan_code) = 56 then keyboard.is_alt := true;
-    if uint8(scan_code) = 184 then keyboard.is_alt := false;
 end;
 
 function load(ptr : void) : boolean;

src/driver/net/l1/net.pas

@@ -100,8 +100,8 @@ end;
 
 procedure send(p_data : void; p_len : uint16);
 begin
-    //push_trace('net.send');
-    //writeToLogLn('L1: net.send');
+    push_trace('net.send');
+    writeToLogLn('L1/NET: send');
     if CBSend <> nil then CBSend(p_data, p_len);
     pop_trace;
 end;
@@ -111,8 +111,7 @@ var
     context : PPacketContext;
 
 begin
-    //push_trace('net.recv');
-    //writeToLogLn('L1: net.recv');
+    push_trace('net.recv');
     context:= newPacketContext;
     if CBNext <> nil then CBNext(p_data, p_len, context);
     freePacketContext(context);
@@ -129,6 +128,7 @@ end;
 procedure init;
 begin
     push_trace('net.init');
+    writeToLogLn('L1/NET: init');
     //l2
     eth2.register;
     //l3
@@ -136,6 +136,7 @@ begin
     ipv4.register;
     //l4
     icmp.register;
+    tcp.register;
     udp.register;
     //l5
     dhcp.register;

src/driver/net/l2/eth2.pas

@@ -46,6 +46,7 @@ var
 
 procedure registerTypePromisc(eType : uint16; RecvCB : TRecvCallback);
 begin
+    push_trace('eth2.registerTypePromisc');
     register;
     if EthTypes[eType] = nil then EthTypes[eType]:= RecvCB;
     Promisc[eType]:= true;
@@ -53,6 +54,7 @@ end;
 
 procedure registerType(eType : uint16; RecvCB : TRecvCallback);
 begin
+    push_trace('eth2.registerType');
     register;
     if EthTypes[eType] = nil then EthTypes[eType]:= RecvCB;
 end;
@@ -93,7 +95,7 @@ var
     buf        : puint8;
 
 begin
-    //writeToLogLn('    L2: eth2.recv');
+    push_trace('eth2.recv');
     buf:= puint8(p_data);
     
     Header:= PEthernetHeader(buf);
@@ -120,6 +122,7 @@ var
 begin
     push_trace('eth2.register');
     if not Registered then begin
+        writeToLogLn('    L2/ETH: register');
         for i:=0 to 65535 do begin
             EthTypes[i]:= nil;
             Promisc[i]:= false;

src/driver/net/l3/arp.pas

@@ -96,6 +96,7 @@ var
     hSize, pSize : uint8;
 
 begin
+    push_trace('arp.send');
     if p_context <> nil then begin
         buf:= kalloc(sizeof(TARPHeader));
         hdr:= PARPHeader(buf);
@@ -135,6 +136,8 @@ var
     context : PPacketContext;
 
 begin
+     push_trace('arp.sendGratuitous');
+     writeToLogLn('      L3/ARP: sendGratuitous');
      context:= newPacketContext;
      CopyIPv4(@getIPv4Config^.Address[0], @context^.IP.Destination[0]);
      CopyIPv4(@getIPv4Config^.Address[0], @context^.IP.Source[0]);
@@ -150,6 +153,7 @@ var
     CacheRecord : PARPCacheRecord;
 
 begin
+     push_trace('arp.sendRequestGateway');
      context:= newPacketContext;
      CacheRecord:= findCacheRecordByIP(@getIPv4Config^.Gateway[0]);
      if CacheRecord <> nil then begin
@@ -168,6 +172,8 @@ var
     CacheRecord : PARPCacheRecord;
 
 begin
+     push_trace('arp.sendRequest');
+     writeToLogLn('      L3/ARP: sendRequest');
      context:= newPacketContext;
      CopyIPv4(ip, @context^.IP.Destination[0]);
      CopyIPv4(@getIPv4Config^.Address[0], @context^.IP.Source[0]);
@@ -184,6 +190,7 @@ var
     CacheRecord : PARPCacheRecord;
 
 begin
+    push_trace('arp.resolveIP');
     CacheRecord:= findCacheRecordByIP(ip);
     resolveIP:= nil;
     if CacheRecord = nil then begin
@@ -203,6 +210,7 @@ var
     context      : PPacketContext;
 
 begin
+    push_trace('arp.recv');
     { Get our converted Header }
     Header:= PARPHeader(p_data);
     AHeader.Hardware_Type:= (Header^.Hardware_Type_Hi SHL 8) + Header^.Hardware_Type_Lo;
@@ -298,6 +306,7 @@ procedure register;
 begin
     push_trace('arp.register');
     if not Registered then begin
+        writeToLogLn('      L3/ARP: register');
         Cache:= LL_New(sizeof(TARPCacheRecord));
         eth2.registerTypePromisc($0806, @recv);
         stdio.registerCommand('ARP', @terminal_command_arp, 'Get ARP Table.');

src/driver/net/l3/ipv4.pas

@@ -46,7 +46,9 @@ var
 
 function  getIPv4Config : PIPv4Configuration;
 begin
+    push_trace('ipv4.getIPv4Config');
     getIPv4Config:= @Config;
+    pop_trace;
 end;
 
 procedure send(p_data : void; p_len : uint16; p_context : PPacketContext);
@@ -57,6 +59,7 @@ var
     buffer : void;
 
 begin
+    push_trace('ipv4.send');
     inc(CurrentID);
     Header.version:= 4;
     Header.header_len:= 5;
@@ -84,6 +87,7 @@ begin
     memcpy(uint32(p_data), uint32(Buffer) + (Header.header_len * 4), p_len);
     eth2.send(Buffer, (Header.header_len * 4) + p_len, $0800, p_context);
     kfree(Buffer);
+    pop_trace;
 end;
 
 procedure recv(p_data : void; p_len : uint16; p_context : PPacketContext);
@@ -95,6 +99,7 @@ var
     len     : uint16;
 
 begin
+    push_trace('ipv4.recv');
     Header:= PIPV4Header(p_data);
     AHeader.version:= Header^.version;
     AHeader.header_len:= Header^.header_len;
@@ -195,6 +200,7 @@ var
 begin
     push_trace('ipv4.register');
     if not Registered then begin
+        writeToLogLn('      L3/IPv4: register');
         for i:=0 to 255 do begin
             Protocols[i]:= nil;
         end;
@@ -213,6 +219,7 @@ end;
 
 procedure registerProtocol(Protocol_ID : uint8; recv_callback : TRecvCallback);
 begin
+    push_trace('ipv4.registerProtocol');
     register;
     if Protocols[Protocol_ID] = nil then Protocols[Protocol_ID]:= recv_callback;
     pop_trace;

src/driver/net/l4/icmp.pas

@@ -23,7 +23,7 @@ interface
 
 uses
     bios_data_area,
-    lmemorymanager,
+    lmemorymanager, tracer,
     net, nettypes, netutils, ipv4, arp, util;
 
 type
@@ -55,6 +55,7 @@ var
     i : uint8;
 
 begin
+    push_trace('icmp.nextInactiveHandler');
     nextInactiveHandler:= 0;
     for i:=1 to 255 do begin
         if not Handlers[i].Active then begin
@@ -80,6 +81,8 @@ var
     Size     : uint32;
 
 begin
+    push_trace('icmp.sendICMPRequest');
+    writeToLogLn('        L4/ICMP: sendICMPRequest');
     handle:= nextInactiveHandler;
     Handlers[handle].Active:= true;
     Handlers[handle].OnReply:= OnRep;
@@ -135,6 +138,8 @@ var
     Handle : uint8;
 
 begin
+    push_trace('icmp.recv');
+    writeToLogLn('        L4/ICMP: recv');
     Header:= PICMPHeader(p_data);
     //writehexlnWND(Header^.ICMP_Type, getTerminalHWND); 
     case Header^.ICMP_Type of
@@ -243,6 +248,8 @@ var
     i : uint32;
 
 begin
+    push_trace('icmp.register');
+    writeToLogLn('        L4/ICMP: register');
     for i:=0 to 255 do begin
         Handlers[i].Active:= false;
         Handlers[i].OnError:= nil;