JoshRodd/86Box-tool

86Box VM-Operationen

Verwenden Sie dieses Skill, wenn eine Aufgabe das Starten, Konfigurieren, Warten, Neustarten, Debuggen oder Inspizieren einer 86Box-VM erfordert.

Unverhandelbare Sicherheitsregeln

1. Lösen Sie das exakte VM-Verzeichnis vor dem Start auf.
2. Starten Sie mit --vmpath <VM-Verzeichnis> --vmname <Anzeigename>.
3. Verfolgen Sie die PID, die für diesen Start zurückgegeben wird, und den stabilen Prozessnamen der Verwaltung.
4. Überprüfen Sie die PID-Identität anhand der ausführbaren Datei und des exakten --vmpath vor jedem Signal.
5. Verwenden Sie niemals killall, breites pkill, breites pgrep oder eine nicht verifizierte PID.
6. Gehen Sie davon aus, dass andere Personen unabhängige 86Box-Prozesse ausführen.
7. Bevorzugen Sie eine saubere UI-Beendigung, wenn NVRAM- oder Konfigurationsänderungen wichtig sind.
8. Überschreiben Sie niemals gemeinsam genutzte ROMs für ein Einzel-VM-Experiment; klonen Sie einen vollständigen ROM-Satz und wählen Sie ihn mit --rompath aus.

Vorbereitung

1. Lösen Sie einen Namen unter dem plattformspezifischen VM-Stammverzeichnis auf. Unter macOS:

   ~/Library/Application Support/86Box/Virtual Machines/<NAME>
   

   Ein direkter VM-Pfad ist ebenfalls gültig.

2. Lesen Sie <VM>/86box.cfg. Notieren Sie:

   • machine;
   • cpu_use_dynarec;
   • optional gdbstub_port;
   • konfigurierte Medien- und Adaptergeräte.

3. Wählen Sie die Binärdatei:

   • normale Interaktion: /Applications/86Box.app/Contents/MacOS/86Box;
   • Gast-Debugging: der lokale -DGDBSTUB=ON Build.

4. Überprüfen Sie den Befehl (ausgeführt vom 86Box-tool-Projektstammverzeichnis oder nach Installation):

   cd ~/src/86Box-tool && uv run ./86boxctl.sh <VM> command
   

5. Wenn mehrere VMs debuggt werden, benötigen Sie einen eindeutigen gdbstub_port in jeder Konfiguration und cpu_use_dynarec = 0.

Start

Eigenständiger Controller:

./86boxctl.sh <VM> start
./86boxctl.sh <VM> start --gdb-stub

Gepatches IBM PS/2 Model 80 Typ 2 BIOS:

./86boxctl.sh <VM> command \
  --model-80-type-2-rom /pfad/zu/sequentiell-128k.bin
./86boxctl.sh <VM> start \
  --model-80-type-2-rom /pfad/zu/sequentiell-128k.bin

Die VM muss machine = ibmps2_m80 verwenden. Der Controller ermittelt das Standard-ROM-Stammverzeichnis der Plattform, klont den vollständigen Baum unter <VM>/romsets/, teilt das Bild in die aktiven Gerad-/Ungerade-Spur-Dateien, validiert sie und startet mit diesem generierten Stammverzeichnis über --rompath. Verwenden Sie --rom-source, wenn die Suche mehrdeutig ist. Verwenden Sie prepare-roms, um zu bauen, ohne zu starten.

Für eine lange, von der Verwaltung vermittelte GUI-Sitzung starten Sie die ausführbare Datei über den Prozessmanager der Verwaltung mit:

name        = eindeutiger stabiler Name wie 86box-automatic-configuration
application = ausgewählte 86Box-Binärdatei
args        = [--vmpath, <absoluter VM-Pfad>, --vmname, <Anzeigename>]
pty         = false
persist     = true wenn die Interaktion mehrere Runden umfasst

Notieren Sie die zurückgegebene PID. Verwenden Sie nur diesen stabilen Prozessnamen für nachfolgende describe-, logs-, restart- und stop-Operationen. Ein Neustart erzeugt eine neue PID; notieren Sie diese.

Übergeben Sie 86box.cfg nicht als einzelnes Positionsargument. Das wählt zwar eine Konfiguration aus, setzt aber nicht den VM-Benutzerdateien-Pfad von 86Box, sodass relative Medien, NVRAM und lokale ROMs gegen das falsche Verzeichnis aufgelöst werden können.

Betriebsbereitschaft herstellen

Die Prozesserstellung allein ist keine Gast-Betriebsbereitschaft.

• Normaler Build: Erfordert, dass der genaue Prozess den Start überlebt, dann die sichtbare VM oder ein konkretes VM-Artefakt überprüfen.
• GDB-Build: Erfordert, dass der konfigurierte RSP-Port dieser VM lauscht.
• Interpretieren Sie niemals einen anderen 86Box-Prozess oder -Port als Nachweis für diese VM.

