# daveemu

daveemu is a modern IBM PC/AT style emulator focused on a clean user experience, deterministic behavior, and practical performance. The current release is aimed at running classic DOS-era software with a convenient SDL-based frontend, persistent settings, and optional automation features such as HTTP control.

## Package Contents

- `daveemu_gui` or `daveemu_gui.exe`: main interactive frontend
- `data/bios/bios286.bin`: bundled BIOS image used by the emulator
- `data/ttf/...`: bundled fonts used by the UI
- platform-specific runtime libraries required by the release build

Run the emulator from the extracted release directory so it can find the bundled `data/` files next to the executable.

## Quick Start

Linux:

```bash
./daveemu_gui --bios data/bios/bios286.bin --floppy /path/to/disk.img
```

Windows:

```powershell
.\daveemu_gui.exe --bios data\bios\bios286.bin --floppy C:\path\to\disk.img
```

If you want to boot from a hard disk image instead of a floppy:

```bash
./daveemu_gui --bios data/bios/bios286.bin --hdimg /path/to/disk.img
```

## Common Launch Options

| Option | Meaning |
| --- | --- |
| `--bios <path>` | BIOS ROM path. Optional for release packages: if omitted, daveemu tries `data/bios286.bin` and `data/bios/bios286.bin` next to the executable. |
| `--floppy <path>` | Boot from a floppy image. |
| `--hdimg <path>` | Use a raw hard disk image. |
| `--mount-folder <path>` | Mount a host folder as a guest drive. |
| `--mounted-size <N[K\|M]>` | Size of the mounted virtual disk, up to 2 GB. |
| `--width <N>` / `--height <N>` | Window size in pixels. |
| `--scale <N>` | UI scale factor. |
| `--target-mhz <N>` | Emulated CPU speed. Default is `12`. Use `0` for uncapped speed. |
| `--target-fps <N>` | Frame-rate cap. Default is `60`. |
| `--ram <N[K\|M]>` | RAM size. Default is `4M`. |
| `--vram <N[K\|M]>` | VRAM size. Default is `512K`. |
| `--software-renderer` | Force software rendering instead of hardware acceleration. |
| `--renderer-mode hardware|software` | Explicit renderer selection. |
| `--font pixel|ttf|ttf-hires` | UI font mode. Default is `ttf`. |
| `--mouse-capture` | Start with relative mouse capture enabled. |
| `--http-control` | Enable the built-in HTTP control server. |
| `--http-control-host <addr>` | Bind address for HTTP control, default `127.0.0.1`. |
| `--http-control-port <N>` | Port for HTTP control, default `7070`. |
| `--with-hdd-sounds` | Enable HDD sound effects. |
| `--hdd-sounds-config <path>` | Custom HDD sound configuration file. |
| `--emu-config <path>` | Optional emulation tuning file for HDD timing and related behavior. |
| `--verbose-log` | Enable more detailed logging. |
| `--log <path>` | Custom log file path. |
| `--offscreen` | Run headless/offscreen for automation. |
| `--help` | Print the command-line usage summary. |

## Mounted Folder Workflow

`--mount-folder` creates a FAT16 `drive_d.img` from a host folder and attaches it as guest drive `D:`. This is the recommended workflow for automation, source exchange, and artifact export because it avoids repeated patching of the system `C:` image.

Typical launch:

```bash
./daveemu_gui --bios data/bios/bios286.bin --hdimg /path/to/c.img --mount-folder /path/to/workdir --mounted-size 16M
```

How it works:

- `virtdisk` builds and updates the mounted FAT16 image from the host folder.
- The mounted image is attached as guest drive `D:`.
- The frontend watches `drive_d.img` for changes and reattaches drive `D:` when the image is rebuilt.
- The machine runtime invalidates the cached DOS drive state for `D:` after reattach so directory and file reads become visible deterministically inside the guest.

Current verified support:

- `MS-DOS 3.3`
- `MS-DOS 5.0`

The support rule is simple: a DOS version is considered supported only after the mount-sync E2E matrix passes for it. If you later add `MS-DOS 6.22` to the same tests and it passes, it can be treated as verified too.

Implementation locations in the source tree:

- image build and host sync: `virtdisk/src/folder_sync.cpp`, `virtdisk/src/fat16_builder.cpp`
- drive `D:` reattach in the frontend: `frontend/src/gui_main.cpp`
- DOS cache invalidation after attach / reload: `machine/src/machine.cpp`
- mount-sync E2E coverage: `tests_e2e/tests/test_virtdisk_mount_sync.py`

## Settings and User Data

daveemu saves GUI settings automatically. This includes values such as:

- window size and position
- target MHz and FPS
- UI scale
- renderer mode
- font mode
- selected shader and shader folder
- HDD sounds settings
- custom TTF path
- mouse capture preferences

Default settings file locations:

Linux:

- `$HOME/daveemu/settings.json`
- fallback existing locations: `$HOME/Documents/daveemu/settings.json`, `$HOME/daveemu_settings.json`

Windows:

- `%USERPROFILE%\\Documents\\daveemu\\settings.json`
- fallback existing locations: `%USERPROFILE%\\daveemu\\settings.json`, `%USERPROFILE%\\daveemu_settings.json`

You can override the settings path with:

```bash
DAVEEMU_SETTINGS_PATH=/custom/path/settings.json
```

## Optional Environment Variables

- `DAVEEMU_SETTINGS_PATH`: overrides the settings file location
- `DAVEEMU_EMU_CONFIG`: default path for `--emu-config`
- `DAVEEMU_HDD_SOUNDS_CONFIG`: default path for `--hdd-sounds-config`

## Notes

- Some settings take effect immediately, while others are applied on the next launch.
- If you switch between pixel and TTF-based font modes, a restart may be required for the cleanest result.
- The HTTP control server is intended for local automation and testing; by default it listens only on `127.0.0.1`.
