# openMSX Setup Guide

## Contents

## 1. Introduction

### 1.1 New Versions of this Document

The latest version of the openMSX manual can be found on the openMSX home page:

http://openmsx.sourceforge.net/manual/

You can also use this URL to get up-to-date versions of the hyper links if you printed out this manual.

### 1.2 Purpose

This guide is about openMSX, the open source MSX emulator that tries to achieve near-perfect emulation by using a novel emulation model. You can find more information about openMSX on the openMSX home page. You can also download the emulator itself from there.

openMSX is in alpha state, which means that some things work but not all features are implemented yet. Many emulation features are implemented, but in terms of user interface it is rather bare bones. However, because the emulation is already pretty good, it would be nice if non-insiders would be able to play with it, too. For those people, we have written this guide. It explains how you can get the emulator running on your system, i.e. how to get the sources and compile them.

This guide describes the setup of openMSX. After installation, openMSX is ready to run using C-BIOS and the default settings. In this guide you can read how to configure openMSX to emulate actual MSX machines (such as Panasonic FS-A1GT). It also describes how you can have openMSX start up with your personal settings, how you can configure openMSX and your system for optimal performance and several other configuration related topics.

Disclaimer: We do not claim this guide is complete or even correct. What you do with the information in it is entirely at your own risk. We just hope it helps you enjoy openMSX more.

### 1.3 Contributors

The following people contributed to this document in one way or another:

- Jorrith Schaap
- Manuel Bilderbeek
- Maarten ter Huurne
- other openMSX developers

Thanks to all of them!

### 1.4 Revision History

This section gives an overview of the changes that were made to this document. It doesn't contain every single modification (use the CVS log for that), only the big picture.

2005-02-19: Manuel Bilderbeek
  Various updates for version 0.5.1, mainly C-BIOS related.
2004-09-28: Manuel Bilderbeek
  Various updates for version 0.5.0.
2004-04-25: Manuel Bilderbeek
  Various updates for version 0.4.0.
2003-09-21: Maarten ter Huurne
  Split the Setup Guide off from the openMSX HOWTO. Converted to XHTML. Restructured the document. Rewrote some text to fit better in the new structure and format.
2002, 2003: Manuel Bilderbeek & others
  Various updates to the HOWTO.
2002: Manuel Bilderbeek & Jorrith Schaap
  Original text written as part of the openMSX HOWTO.

## 2. Machines and Extensions

We use the word machine to refer to a specific MSX model. For example, the Sony HB-75P is a machine. openMSX does not have a fixed machine hardcoded into it. Instead, many different MSX machines can be emulated. The details of a machine are described in an XML file. This file describes how much memory a machine has, what video processor it has, in which slots its system ROMs are located, whether the machine has a built-in disk drive etc. openMSX reads the machine description XML and will then emulate exactly that MSX machine, which can be anything from an MSX1 with 16K of RAM to the MSXturboR GT.

The openMSX distribution contains XML files describing many existing MSX models. You can find them in the `share/machines` directory. If you want to run one of those machines, you also need the system ROMs for that machine. See the next chapter for more information on system ROMs. You can also create your own machine descriptions, to expand existing MSX models or to create your own fantasy MSX. There is currently one such a fantasy MSX configuration that is based on a real MSX shipped with openMSX. It is called "Boosted_MSX2_EN", because it is a European MSX2 with loads of hardware built in. You can find some more information about it in the README file which is in its directory `share/machines/Boosted_MSX2_EN`. More about creating fantasy MSX machines in a later chapter.

An extension is a piece of MSX hardware that can be inserted into a cartridge slot to extend the capabilities of an MSX. Examples of extensions are the Panasonic FMPAC, the Sunrise IDE interface and an external 4MB memory mapper. Extensions, like machines, are described in XML files. You can find a lot of predefined extensions in the `share/extensions` directory. Some extensions need ROM images in order to run, similar to system ROMs.

## 3. System ROMs

An MSX machine consists of a lot of hardware, but also contains some software. Such software includes the BIOS, MSX-BASIC, software controlling disk drives and built-in applications (firmware). openMSX emulates the MSX hardware, but it needs MSX system software to emulate a full MSX system. Because the internal software is located in ROM chips, it is referred to as system ROMs.

The software in the system ROMs, like most software, is copyrighted. Depending on your local laws, there are certain things you are allowed to do with copyrighted software and certain things you are not allowed to do. In this manual, a couple of options are listed for providing system ROMs to your openMSX installation. It is up to you, the user, to select an option that is legal in your country.

### 3.1 C-BIOS

