-
Notifications
You must be signed in to change notification settings - Fork 19
MartyPC User Guide
Thank you for checking out MartyPC! Documentation will be a little threadbare initially, but here are some basic instructions and tips.
The current release version of MartyPC is 0.2.2. This version of MartyPC supports CGA and EGA graphics. VGA support is planned.
The next release of MartyPC will be 0.3.0.
MartyPC reads the file martypc.toml to determine its configuration. TOML is similar to .INI files you may already be familiar with, but far more capable. You can edit it with any text editor, such as notepad. The configuration file contains many comments explaining the various options. Please be aware that some options may be experimental, disabled, or not yet implemented.
One of the first options you may wish to change is to choose a different machine configuration or configuration overlay.
Under the [machine] header, you can select a base configuration by setting the config_name key to the appropriate string. For example, config_name = "ibm5160" will select a base model IBM XT 5160.
config_name = "ibm5160_hdd" will specify a IBM XT with a hard disk controller. You will need to provide the appropriate Xebec HDC ROM file or this configuration cannot be run.
I generally recommend the IBM 5160 configuration, unless you are just curious about the 5150 for historical reasons. The basic hardware between the 5150 and 5160 was nearly identical, but the BIOS was improved. The 5160 can run all software that the 5150 can, including any demos you may be interested in seeing.
More information on the format of the MartyPC configuration file can be found here.
MartyPC by default is a GUI application, but it will print some messages on the command line which may be useful.
If MartyPC doesn't appear to run or it closes immediately, run it from the command line so you can view any error messages that might be output. The most common cause of MartyPC failing to start is a lack of required ROM files.
MartyPC's graphical display and GUI is hardware accelerated. It may have poor performance when run remotely via RDP, under virtualization such as VMWare Workstation or VirtualBox, or using a low-powered integrated adapter. The Performance view in the Emulator menu can tell you if you are running less than 60fps or if the emulated CPU is running less than 4.77Mhz. Please include a screenshot of the Performance window if you open any issues related to performance of the emulator.
See the FAQ section for some work-arounds for common graphical display issues.
MartyPC requires some ROM files for full functionality - please see the ROMS section for more information about what is required.
An open-source XT BIOS, GLaBIOS is provided with the distribution, so you don't need to hunt anything down to run a basic, XT-compatible machine. This BIOS is very compatible with legacy hardware and software, but you may wish to substitute an authentic original IBM BIOS for that nostalgic experience. If you have both sets of ROMs and wish to prioritize the original OEM ROMs over their modern equivalents, you can set the configuration parameter prefer_oem to true.
Separate, original IBM ROMs are required for hard disk, EGA or VGA support.
You must add the Xebec adapter ROM to be able to use a hard disk. If you select a machine configuration containing a hard disk controller and do not have the corresponding ROM, MartyPC will not start.
MartyPC uses VHD (Virtual Hard Disk) files for its hard disk images. A blank VHD image is included with the distribution. It will need to be partitioned and formatted with the OS of your choice. Most DOS installation floppies can handle this for you.
Due to the specific drive types required by the emulated hard disk controller, you must create compatible VHDs from within MartyPC via the Media menu.
Only one size is currently supported - just give it a name and it will be created in the '/media/hdd' directory.
Once you've created a VHD and mounted it, you'll need to partition the drive and format it. The easiest way to do this is to run one of the DOS distribution setup programs which can handle this for you. For more information on partitioning drives in DOS, you may wish to Google DOS FDISK usage or such, eventually I plan to create a short guide on the process.
Drives can be specified in a machine configuration, but you can also override the default VHD images loaded by specifying them in the main configuration.
To specify a hard disk to load by default, specify the VHD name under filename in an
[[emulator.media.vhd]] section in martypc.toml.
You cannot change VHDs while the machine is powered on. Power the machine off first and the menu option to change disks will be enabled. This is to protect against VHD corruption.
For information on working with floppy disk images, see this section of the wiki.
When working with floppies, it's important to be aware of the hardware and BIOS limitations of the time. Certain machines only supported certain floppy drive types. The original PC/XT only supported 360K/720K floppies, and only the 1986 BIOS revision of the XT supported the latter. The 1986 BIOS also included partial support for 1.2MB, high-density 5.25" drives. The included version of GLaBIOS has limited support for 720K floppies.
It is possible by modifying machine configurations to outfit a machine with a drive type that the machine will not properly function with. You'll need to do your research before assuming there is a bug in the emulator.
When using a BIOS version that did not support 720K disks, you may find that you can read a 720K disk fine. But if you format the disk, the resulting capacity will be 360k. You can create blank, formatted disks of a specified size within the Media menu as a work around.
MartyPC includes FreeDOS 1.3 just so you can have something to boot to right out of the box - however, this version of DOS has high memory usage and some programs and games may not run. You'll want to track down an earlier version of DOS. (I recommend 3.3 for machines of this era)
During single-stepping, F10 will step over and F11 will step into the next instruction. While stepping over, MartyPC may give up and breakpoint in an arbitrary location if the stepped-over instruction does not return within a certain cycle limit.
Due to a quirk of EGUI, you must have keyboard focus in any one of the input boxes in the GUI for your keys to be recognized by the debugger and not the guest machine. It doesn't matter which input box you use, F10 and F11 will be recognized globally as step and step over. This is a bit awkward, but it is tricky sharing the same keyboard with both the guest PC and user interface.
- Control-F10 will capture the mouse. Press Control-F10 again to release the mouse cursor.
- Control-F12 will reset the machine.
- Control-Enter will toggle the current window to fullscreen and back.
You can configure various hotkeys to your liking by editing the hotkeys entry under the
[emulator.input] section of martypc.toml.