docs: document watchpoint slot tracking and update debugger commands

debug/watchpoint_linux_amd64.go

@@ -25,12 +25,34 @@ const (
 	WatchRead  WatchpointType = 3 // trigger on read or write
 )
 
+// FindFreeWatchpointSlot returns the index of the first free watchpoint slot
+// (0-3), or -1 if all four hardware watchpoints are in use.
+func (s *Session) FindFreeWatchpointSlot() int {
+	for i := 0; i < 4; i++ {
+		if !s.wpSlots[i] {
+			return i
+		}
+	}
+	return -1
+}
+
+// IsWatchpointSlotUsed reports whether slot (0-3) currently holds a watchpoint.
+func (s *Session) IsWatchpointSlotUsed(slot int) bool {
+	if slot < 0 || slot > 3 {
+		return false
+	}
+	return s.wpSlots[slot]
+}
+
 // SetWatchpoint installs a hardware watchpoint on the given address.
-// slot is 0-3 (four hardware watchpoints available).
+// slot is 0-3 (four hardware watchpoints available); the slot must be free.
 func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size int) error {
 	if slot < 0 || slot > 3 {
 		return fmt.Errorf("debug: watchpoint slot must be 0-3")
 	}
+	if s.wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d already in use", slot)
+	}
 
 	// Determine the length encoding.
 	var lenBits uint64
@@ -82,6 +104,7 @@ func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size
 	if err := ptracePokeUser(s.pid, 0x38, dr7); err != nil {
 		return fmt.Errorf("debug: set DR7: %w", err)
 	}
+	s.wpSlots[slot] = true
 	return nil
 }
 
@@ -90,20 +113,29 @@ func (s *Session) ClearWatchpoint(slot int) error {
 	if slot < 0 || slot > 3 {
 		return fmt.Errorf("debug: watchpoint slot must be 0-3")
 	}
+	if !s.wpSlots[slot] {
+		return fmt.Errorf("debug: watchpoint slot %d is not in use", slot)
+	}
 	// Read DR7, clear the enable bit for this slot.
 	dr7, err := ptracePeekUser(s.pid, 0x38)
 	if err != nil {
 		return err
 	}
 	dr7 &^= uint64(1) << (2 * slot) // disable
-	return ptracePokeUser(s.pid, 0x38, dr7)
+	if err := ptracePokeUser(s.pid, 0x38, dr7); err != nil {
+		return err
+	}
+	s.wpSlots[slot] = false
+	return nil
 }
 
 // ClearAllWatchpoints removes all hardware watchpoints.
 func (s *Session) ClearAllWatchpoints() error {
 	for slot := 0; slot < 4; slot++ {
-		if err := s.ClearWatchpoint(slot); err != nil {
-			return err
+		if s.wpSlots[slot] {
+			if err := s.ClearWatchpoint(slot); err != nil {
+				return err
+			}
 		}
 	}
 	return nil