C-BIOS stands for "Compatible BIOS". It tries to be compatible with the MSX BIOS found in real MSX machines, but it was written from scratch, so all copyrights belong to its authors. BouKiChi, the original author of C-BIOS, was kind enough to allow C-BIOS to be distributed together with openMSX. Since then, Reikan took over maintenance of C-BIOS and the license was changed to give users and developers even more freedom in using C-BIOS. Even later, C-BIOS was moved to a SourceForge.net project, with several new maintainers. Every now and then, an updated version of C-BIOS is released. You can wait for it to be included in the next openMSX release, or download it directly from the C-BIOS web site.

C-BIOS can be used to run most MSX1, MSX2 and MSX2+ cartridge-based games. It does not include MSX-BASIC and does not support disk drives yet, so programs depending on that will not run. openMSX contains three machine configurations using C-BIOS. The machine `C-BIOS-MSX1` is an MSX1 with 64K RAM. The machine `C-BIOS-MSX2` is an MSX2 with 512K RAM and 128K VRAM. The machine `C-BIOS-MSX2+` is an MSX2+ with 512K RAM, 128K VRAM and MSX-MUSIC. The latter is the default machine for openMSX after installation, so if you change nothing to the openMSX configuration, then `C-BIOS-MSX2+` is the machine that will be booted.

It is always legal for you to run the C-BIOS ROMs in openMSX. You are allowed to use C-BIOS and its source code in various other ways as well, read the C-BIOS license for details. It is located in the file `README.cbios` in the Contrib directory.

### 3.2 Dumping ROMs

If you own a real MSX machine, you can dump the contents of its system ROMs to create ROM images you can run in openMSX. This way, you can emulate the MSX machines you are familiar with.

#### 3.2.1 Tools

The easiest way to dump system ROMs is to run a special dumping tool on your real MSX, which copies the contents of the system ROMs to disk. Sean Young has made such tools, you can find the tools and documentation on his web site. These tools can also be used to dump cartridge ROMs, which may be useful later, if you want to use certain extensions or play games.

#### 3.2.2 Legal Issues

Using ROMs dumped from machines you own is generally considered a proper thing to do in the MSX community. When the MSX machine was bought in a shop years ago, you or the person that originally bought it paid money for the MSX machine. A small part of that money paid for the software in the system ROMs. However, we are no legal experts, so it is up to you to check whether it is legal in your country to use dumped ROMs of machines you own.

### 3.3 Downloading ROMs

Some WWW and FTP sites offer MSX system ROMs as a download. Some MSX emulators include system ROMs in their distribution. Downloaded system ROMs can be used in the same way as system ROMs you dumped yourself, see the previous section.

It may be illegal in your country to download system ROMs. Please inform yourself of the legal aspects before considering this option. Whatever you decide, is your own responsibility.

### 3.4 Installing ROMs

#### 3.4.1 ROM Locations

After you dumped or downloaded the ROM images, copy them to the appropriate subdirectory called `roms` in the machine directory. For example, if you dumped the ROMs of a Philips NMS 8250 machine, copy them to `share/machines/Philips_NMS_8250/roms`. Look in the file hardwareconfig.xml for the file names openMSX expects the ROM images to have.

There is also an easier way. The so-called ROM pools: special directories where openMSX will look for ROM files. The default ROM pool is the `share/systemroms` directory. So, you can just as well put all your system ROMs in that directory.

#### 3.4.2 How to handle split ROMs

The machine configurations bundled with openMSX often refer to ROM files that span multiple 16K pages. For example, in the NMS 8250 configuration, the BIOS and MSX-BASIC are expected in a single 32K ROM image. If you created two 16K images when dumping or got those from downloading, you can concatenate them using tools included with your OS. In Linux and other Unix(-like) systems you can do it like this:

cat bios.rom basic.rom > nms8250_basic-bios2.rom

In Windows, open a command prompt and issue this command:

copy /b bios.rom + basic.rom nms8250_basic-bios2.rom

#### 3.4.3 Checksums

You can check whether you have the same images as the machine configuration was tested with using the `SHA1SUMS` file. This file contains checksums of ROM images that are known to work. You can compare the checksums of your ROM images to this file with the `sha1sum` tool. It is installed by default on most UNIX systems, on Windows you would have to download it separately. If the checksums match, it is almost certain you have correct system ROMs. If the checksums do not match, it could mean something went wrong dumping the ROMs, or it could mean you have a slightly older/newer model which contains different system ROMs.

The sha1sums are also included in the machine configuration files. This enables openMSX to find the right ROM file from one of the ROM pools. If the ROM is explicitly specified in the configuration file and the sha1sum doesn't match a warning will be printed.

## 4. User Preferences