Verwenden Sie:

./86boxctl.sh <VM> status
./86boxctl.sh <VM> logs --lines 100

Auf einen Benutzer warten

Wenn der Benutzer sagt, bis zu einer Verwaltungsunterbrechung zu warten, tun Sie genau das. Fahren Sie nicht fort, wenn die VM beendet wird, es sei denn, der Benutzer hat eine durch Beendigung ausgelöste Aktion angefordert. Der Auftragswartevorgang der Verwaltung behandelt einen verwalteten GUI-Prozess nicht als Hintergrundauftrag. Erstellen Sie daher einen langen, endlichen, asynchronen Wartesentinel, warten Sie auf diesen Auftrag mit einem unbegrenzten Verwaltungs-Timeout und brechen Sie ihn nach der Benutzerunterbrechung ab.

Behalten Sie den VM-Prozess getrennt im Auge, verfolgt durch seinen stabilen Prozessnamen und seine PID.

Beobachten

Host-Lebenszyklus

./86boxctl.sh <VM> status
./86boxctl.sh <VM> wait
./86boxctl.sh <VM> logs --lines 100

Gast-Bildschirm, -Konsole und -Speicher

Zwei unabhängige Pfade:

1. RSP-Stub (erfordert den GDB-Stub-Build; das Verbinden pausiert den Gast):

   RSP_PORT=<port> ./rsp.py probe
   RSP_PORT=<port> ./rsp.py video-mode
   RSP_PORT=<port> ./rsp.py screen
   RSP_PORT=<port> ./rsp.py wait-screen "erwarteter Text" --wait-timeout 600
   RSP_PORT=<port> ./rsp.py dump b8000 fa0
   

   In den Textmodi 0, 1, 2, 3 und 7 wählt screen 40x25 oder 80x25, verwendet B8000h für Farbe oder B0000h für Monochrom und folgt der aktiven Videoseite. Im Grafikmodus 11h liest es den gepackten 640x480-1BPP-Framebuffer bei A0000h, setzt den Gast fort und bittet das konfigurierte @vision-Modell der Verwaltung, das generierte PNG zu interpretieren. omp muss im PATH sein; verwenden Sie --vision-question, um die Eingabeaufforderung anzupassen. Snapshot-Befehle pausieren nur zur Inspektion und trennen die Verbindung vor der Modellinferenz.

2. Memdump-Server (kein GDB-Stub, keine CPU-Pause): Setzen Sie memdump_port in der VM-Konfiguration. Fragen Sie den Text-Framebuffer mit einer Live-Delta-Ansicht ab:

   ./screenmon.py --memdump-port 12348            # interaktives TTY: ANSI-Delta
   ./screenmon.py --memdump-port 12348 --plain   # weitergeleitet: vollständiger Frame + geänderte Zeilen
   ./screenmon.py --memdump-port 12348 --count 30 --interval 0.1
   

   screenmon.py rendert nur das, was sich zwischen den Abfragen geändert hat; der Modus wird von isatty() bestimmt, es sei denn, --full/--plain überschreibt ihn. Das Standardintervall beträgt 0,1 s.

Für den kontinuierlichen bidirektionalen Betrieb:

# Interaktiver ANSI-Spiegel; Strg-] trennt die Verbindung
RSP_PORT=<port> ./guest_console.py

# Verarbeitbare Bildschirm- und Delta-Ereignisse
RSP_PORT=<port> ./guest_console.py \
  --format jsonl --no-input --duration 10

# Geben Sie einen DOS-Befehl über den BIOS-Ring ein
RSP_PORT=<port> ./guest_console.py \
  --send "DIR" --enter --duration 10

# Frühes POST erfordert Hardware-Scan-Code-Injektion
RSP_PORT=<port> ./guest_console.py \
  --input-mode hardware --key F1 --duration 5

Die Konsole tastet mit 70 Hz ab, behält den vollständigen Zeichen-/Attributpuffer und gibt nur zusammengefasste geänderte Läufe aus. Ein TTY erhält ANSI-Cursor-Updates; weitergeleitete Ausgabe standardmäßig im JSONL-Format. Die Eingabe standardmäßig über den validierten BIOS- Tastaturring nach dem Booten. Der Hardware-Modus injiziert getaktete Set-1-Scan-Bytes durch den emulierten 8042 für POST. Behalten Sie Strg-] zum Trennen bei, damit Gast-Strg-C verfügbar bleibt.

Schließen Sie nie allein aus einem injizierten Tastendruck auf Erfolg. Beobachten Sie das resultierende Bildschirm-Delta oder die explizite Gastausgabe.

Dauerhafte VM-Konfiguration

Überprüfen Sie nach einer sauberen Abschaltung nur das aufgelöste VM-Verzeichnis:

