Fix debugger step_over to use instruction-level stepping

- Changed step_over implementation from using breakpoints and full emulation
  to instruction-level stepping for precise control
- Both DebuggerWidget and TCP server now use the same stepping approach
- Step_over now properly executes JSR and steps through subroutine until return
- Added debugStepped signal for UI synchronization
- Connected DebuggerWidget to AtariEmulator signals for real-time updates
- Fixed synchronization between TCP commands and debug widget display
- Safety limit of 10,000 instructions prevents infinite loops in subroutines
- Added documentation for debug.step_into and debug.step_over TCP commands

This fixes the issue where step_over was using coarse frame-level stepping
and ensures consistent behavior between UI and TCP debugging interfaces.

Author: pedgarcia

TCP_SERVER_API.md

@@ -786,12 +786,14 @@ Single-step execution (one frame). Executes approximately 7,000-10,000 instructi
 echo '{"command": "debug.step"}' | nc localhost 6502
 ```
 
-#### `debug.step_instruction`
+#### `debug.step_instruction` / `debug.step_into`
 
-Single-instruction stepping for precise debugging. Executes exactly one 6502 CPU instruction.
+Single-instruction stepping for precise debugging. Executes exactly one 6502 CPU instruction. Both commands are aliases and perform the same operation.
 
 ```bash
 echo '{"command": "debug.step_instruction"}' | nc localhost 6502