Almost all user preferences can be done via the openMSX console, at openMSX run time. This is more thoroughly explained in the User's Manual. In short: you can save your settings with the `save_settings` command, which will save the settings in `~/.openMSX/share/settings.xml` (UNIX) or `My Documents\openMSX\share\settings.xml` (Windows), your personal settings file. The settings file will be loaded every time openMSX starts. You can still manually edit this file, but it is not really necessary anymore: just edit the settings from the console. Note that openMSX doesn't ship a `settings.xml` file anymore. If you save your settings for the first time, it is generated from the current settings, which may be the built in defaults.

One of the preferences is the default machine: the machine openMSX uses if you did not specify one on the command line. The name of this setting is `machine`.

A convenient setting is called `user_directories`. With this setting you can specify directories in which openMSX should look for to find files that you mention on the command line or in the openMSX console. If you have some big directory with a lot of disk images, e.g., you can add the path to the TCL list that holds the user directories with this setting, so that you don't have to specify the whole path anymore. Use this to make things just a little more comfortable. For example: `set user_directories "~/diskimages /mnt/datadisk/MSX-soft/diskimages ~/.openMSX/ROMs ~/.openMSX"` specifies four user directories in which is searched.

By using the `bind` command you can create custom key bindings. These bindings will also be saved as settings in your settings file if you issue a `save_settings` command.

The other settings are discussed in the User's Manual and in the file `doc/commands.txt`.

Previous versions of openMSX also had a possibility to specify `AutoCommands`. If you still want to let openMSX execute commands at start up, add those commands to the `init.tcl` file. This file can be placed in exactly the same directories as the `settings.xml` file. Note that you can put any Tcl command there, so you can also use it to specify aliases, for example. If you do not want to mess with the standard `init.tcl`, you can also specify another Tcl file to be loaded and executed on the openMSX commandline. For this, use the `-script` command line option, which has the filename of the Tcl script as argument.

## 5. Writing Hardware Descriptions

There are two ways to use extra devices in your emulated MSX: you can use an shipped extension (which is analogous to inserting a cartridge with the device into the MSX) or you can modify the hardware configuration file (which is analogous to open the MSX and build in the device). As in the real world, extensions are easier to use, but modifying the machine gives you more possibilities. Normal usage of machines and extensions is covered in the User's Manual; this chapter tells you how you can create or modify these hardware descriptions. By editing the XML files, you can for example increase the amount of RAM, add a built-in MSX-MUSIC, add a disk drive, create extra cartridge slots etc.

You can modify an MSX machine (e.g. to add devices) by editing the XML config file. So, let's make a copy of `machines/Philips_NMS_8250/hardwareconfig.xml` and put it in `machines/mymsx/` under the name of `hardwareconfig.xml`. It's the config we are going to play with; our custom MSX. Note: it is convenient to use the directory `~/.openMSX/share/machines` (UNIX) or `My Documents\openMSX\share\machines` (Windows) to store your home-made machines, instead of the openMSX installation directory.

The easiest thing to do is to copy and modify fragments from other existing configurations that can be found in `share/machines` or `share/extensions`. For example, to add an FMPAC to the 8250, just copy it from the `share/extensions/fmpac/hardwareconfig.xml` to some place in your `mymsx/hardwareconfig.xml` file (between the `<devices>` and `</devices>` tags!):

        <primary slot="2">
          <secondary slot="1">
            <FMPAC id="PanaSoft SW-M004 FMPAC">
              <io base="0x7C" num="2" type="O"/>
              <mem base="0x4000" size="0x4000"/>
              <sound>
                <volume>13000</volume>
                <mode>left</mode>
              </sound>
              <rom>
                <sha1>9d789166e3caf28e4742fe933d962e99618c633d</sha1>
                <filename>roms/fmpac.rom</filename>
              </rom>
              <sramname>fmpac.pac</sramname>
            </FMPAC>
          </secondary>
        </primary>

Don't forget to add the `fmpac.rom` file to the roms directory of your machine, or add the file with the mentioned sha1sum to one of your ROM pools.

Because we changed the FMPAC from extension to built-in device, we have to specify in which slot the FMPAC is residing inside the modified 8250. So, we should replace the `slot="any"` stuff, with a specified slot as you can see in the above fragment. The number in the `slot` attribute of the `<primary>` tag indicates the primary slot of the emulated MSX you're editing. In this case the second cartridge slot of the NMS-8250 is used. `<secondary>` means sub slot. If we leave it out, the slot is not expanded and the primary slot is used. If we use it like in the above example, it means that slot 1 (of the `<primary>` tag) will be an expanded slot. If a `<primary>` tag has the attribute `external="true"`, this means that the slot is visible on the outside of the machine and can thus be used for external cartridges like extensions and ROM software. As explained above, the parameter filename can be adjusted to the name of your (64kB!) FMPAC ROM file (note: if the file is not 64kB (65536 bytes) in size, it won't work). "mode" defines to what channel the FMPAC's sound will be routed by default. "sramname" specifies the file name for file in which the SRAM contents will be saved to or loaded from. The saved files are compatible with the files that are saved by the (real) FMPAC commander's save option.

