Configuration
If you run Halfix by double-clicking on the program icon or running it from the command line without any arguments, it will load a set of configuration options from default.conf. A sample default.conf that does absolutely nothing is located in the repository root.
The vast majority of the configuration file is made up of key=value pairs. Both keys and values are case sensitive. All whitespace is ignored until the first non-space character. Thus, the following configuration parameters are functionally identical:
bios=bios.bin
bios =bios.bin
bios = bios.bin
bios = bios.bin
However, the following are not:
bi os=bios.bin
bios=bios . bin
All key-value pairs are terminated by a newline.
Comments begin with a # and go all the way until the end of the line. No other comment syntax is currently supported.
Section names are enclosed in brackets. They are case sensitive and must not contain any spaces.
Invalid keys and their values are silently ignored.
In the past, option order mattered. With the new INI parser (src/ini.c), it does not. Aside from the Default section, section order does not matter either.
All paths are interpreted relative to the current working directory.
This section contains generic options that don't have to do with one category or another. This section is implicitly defined at the start of the function. All key=value pairs in this section must come before the first explicitly named section. There is no [default] section header.
Path to BIOS image. I recommend the Bochs BIOS image in this repository. You can also use SeaBIOS.
Note: The BIOS image is slightly patched. The stock Bochs BIOS image does not handle asynchronous disk writes properly. There's a patch for this somewhere in the repository.
Path to VGA BIOS image. I recommend the LGPL'ed VGA BIOS. For SeaBIOS, you may want to use SeaVGABIOS. If you want, you can also use the ET4000 VGA BIOS ROM.
Total system RAM available to the host OS. This amount must be smaller than 3.5 GB because of how memory mapped I/O is implemented. It must be greater than 1 MB. The default is 32 MB.
You can add the K (KB), M (MB), and G (GB) suffixes to the number you specify. memory=256M is equal to memory=33554432
Same as above, except for VGA RAM. The VGA controller must have at least 256 KB RAM to function normally. The larger you set this number, the larger the maximum VBE screen size will be.
Set this to 0 if you wish to disable PCI. Set this to any non-zero number if you wish to enable PCI. If PCI is enabled, then the system will function as if a PCI controller is not present at all in the system. If you choose to disable PCI, there is no way to enable it while the VM is running.
Enables/disables the Advanced Programmable Interrupt Controller. If APIC is disabled, then the system will function as if an APIC is not present in the CPU. Enabling the APIC will also enable the I/O APIC.
Enables/disables the Advanced Configuration and Power Interface.
Enables/disables the floppy disk controller. If the floppy disk controller is disabled, the system will function as if a floppy disk controller is not attached to the computer.
In some cases, the emulator may crash because a floppy disk controller command has not been implemented yet. You may want to disable this option unless you absolutely need to virtualize a floppy controller.
This option overrides everything in the fda and fdb sections.
Enables/disables VBE emulation. Setting this option to zero disables the VBE I/O interface.
Enables/disables PCI interface for VGA. This is incomplete, so it is disabled by default. This option must be enabled for SeaBIOS to work.
The emulator supports four disk drives -- primary master (ata0-master), primary slave (ata0-slave), secondary master (ata1-master), and secondary slave (ata1-slave). Each of them are their own section. Regardless of how many disks you insert, Halfix will always emulate two disk controllers (primary and secondary). I recommend mounting all your disks on the primary controller since operating system support for the secondary controller is flaky.
Pay particularly close attention to these settings while booting Windows NT! It is very specific about the configuration of your disks.
A sample ataX-{master|slave} section goes as thus:
[ata0-slave]
inserted=1
file=xp.iso
driver=sync
type=cd
The following headings are options that can go with each disk drive:
Either hd, cd, or none. This will determine the drive type. To be specific, hd will allow the ATA IDENTIFY command to be run, and cd will allow ATAPI IDENTIFY. This option will also change how the hard disk signatures are set.
none will report that there aren't any controllers connected to the bus at all.
Controls whether the drive has media inserted or not. Set inserted to zero if you have a drive that should report itself as a disk/CD-ROM drive, but you don't have any media that you wish to insert.
This option is useful when booting Windows NT, which is really picky about what kind of disks it boots with. My installation of NT 4.0, for instance, is configured like this:
[ata0-master]
inserted=1
type=hd
file=disks/nt-install
[ata0-slave]
inserted=0
type=cd
There are two block device drivers: the "standard" driver (the one that uses all those chunked up files, and it 's the only option on Emscripten) and the "sync" driver (the one that works on raw hard disk images).
The default format is standard. We do not autodetect. Now we do!!
The path to the disk image. Point this to a folder for the standard driver, point this to a disk image for the sync driver.
Halfix supports two floppy disk drives. They are fda and fdb, each of them their own sections. Their options are identical to the ones for the hard disks/CD-ROMs above. In fact, they use the same backends.
Select boot order: a, b, and c.
Options are hd, cd, and none.