JoshRodd/86Box-tool

Operações de VM 86Box

Use este skill sempre que uma tarefa exigir iniciar, configurar, aguardar, reiniciar, depurar ou inspecionar uma máquina virtual 86Box.

Regras de segurança não negociáveis

1. Resolva o diretório exato da VM antes de iniciar.
2. Inicie com --vmpath <diretório da VM> --vmname <nome de exibição>.
3. Rastreie o PID retornado para essa inicialização e o nome estável do processo harness.
4. Verifique a identidade do PID usando o executável e o --vmpath exato antes de qualquer sinal.
5. Nunca use killall, pkill amplo, pgrep amplo ou um PID não verificado.
6. Presuma que outras pessoas estão executando processos 86Box independentes.
7. Prefira o desligamento limpo pela interface quando NVRAM ou mudanças de configuração forem importantes.
8. Nunca sobrescreva ROMs compartilhadas para um experimento de uma única VM; clone um conjunto completo de ROMs e selecione-o com --rompath.

Pré-voo

1. Resolva um nome sob a raiz de VMs da plataforma. No macOS:

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

   Um caminho direto de VM também é válido.

2. Leia <VM>/86box.cfg. Registre:

   • machine;
   • cpu_use_dynarec;
   • gdbstub_port opcional;
   • dispositivos de mídia e adaptadores configurados.

3. Escolha o binário:

   • interação normal: /Applications/86Box.app/Contents/MacOS/86Box;
   • depuração do convidado: a compilação local com -DGDBSTUB=ON.

4. Audite o comando (execute a partir da raiz do projeto 86Box-tool, ou instale-o):

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

5. Ao depurar múltiplas VMs, exija um gdbstub_port distinto em cada configuração e cpu_use_dynarec = 0.

Inicialização

Controlador autônomo:

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

BIOS IBM PS/2 Model 80 Type 2 corrigida:

./86boxctl.sh <VM> command \
  --model-80-type-2-rom /path/to/sequential-128k.bin
./86boxctl.sh <VM> start \
  --model-80-type-2-rom /path/to/sequential-128k.bin

A VM deve usar machine = ibmps2_m80. O controlador descobre a raiz de ROMs padrão da plataforma, clona a árvore completa sob <VM>/romsets/, divide a imagem nos arquivos ativos de lane par/ímpar, valida-os e inicia com essa raiz gerada através de --rompath. Use --rom-source quando a descoberta for ambígua. Use prepare-roms para construir sem iniciar.

Para uma longa sessão GUI mediada pelo harness, inicie o executável através do gerenciador de processos harness com:

name        = nome estável único, como 86box-automatic-configuration
application = binário 86Box selecionado
args        = [--vmpath, <diretório VM absoluto>, --vmname, <nome de exibição>]
pty         = false
persist     = true quando a interação abranger vários turnos

Registre o PID retornado. Use apenas esse nome de processo estável para operações subsequentes de describe, logs, restart e stop. Uma reinicialização produz um novo PID; registre-o.

Não passe 86box.cfg como um argumento posicional único. Isso seleciona uma configuração, mas não define o caminho de arquivos de usuário da VM do 86Box, então mídias relativas, NVRAM e ROMs locais podem ser resolvidas contra o diretório errado.

Estabelecer prontidão

A criação do processo por si só não é prontidão do convidado.

• Compilação normal: exija que o processo exato sobreviva à inicialização, depois inspecione a VM visível ou um artefato concreto da VM.
• Compilação GDB: exija que a porta RSP configurada desta VM esteja ouvindo.
• Nunca interprete outro processo ou porta do 86Box como evidência para esta VM.

Use:

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

Aguardar um usuário

Quando o usuário disser para aguardar até uma interrupção do harness, faça exatamente isso. Não avance quando a VM sair, a menos que o usuário tenha solicitado trabalho acionado por saída. O waiter de trabalho do harness não trata um processo GUI gerenciado como um job em segundo plano; portanto, crie um sentinela longo de espera assíncrona finita, espere nesse job com um timeout de harness indefinido e cancele-o após a interrupção do usuário.

Mantenha o processo da VM rastreado separadamente por seu nome de processo estável e PID.

Observação

Ciclo de vida do host

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

Tela, console e memória do convidado

Dois caminhos independentes:

1. Stub RSP (requer a compilação com GDB-stub; conectar pausa o convidado):

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

   Nos modos de texto 0, 1, 2, 3 e 7, screen seleciona 40x25 ou 80x25, usa B8000h para cores ou B0000h para monocromático, e segue a página de vídeo ativa. No modo gráfico 11h, ele lê o framebuffer 640x480 1bpp compactado em A0000h, retoma o convidado e pede ao modelo @vision configurado do harness para interpretar o PNG gerado. omp deve estar no PATH; use --vision-question para personalizar o prompt. Comandos de snapshot pausam apenas para inspeção e se desanexam antes da inferência do modelo.

2. Servidor Memdump (sem stub GDB, sem pausa da CPU): configure memdump_port no arquivo de configuração da VM. Consulte o framebuffer de texto com uma visualização delta ao vivo:

   ./screenmon.py --memdump-port 12348            # TTY interativo: delta ANSI
   ./screenmon.py --memdump-port 12348 --plain   # pipe: quadro completo + linhas alteradas
   ./screenmon.py --memdump-port 12348 --count 30 --interval 0.1
   

   screenmon.py renderiza apenas o que mudou entre as consultas; o modo é escolhido por isatty() a menos que --full/--plain o substituam. O intervalo padrão é 0,1 s.