After saving your config and running openMSX again, you should be able to get the FMPAC commander with `CALL FMPAC` in the emulated MSX!

In a similar fashion, you can also add an MSX-Audio device (`<MSX-AUDIO>`, note that some programs also need the `MusicModuleMIDI` device to detect the Music Module; this device is at the moment not fully implemented though), an empty SCC cartridge (`<SCC>`), etc. Just browse the existing existing extensions, the Boosted_MSX2_EN configuration file or the extensions and see what you can find.

Devices that contain ROM or RAM will have to be put inside a slot of the MSX, using the `<primary>` and `<secondary>` tags as is demonstrated with the above mentioned FMPAC example. Other devices don't need this. Remember that you can not put two devices that have a ROM in the same (sub)slot! Just use a new free subslot if you need to add such a device and all your primary slots are full. Devices that do not need a slot, like the MSX-Audio device, you can add as many as you like.

Another thing you may want to change: the amount of RAM of the MSX: change the "size" parameter in the `<MemoryMapper>` device config.

In principle all of the above mentioned things are also valid for extensions. The main difference is the fact that you should use `"any"` for the slot specification as was already mentioned above. Just compare the fragment above with the original FMPAC extension we based it on.

If you understand the basics of XML, you should be able to compose your MSX now! You can use the ready-made configurations in `share/machines` as examples.

## 6. Performance Tuning

This chapter contains some tips for tuning the performance of openMSX on your system.

### 6.1 OpenGL

The SDLGL renderer needs hardware acceleration to run at a decent speed. If your OpenGL driver is not hardware accelerated, use the SDL renderer instead. If you have hardware accelerated OpenGL, but an older graphics card, try disabling scanlines, blur and glow (set them to 0).

For OpenGL under Linux, you might have to take some additional steps to get it hardware accelerated. If you have an nVidia card, go to the nVidia web site for drivers, which include an OpenGL implementation. ATI users can check out the ATI web site for drivers. For other cards, try Mesa, which can be found in packages like `xlibmesa-gl` and `xlibmesa-gl-dev` (Debian) or `XFree86-GLX` and `XFree86-GLX-devel` (SUSE).

You need to have the GLX module loaded in your X server and also accelerated graphics (DRI). You can verify this by typing `glxinfo` on the command line.

### 6.2 Various Tuning Tips

CPU and graphics performance varies a lot, depending on the openMSX settings and the MSX hardware and software you're emulating. Some things run fine on a 200MHz machine, others are slow on a 2GHz machine.

If openMSX runs slow, you can try the following measures:

- Make sure there are no CPU or I/O heavy background processes is running. Downloads, P2P software, distributed calculation efforts, search indexers etc may grab the CPU from time to time, leaving less time for openMSX to do its job. Even if they only do so only once in a while, it may be enough to cause emulation to stutter.
- Use 16-bit colour mode ("High Colours", "65536 colours") instead of 32-bit ("True Colours", "millions of colours"). openMSX uses your platform's default setting.
- Increase the number of frames that may be skipped (`set maxframeskip 10`, for example).
- Use a `scale_factor` of 1 with the SDL renderer (75% less pixels to fill). For most games (and any MSX1 software) it works perfectly, especially when using full screen. The drawback: no special effects at all, not even scanlines.
- Use a lower sound mixing frequency, for example 22050Hz instead of 44100Hz. Use the `frequency` setting for this.
- Use less sound channels, for example use MSX-MUSIC (maximum 9 channels) instead of MoonSound (maximum 18+24 channels).

## 7. Contact Info

Because openMSX is still in heavy development, feedback and bug reports are very welcome!

If you encounter problems, you have several options:

1. If you're a regular user and want to discuss openMSX and possible problems, join our `openmsx-user` mailing list. More info on the openMSX mailing lists, including an archive of old messages, can be found at SourceForge.
2. Go to our IRC channel: `#openMSX` on `irc.freenode.net` and ask your question there.
3. If you want to address the openMSX developers directly, post a message to the `openmsx-devel` mailing list. More info on the openMSX mailing lists, including an archive of old messages, can be found at SourceForge.
4. Use one of the openMSX trackers at SourceForge. At the moment of writing, there are four trackers: Bugs, Support Requests, Patches and Feature Requests.
5. Post a message on the forum on www.openmsx.org or the openMSX forums at SourceForge.

For experienced users: if you get a crash, try to provide a `gdb` backtrace. This will only work if you did not strip the openMSX binary of its debug symbols.

In any case, try to give as much information as possible when you describe your bug or request.

$Id: setup.html,v 1.32 2005/12/12 22:03:26 manuelbi Exp $