<VM>/86box.cfg
<VM>/nvr/<machine>.nvr
<VM>/nvr/<machine>_sec.nvr

Für dieses Repository:

uv run --project . refdisk-view-config --vm <NAME> --adf-source rf7080a/disk

Das Hinzufügen einer Karte in der 86Box-Oberfläche füllt nicht automatisch den Gast-MCA-NVRAM. Die Gast-Referenzdiskette muss den POS-Status konfigurieren und 86Box muss ihn sauber speichern.

ROM-Überprüfung

machine = ... bestimmt die erforderlichen ROM-Dateinamen. Überprüfen Sie:

1. den genauen --rompath, der von 86boxctl status aufgezeichnet wurde, falls vorhanden;
2. die .86boxctl-romset.json des generierten Satzes;
3. die genauen aktiven Dateinamen aus der 86Box-Maschinenbeschreibung;
4. Hashes oder Byte-Vergleiche dieser aktiven Dateien.

Für diesen Workflow muss ein expliziter --rompath den vollständigen 86Box-ROM-Satz enthalten. Obwohl 86Box auf andere Suchstämme zurückfallen kann, macht die Vollständigkeit den Lauf in sich abgeschlossen und verhindert stilles Mischen. Zeigen Sie nicht auf ein Verzeichnis, das nur eine Maschine enthält.

Für ein rohes sequentielles 128 KiB Model 80 Typ 2 Image verwenden Sie --model-80-type-2-rom. Der Controller schreibt:

machines/ibmps2_m80/15f6637.bin = input[0::2]  # niedrige/gerade Spur
machines/ibmps2_m80/15f6639.bin = input[1::2]  # hohe/ungerade Spur

Beide Dateien sind 65.536 Bytes groß; ihre Verschachtelung muss die Eingabe reproduzieren. start und restart erstellen oder validieren das isolierte Klon automatisch:

./86boxctl.sh <VM> prepare-roms \
  --model-80-type-2-rom /pfad/zu/sequentiell-128k.bin
./86boxctl.sh <VM> status

Standardeinstellungen sind die Standard-86Box-ROM-Stämme: macOS Application Support, XDG_DATA_HOME/XDG_DATA_DIRS unter Unix und Local/Program/AppData unter Windows. Überschreiben Sie mit --rom-source PATH oder 86BOX_ROM_ROOT. --refresh-rom-set erstellt nur ein erkanntes generiertes Verzeichnis neu.

Sicherungs-Suffixe wie .orig und .altered werden nicht automatisch ausgewählt. Bewahren Sie gemeinsame Originale auf.

Für einen End-to-End-Beweis mit einem echten GDB-Stub-fähigen 86Box-Prozess:

./model80_rom_smoke.py <MODEL80_VM>

Erfordert machine = ibmps2_m80, cpu_use_dynarec = 0 und einen eindeutigen gdbstub_port. Die Verwaltung leitet ein sequentielles Image aus den Standard-Spuren ab, ändert KB OK zu OKBMR, repariert die 64 KiB-Prüfsumme, startet durch den isolierten vollständigen ROM-Klon, beobachtet OKBMR im Gast-Text-VRAM und stoppt nur seine aufgezeichnete PID. Verwenden Sie --keep-running nur, wenn eine manuelle Inspektion erforderlich ist.

Stoppen oder Wiederherstellen

Bevorzugen Sie eine saubere UI-Beendigung und bestätigen Sie dann, dass der verfolgte Prozess beendet wurde. Wenn eine Steuerung erforderlich ist:

./86boxctl.sh <VM> stop
./86boxctl.sh <VM> restart

stop sendet SIGTERM nur an die identitätsgeprüfte PID und beendet sie nicht stillschweigend mit Gewalt. Verwenden Sie --kill-after-timeout nur, nachdem Sie einen möglichen NVRAM- oder Konfigurationsverlust akzeptiert haben.

Bei einem Absturz:

1. erfassen Sie status und logs;
2. bestätigen Sie, dass der Datensatz zur beabsichtigten VM gehört;
3. starten Sie nur diesen Datensatz neu;
4. notieren Sie die neue PID;
5. kehren Sie zum vorherigen Warte- oder Beobachtungsschritt zurück.

Abschlussnachweise

Bevor Sie über einen Erfolg berichten, legen Sie die für die Aufgabe geeigneten Nachweise vor:

• genauer VM-Pfad und Maschinenkennung;
• Binärdatei und exakter Startbefehl;
• stabiler Prozessname und aktuelle PID;
• Betriebsbereitschaftsnachweis;
• sauberer Beendigungs- oder Absturzstatus;
• relevante Konfigurations-/NVRAM-Pfade und -Größen;
• Gast-Bildschirm, -Register, -Speicher oder decodierte Konfigurationsausgabe.

Siehe README.md für Implementierungsdetails, GDB-Stub-Besonderheiten, ROM-Suche und Fehlerdiagnose.