Para operação bidirecional contínua:

# Espelho ANSI interativo; Ctrl-] desanexa
RSP_PORT=<porta> ./guest_console.py

# Eventos de tela e delta processáveis
RSP_PORT=<porta> ./guest_console.py \
  --format jsonl --no-input --duration 10

# Digitar um comando DOS através do anel da BIOS
RSP_PORT=<porta> ./guest_console.py \
  --send "DIR" --enter --duration 10

# POST inicial requer injeção de scan-code por hardware
RSP_PORT=<porta> ./guest_console.py \
  --input-mode hardware --key F1 --duration 5

O console amostra a 70 Hz, retém o buffer completo de caracteres/atributos, e emite apenas execuções alteradas coalescidas. Um TTY recebe atualizações de cursor ANSI; saída redirecionada usa JSONL por padrão. A entrada padrão usa o anel de teclado validado da BIOS após a inicialização. O modo hardware injeta bytes de scan set-1 com pausa através do 8042 emulado para POST. Mantenha Ctrl-] para desanexar para que o Ctrl-C do convidado permaneça disponível.

Nunca infira sucesso apenas a partir de uma tecla injetada. Observe o delta da tela resultante ou a saída explícita do convidado.

Configuração persistente da VM

Após um desligamento limpo, inspecione apenas o diretório resolvido da VM:

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

Para este repositório:

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

Adicionar uma placa na interface do 86Box não preenche por si só a NVRAM MCA do convidado. O Disco de Referência do convidado deve configurar o estado POS e o 86Box deve salvá-lo de forma limpa.

Verificação de ROMs

machine = ... determina os nomes de arquivo de ROM necessários. Verifique:

1. o --rompath exato registrado por 86boxctl status, quando presente;
2. o .86boxctl-romset.json do conjunto gerado;
3. os nomes de arquivo ativos exatos da definição da máquina 86Box;
4. hashes ou comparações de byte desses arquivos ativos.

Para este fluxo de trabalho, um --rompath explícito deve conter o conjunto completo de ROMs do 86Box. Embora o 86Box possa recorrer a outras raízes de busca, a completude torna a execução autocontida e evita a mistura silenciosa. Não aponte para um diretório contendo apenas uma máquina.

Para uma imagem raw sequencial de 128 KiB do Model 80 Type 2, use --model-80-type-2-rom. O controlador escreve:

machines/ibmps2_m80/15f6637.bin = input[0::2]  # lane par/baixa
machines/ibmps2_m80/15f6639.bin = input[1::2]  # lane ímpar/alta

Ambos os arquivos têm 65.536 bytes; a intercalação deve reproduzir a entrada. start e restart criam ou validam o clone isolado automaticamente:

./86boxctl.sh <VM> prepare-roms \
  --model-80-type-2-rom /path/to/sequential-128k.bin
./86boxctl.sh <VM> status

Os padrões são as raízes de ROM padrão do 86Box: Application Support no macOS, XDG_DATA_HOME/XDG_DATA_DIRS no Unix e Local/Program/AppData no Windows. Substitua com --rom-source CAMINHO ou 86BOX_ROM_ROOT. --refresh-rom-set recria apenas um diretório gerado reconhecido.

Sufixos de backup como .orig e .altered não são selecionados automaticamente. Preserve os originais compartilhados.

Para uma prova de ponta a ponta usando um processo 86Box real com GDB-stub habilitado:

./model80_rom_smoke.py <MODEL80_VM>

Exija machine = ibmps2_m80, cpu_use_dynarec = 0 e um gdbstub_port único. O harness deriva uma imagem sequencial das lanes padrão, altera KB OK para OKBMR, repara o checksum de 64 KiB, inicia através do clone completo de ROM isolado, observa OKBMR na VRAM de texto do convidado e para apenas seu PID registrado. Use --keep-running apenas quando for necessária inspeção manual.

Parar ou recuperar

Prefira um desligamento limpo pela interface e confirme que o processo rastreado foi encerrado. Se o controle for necessário:

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

stop envia SIGTERM apenas ao PID com identidade verificada e não o força a terminar silenciosamente. Use --kill-after-timeout apenas após aceitar a possível perda de NVRAM ou configuração.

Em caso de falha:

1. capture status e logs;
2. confirme que o registro pertence à VM pretendida;
3. reinicie apenas esse registro;
4. registre o novo PID;
5. retorne à etapa anterior de espera ou observação.

Evidência de conclusão

Antes de relatar sucesso, forneça a evidência apropriada para a tarefa:

• caminho exato da VM e identificador da máquina;
• binário e comando de inicialização exato;
• nome do processo estável e PID atual;
• evidência de prontidão;
• status de saída limpa ou falha;
• caminhos e tamanhos relevantes de config/NVRAM;
• saída de tela, registradores, memória ou configuração decodificada do convidado.

Consulte README.md para detalhes de implementação, peculiaridades do GDB-stub, busca de ROMs e diagnóstico de falhas.