JoshRodd/86Box-tool

Operaciones con máquinas virtuales 86Box

Utiliza este skill cada vez que una tarea requiera iniciar, configurar, esperar, reiniciar, depurar o inspeccionar una máquina virtual de 86Box.

Reglas de seguridad no negociables

1. Resuelve el directorio exacto de la VM antes del lanzamiento.
2. Lanza con --vmpath <directorio VM> --vmname <nombre de visualización>.
3. Registra el PID devuelto para ese lanzamiento y el nombre estable del proceso del harness.
4. Verifica la identidad del PID usando el ejecutable y el --vmpath exacto antes de cualquier señal.
5. Nunca uses killall, pkill amplio, pgrep amplio o un PID no verificado.
6. Asume que otras personas están ejecutando procesos independientes de 86Box.
7. Prefiere un apagado limpio de la interfaz de usuario cuando la NVRAM o los cambios de configuración sean importantes.
8. Nunca sobrescribas ROMs compartidas para un experimento de una sola VM; clona un conjunto completo de ROMs y selecciónalo con --rompath.

Pre-vuelo

1. Resuelve un nombre bajo la raíz de VM de la plataforma. En macOS:

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

   Una ruta directa de VM también es válida.

2. Lee <VM>/86box.cfg. Registra:

   • machine;
   • cpu_use_dynarec;
   • gdbstub_port opcional;
   • los medios y dispositivos adaptadores configurados.

3. Elige el binario:

   • interacción normal: /Applications/86Box.app/Contents/MacOS/86Box;
   • depuración del invitado: la compilación local con -DGDBSTUB=ON.

4. Audita el comando (ejecuta desde la raíz del proyecto 86Box-tool, o instálalo):

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

5. Si depuras múltiples VMs, requiere un gdbstub_port distinto en cada configuración y cpu_use_dynarec = 0.

Lanzamiento

Controlador independiente:

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

BIOS parcheado IBM PS/2 Modelo 80 Tipo 2:

./86boxctl.sh <VM> command \
  --model-80-type-2-rom /ruta/al/archivo-secuencial-128k.bin
./86boxctl.sh <VM> start \
  --model-80-type-2-rom /ruta/al/archivo-secuencial-128k.bin

La VM debe usar machine = ibmps2_m80. El controlador descubre la raíz de ROMs estándar de la plataforma, clona el árbol completo bajo <VM>/romsets/, divide la imagen en los archivos de carril par/impar activos, los valida y lanza con esa raíz generada a través de --rompath. Usa --rom-source cuando el descubrimiento sea ambiguo. Usa prepare-roms para construir sin lanzar.

Para una sesión larga de GUI mediada por el harness, inicia el ejecutable a través del gestor de procesos del harness con:

name        = nombre estable único como 86box-automatic-configuration
application = binario 86Box seleccionado
args        = [--vmpath, <directorio VM absoluto>, --vmname, <nombre de visualización>]
pty         = false
persist     = true cuando la interacción abarca turnos

Registra el PID devuelto. Usa solo ese nombre de proceso estable para operaciones posteriores de describe, logs, restart y stop. Un reinicio produce un nuevo PID; regístralo.

No pases 86box.cfg como un argumento posicional solitario. Eso selecciona una configuración pero no establece la ruta de archivos de usuario de la VM de 86Box, por lo que los medios relativos, la NVRAM y las ROMs locales podrían resolverse contra el directorio incorrecto.

Establecer la preparación

La creación del proceso por sí sola no es preparación del invitado.

• Compilación normal: requiere que el proceso exacto sobreviva al inicio, luego inspecciona la VM visible o un artefacto concreto de la VM.
• Compilación GDB: requiere que el puerto RSP configurado de esta VM esté a la escucha.
• Nunca interpretes otro proceso de 86Box o puerto como evidencia para esta VM.

Usa:

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

Esperar a un usuario

Cuando el usuario dice esperar hasta una interrupción del harness, haz exactamente eso. No avances cuando la VM salga a menos que el usuario haya solicitado trabajo desencadenado por la salida. El esperador de trabajos del harness no trata un proceso GUI gestionado como un trabajo en segundo plano, así que crea un centinela de espera asíncrono finito largo, espera en ese trabajo con un tiempo de espera del harness indefinido, y cancélalo después de la interrupción del usuario.

Mantén el proceso de la VM rastreado por separado mediante su nombre de proceso estable y PID.

Observar

Ciclo de vida del anfitrión

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

Pantalla, consola y memoria del invitado

Dos rutas independientes:

1. Stub RSP (requiere la compilación con GDB-stub; la conexión pausa al invitado):

   RSP_PORT=<puerto> ./rsp.py probe
   RSP_PORT=<puerto> ./rsp.py video-mode
   RSP_PORT=<puerto> ./rsp.py screen
   RSP_PORT=<puerto> ./rsp.py wait-screen "texto esperado" --wait-timeout 600
   RSP_PORT=<puerto> ./rsp.py dump b8000 fa0
   

   En los modos de texto 0, 1, 2, 3 y 7, screen selecciona 40x25 u 80x25, usa B8000h para color o B0000h para monocromo, y sigue la página de video activa. En el modo gráfico 11h, lee el framebuffer empaquetado 640x480 1bpp en A0000h, reanuda el invitado y pide al modelo @vision configurado del harness que interprete el PNG generado. omp debe estar en PATH; usa --vision-question para personalizar el prompt. Los comandos de instantánea pausan solo para inspección y se separan antes de la inferencia del modelo.

