-
Notifications
You must be signed in to change notification settings - Fork 33
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.4.0. The next release of MartyPC will be 0.4.1.
MartyPC's distribution includes everything you need to start an XT system with CGA graphics and a 32MB hard drive. Just run the main martypc executable and go! If you wish to change machine types, you will need to either edit MartyPC's configuration file, or provide command-line arguments to martypc to change certain parameters.
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 an IBM/Xebec hard disk controller. You will need to provide the appropriate Xebec HDC ROM file or this configuration cannot be run.
config_name = "ibm5160_xtide" will specify an IBM XT with an XT-IDE hard disk controller - this controller has its ROM bundled with MartyPC and is the easiest way to get a hard drive up and running. As of 0.4.0, it is the default machine configuration.
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. If there is an error on startup, it should display some error message. The most common sources of startup errors are TOML configuration syntax errors, if you edited one of the configuration files, or a lack of a required ROM. Read any error messages carefully - please include screenshots of any errors you encounter when reporting issues.
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 file parameter prefer_oem to true.
Separate ROMs are required to use the IBM/Xebec Hard Disk Controller, or the IBM EGA card.
As of 0.4.0, MartyPC emulates an XT-IDE controller, which has an open-source BIOS ROM I can distribute with MartyPC. Therefore, MartyPC is configured with a 32MB hard drive out of the box, and there is nothing further you need to do.
If you wish to experiment with a more authentic IBM/Xebec hard disk controller, you'll need to source the the Xebec adapter ROM. 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 32MB DOS 3.30 formatted hard disk is supplied for you. It does not have a full DOS 3.30 distribution due to copyright - Microsoft has not yet released 3.30 as open-source, as it has 2.0 and 4.0. You can copy the files off DOS 3.30 diskettes into C:\DOS to complete a 3.30 installation, or you can reformat the drive with a newer version of DOS if you so choose.
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.
If using the IBM/Xebec hard disk controller, only one size is currently supported, 20MB.
Once you've chosen a size, give your new VHD 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 SvarDOS just so you can have something to boot to right out of the box - however, you may wish to source your own copy of MS-DOS to maximize available memory and program compatibility. I recommend DOS 3.3 for XTs and XT compatible class machines, but be aware that 3.3 has a partition limit of 32MB.
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.