+# or
+echo '{"command": "debug.step_into"}' | nc localhost 6502
 ```
 
 **Response:**
@@ -811,8 +813,38 @@ echo '{"command": "debug.step_instruction"}' | nc localhost 6502
 - Requires emulation to be paused first
 - Advances PC by the exact instruction size (1-3 bytes)
 - Much more precise than `debug.step` for debugging
+- Will step INTO subroutines when encountering JSR instructions
 - Ideal for IDE integration and breakpoint debugging
 
+#### `debug.step_over`
+
+Step over subroutine calls. When encountering a JSR (Jump to Subroutine) instruction, executes the entire subroutine and returns to the instruction following the JSR. For non-JSR instructions, behaves like `step_into`.
+
+```bash
+echo '{"command": "debug.step_over"}' | nc localhost 6502
+```
+
+**Response:**
+```json
+{
+  "type": "response",
+  "status": "success",
+  "result": {
+    "stepped": true,
+    "pc": "$2004",
+    "step_over": true
+  }
+}
+```
+
+**Notes:**
+- Requires emulation to be paused first
+- When at JSR ($20): executes entire subroutine using instruction-level stepping
+- When not at JSR: executes single instruction like `step_into`
+- Uses instruction-level stepping internally (not frame stepping)
+- Safety limit of 10,000 instructions prevents infinite loops
+- Ideal for debugging without diving into subroutine implementation
+
 #### `debug.load_xex_for_debug`
 
 Load an XEX file and pause after loading completes, ready for debugging. The emulator steps through frames to ensure the XEX is fully loaded into memory before pausing. This allows setting breakpoints before program execution begins.

include/atariemulator.h

@@ -296,6 +296,7 @@ public slots:
     void breakpointsCleared();
     void executionPaused();
     void executionResumed();
+    void debugStepped();
 
 private:
     unsigned char convertQtKeyToAtari(int key, Qt::KeyboardModifiers modifiers);

include/debuggerwidget.h

@@ -51,6 +51,15 @@ public slots:
 
 private slots:
     void refreshDebugInfo();
+    
+    // Emulator signal handlers
+    void onEmulatorBreakpointHit(unsigned short address);
+    void onEmulatorBreakpointAdded(unsigned short address);
+    void onEmulatorBreakpointRemoved(unsigned short address);
+    void onEmulatorBreakpointsCleared();
+    void onEmulatorExecutionPaused();
+    void onEmulatorExecutionResumed();
+    void onEmulatorDebugStepped();
 
 private:
     void setupUI();

src/atariemulator.cpp

@@ -2118,6 +2118,7 @@ void AtariEmulator::stepOneFrame()
         // Execute one frame manually when paused
         processFrame();
         qDebug() << "Stepped one frame - PC:" << QString("$%1").arg(CPU_regPC, 4, 16, QChar('0')).toUpper();
+        emit debugStepped();
     } else {
         qDebug() << "Cannot step frame - emulation not paused";
     }
@@ -2133,6 +2134,7 @@ void AtariEmulator::stepOneInstruction()
         checkBreakpoints();
 
         qDebug() << "Stepped one instruction - PC:" << QString("$%1").arg(CPU_regPC, 4, 16, QChar('0')).toUpper();
+        emit debugStepped();
     } else {
         qDebug() << "Cannot step instruction - emulation not paused";
     }

src/debuggerwidget.cpp

@@ -261,6 +261,17 @@ void DebuggerWidget::connectSignals()
     connect(m_removeBreakpointButton, &QPushButton::clicked, this, &DebuggerWidget::onRemoveBreakpointClicked);
     connect(m_clearBreakpointsButton, &QPushButton::clicked, this, &DebuggerWidget::clearAllBreakpoints);
     connect(m_breakpointListWidget, &QListWidget::itemSelectionChanged, this, &DebuggerWidget::onBreakpointSelectionChanged);
+    
+    // Connect to emulator debugging signals
+    if (m_emulator) {
+        connect(m_emulator, &AtariEmulator::breakpointHit, this, &DebuggerWidget::onEmulatorBreakpointHit);
+        connect(m_emulator, &AtariEmulator::breakpointAdded, this, &DebuggerWidget::onEmulatorBreakpointAdded);
+        connect(m_emulator, &AtariEmulator::breakpointRemoved, this, &DebuggerWidget::onEmulatorBreakpointRemoved);
+        connect(m_emulator, &AtariEmulator::breakpointsCleared, this, &DebuggerWidget::onEmulatorBreakpointsCleared);
+        connect(m_emulator, &AtariEmulator::executionPaused, this, &DebuggerWidget::onEmulatorExecutionPaused);
+        connect(m_emulator, &AtariEmulator::executionResumed, this, &DebuggerWidget::onEmulatorExecutionResumed);
+        connect(m_emulator, &AtariEmulator::debugStepped, this, &DebuggerWidget::onEmulatorDebugStepped);
+    }
 }
 
 void DebuggerWidget::updateCPUState()
@@ -904,35 +915,43 @@ void DebuggerWidget::stepOverSubroutine()
     unsigned char opcode = MEMORY_mem[currentPC];
 
     if (isSubroutineCall(opcode)) {
-        // This is a JSR instruction - set breakpoint at return address
-        m_stepOverBreakPC = currentPC + 3;  // JSR is 3 bytes
+        // This is a JSR instruction - execute it and then run until return address
+        unsigned short returnAddress = currentPC + 3;  // JSR is 3 bytes
 
-        qDebug() << QString("Step Over: JSR at $%1, setting break at $%2")
+        qDebug() << QString("Step Over: JSR at $%1, target return at $%2")
                     .arg(currentPC, 4, 16, QChar('0')).toUpper()
-                    .arg(m_stepOverBreakPC, 4, 16, QChar('0')).toUpper();
+                    .arg(returnAddress, 4, 16, QChar('0')).toUpper();
+        
+        // Execute the JSR instruction first
+        m_emulator->stepOneInstruction();
 
-        // Execute frames until we reach the breakpoint
-        int maxFrames = 1000; // Safety limit
-        int frameCount = 0;
+        // Now we're inside the subroutine, step until we reach the return address
+        // Use a safety limit to prevent infinite loops
+        int maxSteps = 10000;  // Maximum instructions to execute
+        int stepCount = 0;
 
-        while (frameCount < maxFrames && CPU_regPC != m_stepOverBreakPC) {
-            m_emulator->stepOneFrame();
-            frameCount++;
+        while (CPU_regPC != returnAddress && stepCount < maxSteps) {
+            m_emulator->stepOneInstruction();
+            stepCount++;
 
-            // Update display every 10 frames to show progress
-            if (frameCount % 10 == 0) {
+            // Update display periodically for long subroutines
+            if (stepCount % 100 == 0) {
                 refreshDebugInfo();
-                QCoreApplication::processEvents(); // Allow UI updates
+                QCoreApplication::processEvents();
             }
         }
 
-        if (frameCount >= maxFrames) {
-            qDebug() << "Step Over: Timeout reached, subroutine may not return";
+        if (stepCount >= maxSteps) {
+            qDebug() << QString("Step Over: Timeout after %1 steps, subroutine may not return")
+                        .arg(stepCount);
         } else {
-            qDebug() << QString("Step Over: Completed after %1 frames, PC at $%2")
-                        .arg(frameCount)
+            qDebug() << QString("Step Over: Completed after %1 steps, PC at $%2")
+                        .arg(stepCount)
                         .arg(CPU_regPC, 4, 16, QChar('0')).toUpper();
         }
+        
+        // Refresh the display
+        refreshDebugInfo();
     } else {
         // Not a subroutine call, just step one instruction
         stepSingleInstruction();
@@ -1065,4 +1084,105 @@ void DebuggerWidget::checkBreakpoints()
 {
     // This functionality has been moved to the core emulator
     // to ensure breakpoints work consistently across all interfaces (TCP, Debug window)
+}
+
+// Handler for when a breakpoint is hit
+void DebuggerWidget::onEmulatorBreakpointHit(unsigned short address)
+{
+    qDebug() << QString("Debugger: Breakpoint hit at $%1").arg(address, 4, 16, QChar('0')).toUpper();
+    
+    // Update the UI to reflect the paused state (handled by onEmulatorExecutionPaused)
+    // Refresh debug info to show current state
+    refreshDebugInfo();
+}
+
+// Handler for when a breakpoint is added (e.g., from TCP)
+void DebuggerWidget::onEmulatorBreakpointAdded(unsigned short address)
+{
+    qDebug() << QString("Debugger: Breakpoint added at $%1").arg(address, 4, 16, QChar('0')).toUpper();
+    
+    // Update our local breakpoint list from the emulator
+    m_breakpoints = m_emulator->getBreakpoints();
+    updateBreakpointList();
+    
+    // Refresh disassembly to show new breakpoint indicator
+    updateDisassemblyView();
+}
+
+// Handler for when a breakpoint is removed (e.g., from TCP)
+void DebuggerWidget::onEmulatorBreakpointRemoved(unsigned short address)
+{
+    qDebug() << QString("Debugger: Breakpoint removed at $%1").arg(address, 4, 16, QChar('0')).toUpper();
+    
+    // Update our local breakpoint list from the emulator
+    m_breakpoints = m_emulator->getBreakpoints();
+    updateBreakpointList();
+    
+    // Refresh disassembly to remove breakpoint indicator
+    updateDisassemblyView();
+}
+
+// Handler for when all breakpoints are cleared (e.g., from TCP)
+void DebuggerWidget::onEmulatorBreakpointsCleared()
+{
+    qDebug() << "Debugger: All breakpoints cleared";
+    
+    // Clear our local breakpoint list
+    m_breakpoints.clear();
+    updateBreakpointList();
+    
+    // Refresh disassembly to remove breakpoint indicators
+    updateDisassemblyView();
+}
+
+// Handler for when execution is paused (e.g., from TCP or breakpoint hit)
+void DebuggerWidget::onEmulatorExecutionPaused()
+{
+    qDebug() << "Debugger: Execution paused";
+    
+    // Update internal state
+    m_isRunning = false;
+    
+    // Update button states
+    if (m_stepIntoButton && m_stepOverButton && m_runButton && m_pauseButton) {
+        m_stepIntoButton->setEnabled(true);
+        m_stepOverButton->setEnabled(true);
+        m_runButton->setEnabled(true);
+        m_pauseButton->setEnabled(false);
+    }
+    
+    // Stop the refresh timer
+    m_refreshTimer->stop();
+    
+    // Immediately refresh the debug info to show current state
+    refreshDebugInfo();
+}
+
+// Handler for when execution is resumed (e.g., from TCP)
+void DebuggerWidget::onEmulatorExecutionResumed()
+{
+    qDebug() << "Debugger: Execution resumed";
+    
+    // Update internal state
+    m_isRunning = true;
+    
+    // Update button states
+    if (m_stepIntoButton && m_stepOverButton && m_runButton && m_pauseButton) {
+        m_stepIntoButton->setEnabled(false);
+        m_stepOverButton->setEnabled(false);
+        m_runButton->setEnabled(false);
+        m_pauseButton->setEnabled(true);
+    }
+    
+    // Start the refresh timer for continuous updates
+    m_refreshTimer->start();
+}
+
+// Handler for when a debug step occurs (from TCP or UI)
+void DebuggerWidget::onEmulatorDebugStepped()
+{
+    qDebug() << "Debugger: Step executed";
+    
+    // Immediately refresh all debug information
+    refreshDebugInfo();
 }

src/tcpserver.cpp

@@ -21,6 +21,7 @@
 #include <QBuffer>
 #include <QImageReader>
 #include <QDateTime>
+#include <QThread>
 
 extern "C" {
     // Access to CPU registers for debug commands
@@ -1418,8 +1419,9 @@ void TCPServer::handleDebugCommand(QTcpSocket* client, const QJsonObject& reques
                         "Emulation must be paused to step");
         }
 
-    } else if (subCommand == "step_instruction") {
+    } else if (subCommand == "step_instruction" || subCommand == "step_into") {
         // Single-instruction stepping (precise debugging)
+        // step_into is an alias for step_instruction - both step into subroutines naturally
         if (m_emulator->isEmulationPaused()) {
             m_emulator->stepOneInstruction();
 
@@ -1441,6 +1443,72 @@ void TCPServer::handleDebugCommand(QTcpSocket* client, const QJsonObject& reques
                         "Emulation must be paused to step");
         }
 
+    } else if (subCommand == "step_over") {
+        // Step over subroutine calls
+        if (m_emulator->isEmulationPaused()) {
+            unsigned short currentPC = CPU_regPC;
+            unsigned char opcode = MEMORY_mem[currentPC];
+            
+            // Check if this is a JSR instruction (0x20)
+            if (opcode == 0x20) {
+                // JSR instruction - use instruction-level stepping to execute subroutine
+                unsigned short returnAddress = currentPC + 3;  // JSR is 3 bytes
+                
+                qDebug() << QString("TCP step_over: JSR at $%1, target return at $%2")
+                            .arg(currentPC, 4, 16, QChar('0')).toUpper()
+                            .arg(returnAddress, 4, 16, QChar('0')).toUpper();
+                
+                // Execute the JSR instruction first
+                m_emulator->stepOneInstruction();
+                
+                // Now we're inside the subroutine, step until we reach the return address
+                // Use a safety limit to prevent infinite loops
+                int maxSteps = 10000;  // Maximum instructions to execute
+                int stepCount = 0;
+                
+                while (CPU_regPC != returnAddress && stepCount < maxSteps) {
+                    m_emulator->stepOneInstruction();
+                    stepCount++;
+                    
+                    // Process events periodically for long subroutines
+                    if (stepCount % 100 == 0) {
+                        QCoreApplication::processEvents();
+                    }
+                }
+                
+                if (stepCount >= maxSteps) {
+                    qDebug() << QString("TCP step_over: Timeout after %1 steps, subroutine may not return")
+                                .arg(stepCount);
+                } else {
+                    qDebug() << QString("TCP step_over: Completed after %1 steps, PC=$%2")
+                                .arg(stepCount)
+                                .arg(CPU_regPC, 4, 16, QChar('0')).toUpper();
+                }
+            } else {
+                // Not a JSR, just step one instruction
+                m_emulator->stepOneInstruction();
+                qDebug() << QString("TCP step_over: Not JSR (opcode=$%1), single step")
+                            .arg(opcode, 2, 16, QChar('0')).toUpper();
+            }
+            
+            QJsonObject result;
+            result["stepped"] = true;
+            result["pc"] = QString("$%1").arg(CPU_regPC, 4, 16, QChar('0')).toUpper();
+            result["step_over"] = true;
+            
+            sendResponse(client, requestId, true, result);
+            
+            // Send event to all clients
+            QJsonObject eventData;
+            eventData["stepped"] = true;
+            eventData["pc"] = QString("$%1").arg(CPU_regPC, 4, 16, QChar('0')).toUpper();
+            eventData["step_over"] = true;
+            sendEventToAllClients("debug_stepped", eventData);
+        } else {
+            sendResponse(client, requestId, false, QJsonValue(), 
+                        "Emulation must be paused to step");
+        }
+        
     } else if (subCommand == "disassemble") {
         // Disassemble memory at specified address
         int address = params["address"].toInt(CPU_regPC);