2. Servidor Memdump (sin stub GDB, sin pausa de CPU): establece memdump_port en la configuración de la VM. Sondea el framebuffer de texto con una vista delta en vivo:

   ./screenmon.py --memdump-port 12348            # TTY interactivo: delta ANSI
   ./screenmon.py --memdump-port 12348 --plain   # redirigido: fotograma completo + filas cambiadas
   ./screenmon.py --memdump-port 12348 --count 30 --interval 0.1
   

   screenmon.py renderiza solo lo que cambió entre sondeos; el modo se elige mediante isatty() a menos que --full/--plain lo anulen. El intervalo predeterminado es 0.1 s.

Para operación bidireccional continua:

# Espejo ANSI interactivo; Ctrl-] se separa
RSP_PORT=<puerto> ./guest_console.py

# Eventos de pantalla y delta procesables
RSP_PORT=<puerto> ./guest_console.py \
  --format jsonl --no-input --duration 10

# Escribe un comando DOS a través del anillo del BIOS
RSP_PORT=<puerto> ./guest_console.py \
  --send "DIR" --enter --duration 10

# POST temprano requiere inyección de código de exploración de hardware
RSP_PORT=<puerto> ./guest_console.py \
  --input-mode hardware --key F1 --duration 5

La consola muestrea a 70 Hz, retiene el búfer completo de caracteres/atributos, y emite solo las ejecuciones cambiadas coalescidas. Una TTY obtiene actualizaciones de cursor ANSI; la salida redirigida por defecto es JSONL. La entrada por defecto es el anillo de teclado validado del BIOS después del arranque. El modo hardware inyecta bytes de exploración de conjunto 1 espaciados a través del 8042 emulado para POST. Mantén Ctrl-] para separar para que el Ctrl-C del invitado permanezca disponible.

Nunca infieras éxito meramente por una tecla inyectada. Observa el delta de pantalla resultante o la salida explícita del invitado.

Configuración persistente de la VM

Después de un apagado limpio, inspecciona solo el directorio de VM resuelto:

<VM>/86box.cfg
<VM>/nvr/<máquina>.nvr
<VM>/nvr/<máquina>_sec.nvr

Para este repositorio:

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

Añadir una tarjeta en la interfaz de usuario de 86Box no llena por sí sola la NVRAM MCA del invitado. El Disco de Referencia del invitado debe configurar el estado POS y 86Box debe guardarlo limpiamente.

Verificación de ROMs

machine = ... determina los nombres de archivo de ROM requeridos. Verifica:

1. el --rompath exacto registrado por 86boxctl status, cuando esté presente;
2. el .86boxctl-romset.json del conjunto generado;
3. los nombres de archivo activos exactos de la definición de máquina de 86Box;
4. hashes o comparaciones de bytes de esos archivos activos.

Para este flujo de trabajo, un --rompath explícito debe contener el conjunto completo de ROMs de 86Box. Aunque 86Box puede recurrir a otras raíces de búsqueda, la completitud hace que la ejecución sea autocontenida y evita la mezcla silenciosa. No lo apuntes a un directorio que contenga solo una máquina.

Para una imagen secuencial de 128 KiB del Modelo 80 Tipo 2, usa --model-80-type-2-rom. El controlador escribe:

machines/ibmps2_m80/15f6637.bin = entrada[0::2]  # carril bajo/par
machines/ibmps2_m80/15f6639.bin = entrada[1::2]  # carril alto/impar

Ambos archivos son de 65,536 bytes; entrelazarlos debe reproducir la entrada. start y restart crean o validan el clon aislado automáticamente:

./86boxctl.sh <VM> prepare-roms \
  --model-80-type-2-rom /ruta/al/archivo-secuencial-128k.bin
./86boxctl.sh <VM> status

Los valores predeterminados son las raíces estándar de ROMs de 86Box: macOS Application Support, XDG_DATA_HOME/XDG_DATA_DIRS en Unix, y Local/Program/AppData en Windows. Anula con --rom-source RUTA o 86BOX_ROM_ROOT. --refresh-rom-set reconstruye solo un directorio generado reconocido.

Los sufijos de respaldo como .orig y .altered no se seleccionan automáticamente. Conserva los originales compartidos.

Para una prueba de extremo a extremo usando un proceso real de 86Box con GDB-stub habilitado:

./model80_rom_smoke.py <VM_MODELO80>

Requiere machine = ibmps2_m80, cpu_use_dynarec = 0 y un gdbstub_port único. El harness deriva una imagen secuencial de los carriles estándar, cambia KB OK a OKBMR, repara la suma de comprobación de 64 KiB, lanza a través del clon de ROM completo aislado, observa OKBMR en la VRAM de texto del invitado y detiene solo su PID registrado. Usa --keep-running solo cuando se requiera inspección manual.

Detener o recuperar

Prefiere un apagado limpio de la interfaz de usuario, luego confirma que el proceso rastreado haya finalizado. Si se requiere control:

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

stop envía SIGTERM solo al PID verificado por identidad y no lo fuerza a terminar silenciosamente. Usa --kill-after-timeout solo después de aceptar una posible pérdida de NVRAM o configuración.

En caso de cuelgue:

1. captura status y logs;
2. confirma que el registro pertenece a la VM deseada;
3. reinicia solo ese registro;
4. registra el nuevo PID;
5. vuelve al paso de espera u observación anterior.

Evidencia de finalización

Antes de reportar éxito, proporciona la evidencia apropiada para la tarea:

• ruta exacta de la VM e identificador de máquina;
• binario y comando de lanzamiento exacto;
• nombre de proceso estable y PID actual;
• evidencia de preparación;
• estado de salida limpia o cuelgue;
• rutas y tamaños relevantes de configuración/NVRAM;
• pantalla del invitado, registros, memoria o salida de configuración decodificada.

Consulta README.md para detalles de implementación, peculiaridades del GDB-stub, búsqueda de ROMs y diagnóstico de fallos.