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.
This manual 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, unless you use the optional Graphical User Interface dubbed openMSX Catapult, which has separate manuals for now. 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 make use of the features of the emulator, once you have got it running.
This manual tells you how you can use openMSX, once it has been installed and properly set up. You should be able to use most of the features of openMSX if you have read it. If you are using using openMSX with Catapult, you don't have to pay attention to the exact command and setting names. However it is still useful to read this document to find out how openMSX works and learn its terminology.
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.
The following people contributed to this document in one way or another:
Thanks to all of them!
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.
In this chapter we will tell you how to select MSX machines and how to use extension cartridges.
If you start openMSX without any command line parameters, you will get the default machine, which is stored in the machine
setting, see the Setup Guide. If you did not change the default machine, you will get the C-BIOS MSX2+ machine.
To select a different MSX machine, use the -machine
command line argument:
The C-BIOS machines come with ROMs installed; for other machines you will have to install system ROMs yourself, see the Setup Guide for details.
Extensions are simply MSX cartridges (extensions to the MSX system) that you can plug into the emulated MSX. openMSX ships with a lot of predefined extensions. Note that many of them require firmware ROMs to be installed in the share/extensions/name/roms
directory or in share/systemroms
.
We will use the FMPAC as an example. openMSX ships with a definition (XML file) for the FMPAC extension, but you will have to add the fmpac.rom
firmware ROM yourself. When you have done so, you can insert an FMPAC into the emulated MSX machine with the following command line:
If you look in the share/extensions
directory, you will see all the extensions known to openMSX. For example -ext mbstereo
gives you the MoonBlaster stereo effect: FMPAC on the left speaker and MSX-AUDIO on the right speaker.
Often used other command line options will be discussed later in this manual. For a complete list of them, type the following command:
openMSX has a built-in command interface called the console, which allows you to control various aspects of openMSX while it is running. You can access the console by pressing F10 (with default key mapping) when the focus is on the emulator window. This will give you a command line in the openMSX window.
Typing help
gives a list of commands. Using PageUp you can see all of them.
If you type help [command]
you will get help
for the specified command.
This manual describes a few important commands;
a full list can be found in the file doc/commands.txt
.
The console can be used to change disk images, plug in joysticks or mice,
change settings at run time and to change key bindings, among others.
One very practical feature of the console command line is that you can use "completion" features. Just try typing half a command and then press the TAB key; openMSX will then try to finish the word you were typing or show the possibilities in case of ambiguities. You can use it also for file names, connectors, pluggables and settings.
You can reset your MSX with the Console command reset
and exit openMSX with the command exit
. Other commands will be discussed later on in this manual.
An interesting console command is set
. You can use it to change the various
settings. E.g., you can use it to set the current renderer. If you issue set with only the setting (like set renderer
), you will get the current value of that setting.
Settings that have only two possible values can also be toggled with the toggle
command (an example is the default key binding of F12 to toggle
fullscreen
, see also below). A complete list of settings should also be in the file
commands.txt
in the doc
directory. Note that using the "tab completion" feature can help you a lot in getting an idea of what settings are possible, as it will only complete possible options. Just try that.
If the MSX goes too fast or too slow, adjust the emulation speed with the
speed
setting, which has the speed percentage as parameter. So, typing set
speed 120
, will let the emulated MSX run at 120% of normal MSX speed. This is useful for debugging purposes (slow down) or when you want to skip certain parts of a demo for example (speed up).
If you got the MSX sped up to maximum (set throttle off
), but
openMSX is still not going fast enough for you, you can increase the
maxframeskip setting: set maxframeskip 10
will mean that openMSX may
skip 10 screens to be displayed, just to get to the requested speed. Note that
you can also force openMSX to skip frames, with the minframeskip setting. This
sets the amount of frames that will be skipped always. Of course frame skipping
makes emulation a lot less accurate.
Some MSX machines like the Panasonic FS-A1GT have built in software (called firmware), that can be switched on and off via a switch on the machine itself. In openMSX the internal software is switched off by default, but you can switch it on with the following setting: set firmwareswitch on
.
If you're not really interested in how long a real MSX would take for loading from diskette or cassette, you could enable the full speed when loading feature: set fullspeedwhenloading on
. It runs openMSX at maximum speed whenever it thinks that the MSX is loading. The drawbacks: it might detect a bit too late that the MSX isn't loading anymore, so sometimes the first notes of music played right after loading might be too fast. Also, when loading openMSX will use all CPU power it can get to get the maximum speed.
You can save all your current settings with the save_settings
command. If you specify a file name after this command, the settings will not be saved to the default settings file (share/settings.xml
), but to the specified file. At start up, alternative settings files can be loaded by using the -setting
command line option. You can also use the load_settings
command to load settings at run time. Settings that are not mentioned in the saved settings file that you are loading will be untouched. If you want openMSX to automatically save your settings when it exits, issue the following setting: set save_settings_on_exit true
.
The console command plug
can be used to plug the so called pluggables (devices) into connectors on the MSX. Examples of connectors are the joystick ports, the printer port, the MIDI in and out connector, the cassette port, etc. Examples of pluggables are joysticks and mice (see below), but also printer loggers and MIDI equipment. The command plug
without any parameters will show a list of connectors and what pluggables are plugged into them. Using plug [connector]
will only show what is plugged into [connector]. You will not be surprised that the command plug [connector] [pluggable]
will plug the [pluggable] into the [connector].
Note that using the "tab completion" feature can help you a lot in getting an idea of what plug commands are possible, as it will only complete possible connectors and their possible pluggables. Also just try this.
With this information, you can run most of the existing MSX software.
Suppose you want to run the ROM file galious.rom
. Then you simply type:
and the emulated MSX will run the game. (Of course,
in this case, the file galious.rom
should be in the current directory or in one
of the user directories you specified with the user_directories
setting, see the Setup Guide.)
You can also explicitly indicate that the thing is a ROM image like this:
This lets openMSX know that the file galious.gam
is a ROM cartridge and that openMSX should insert it in the first available free cartridge slot. You can also use -carta
to explicitly specify cartridge slot A.
Or, maybe openMSX didn't have the ROM in the ROM database and failed auto detection of the mapper type. You can specify the mapper to Konami
(formerly known as KONAMI4
) like this:
Note that in practice you won't need this, because most ROM images are in the database or auto detected if they are not. The -romtype
option should follow the ROM it applies to immediately on the command line.
If wanted, openMSX can apply IPS patches to ROM software before running it. IPS patches are files that describe a modification of the ROM you are applying it to, e.g. a translation or a cheat. This way you do not need to alter any files. To apply an IPS patch you have to provide the IPS filename like this:
As with the -romtype
option, the -ips
option on the command line must follow the ROM file it applies to directly. You can also use multiple -ips
options if you want to apply multiple patches.
To run a disk image, you can type:
for example. Or, if you use a disk image with an extension that is unknown to openMSX:
You can also change disks at run time of course. Just type
in the console to put the specified disk image in drive A. To eject the disk from drive A, use:
Note that inserting another disk image automatically ejects the previous one.
Disk images in XSA format are also supported, use them as regular disk images, but do note that they are read only. The same counts for (g)zipped disk images. Note that in zipped disk images the first file that is packed into the zip file will be used as disk image.
If wanted, openMSX can also apply IPS patches to disk software before running it. This way you do not need to alter any files. To apply an IPS patch you have to provide the IPS filename like this:
The -ips
option must follow directly the disk image on the command line it applies to. You can also use multiple -ips
options if you want to apply multiple patches.
You can also apply the patches when changing disks at run time. Just type something like
in the console to put the specified disk image SDSNAT1C.DSK in drive A, with both IPS patches applied.
The DirAsDsk feature permits you to use a directory on your host computer's file system as a disk image for your emulated MSX. Note that this has nothing to do with harddisk emulation. It simply creates a virtual disk structure in memory from the files that are in the directory that you specified as if it were a disk image. So:
will try to put all files of the current directory on a disk image in memory and start openMSX with it. The actual data is still read from/written to the files in your directory so that if you change the content of the files, these changes are immediately visible to the emulated MSX. This way you can for instance edit source files with your favourite text editor but compile them immediately in the emulated MSX.
Adding files on the host OS doesn't have any effect on the disk in openMSX and vice versa.
Be careful when writing to files from your emulated MSX.
If you save an existing file on that disk in the emulated MSX (without
increasing the file size), the change is also reflected on the directory on the
host OS! If the files are bigger than the original size then the extra data
sectors needed will be stored in a hidden sector cache and the extra data will
not be reflected in the host OS files! When stopping the emulator, or
ejecting the fake disk, this sector cache is written in the same directory as
the original files, so that it can be loaded again when restarting the emulator.
So if you use the DirAsDsk feature on a real floppy disk, chances are that
you'll end up with a full disk when this cache is written!
Note that this feature is willfully kept very bare bones: it doesn't support sub directories and it skips all remaining files if the virtual disk is full. Its main purpose is to facilitate cross platform development.
As of openMSX 0.5.2, there is extra functionality to perform file
imports and exports, with support for harddisk images with partitions and normal
disk images. Please see the separate documentation for this in the
doc/Using-diskmanipulator.txt
text file.
To use a real disk, just specify /dev/fd0
as a disk image. This is of
course a Linux (Unix, actually) specific feature, but for now it is usable. It
may be a bit slow though, with the FDC emulation enabled. It should be just as
slow as a real disk drive, however! Don't forget that you shouldn't have it
mounted to be able to use it this way. We recommend to use only write-protected
disks! It is possible that you damage the contents of your disk if you don't.
Windows users can try real disks by using the DirAsDsk feature. Because his
feature is still experimental, one should always use it with write protected
disks. Only regular disks with normal files will work with it; specify A: as
disk image to use it.
openMSX only supports the emulation of the Sunrise IDE interface at the moment.
The extension for this is called 'ide'. The extension has a built in harddisk
configuration, in the form of a 100MB sized disk image. This is the default size: if the harddisk image is
not present, the file is created with this size. The image will end up in your openMSX user directory/persistent/ide/untitled1/hd.dsk
.
As of openMSX 0.6.1, you can specify the harddisk image to be used on the command line:
This means that you're using the ide extension with myhd.dsk as harddisk image. You can also change the harddisk image at run time in the console (only when the MSX is powered off via the power
setting). This works the same as the diska
command:
The 'ide' extension needs the BIOS that can be flashed into the Sunrise IDE interface. It can be downloaded from the Sunrise for MSX web site.
When using this extension for the first time, one has to consider it as using a real Sunrise IDE interface with a 100MB empty harddisk connected to the master slot. How to proceed is written in the text files that come with the FDISK program for IDE, downloadable from the Sunrise for MSX web site. There are also some threads on the MSX Resource Center forum that may give you valuable hints.
For clarity: because the emulation is done on a big disk image, there can be no data corruption of your PC's harddisk. This does mean that you need free
disk space for this image, which can be quite big (default 100MB). So, in other words, you
can't really use your normal PC harddisk as an MSX harddisk for this extension.
(Maybe on UNIX systems it works if you choose a device like
/dev/hdb
as harddisk image file, but we have not tested it and do
note that it can cause loss of data of that partition or disk!)
If you still want to use files from your real PC harddisk on the emulated MSX, you have to use the DirAsDsk feature. See the DirAsDsk section for more details.
Last but not least: as of openMSX 0.6.1, there is (limited) support for CD-ROM with the 'ide' extension. The default configuration has a CD-ROM player on the slave port of the IDE interface. You can insert an ISO image in that virtual CD-ROM player with the -cda
command line option and change it at run time with the cda
console command, all similar to the aforementioned hda
and diska
commands and options.
openMSX supports WAV files for tape emulation! Just use an MSX with a cassette port (at least any MSX1 or MSX2 machine will do) and it should be available.
Then type in the console:
And then in MSX Basic, type:
(or another command to load the program on 'tape'.)
Note that in Linux, one should not use the special file /dev/pcm
for tape input. openMSX will try to read the file until the end, which doesn't exist.
Other cassetteplayer related commands/settings you need to know of are:
cassetteplayer rewind
, to rewind the tapecassetteplayer eject
, to eject the tapecassetteplayer new <filename>
, to create a new WAV cassette image to record to; also sets the cassette player in record modecassetteplayer play
, to set the cassette player in play mode (when you've just recorded to the cassette)cassetteplayer record
, to set the cassette player in record mode, to append to existing cassette images (NOT IMPLEMENTED YET)set cassetteplayer_volume
, to set the volume of the cassette player sound (yeah, the screeching tape sounds!)You can also use the so-called CAS files. Use them exactly as you would use WAV files, described in the previous section.
We don't support using CAS files anymore by patching a BIOS, because it is not really something we want: we prefer a more authentic emulation without hacks like this.
So, nowadays, the CAS files are automatically
converted to WAV files, internally. Note that the loading time is drastically
longer this way (but: doing a set fullspeedwhenloading on
will help a lot). On the other hand, you will be able to hear the cassette
sounds now also with the CAS files... What is using cassettes with an MSX
without those characteristic sounds?
To make it even more comfortable to run software from CAS images, try the following experimental setting, that will attempt to type the loading instruction for you after the MSX has started up:
Note that saving to CAS files is not possible; CAS files will be regarded as read-only tapes.
Using Jack is not the easiest option for running a tape-program, but it is an alternative way in which openMSX supports saving to cassette. We are planning to use it for other purposes as well later. This feature is not available on Windows operating systems.
To be able to connect the openMSX cassetteport to other applications via Jack you will need:
Type the following in the console to make the cassette port available to Jack:
Now you need to start an external program to make actual connections. e.g.
The Jack-pluggable has been successfully tested with
timemachine
as recorder and jack.play
as
player. More convenient setups may become available as Jack is still
being developed.
Note that openMSX can be compiled without Jack-support, use the normal cassetteplayer functions to save to tape in that case.
The next subsections list the default key mapping of openMSX. The mapping of the special MSX keys is hardcoded, but the mapping of the keys for emulator functions is fully customizable using the bind
command in the console. Your customized key bindings are saved together with the settings.
On PCs (running Windows, Linux or BSD), the special MSX keys are mapped as follows:
L-CTRL | MSX CTRL key |
R-CTRL | MSX dead (accents) key |
L-ALT | MSX GRAPH key |
R-ALT | MSX CODE/KANA key |
L-Windows | MSX iee ('no') key |
R-Windows | MSX hai ('yes') key |
F7 | MSX SELECT key |
F8 | MSX STOP key |
Several emulator functions are available under keys as well:
Pause | Pause emulation |
ALT+F4 | Quit openMSX |
CTRL+Pause (Break) | Quit openMSX (not in Windows) |
PrtScr | Save current screen to a file (screen shot) |
F9 | Toggle full throttle (maximum speed) |
F10 | Toggle console display |
F11 | Toggle audio mute |
F12 or ALT+Enter | Toggle full screen mode |
On Apple Macintosh computers, the special MSX keys are mapped as follows:
L-CTRL | MSX CTRL key |
R-CTRL | MSX dead (accents) key |
L-ALT | MSX GRAPH key |
R-ALT | MSX CODE/KANA key |
F7 | MSX SELECT key |
F8 | MSX STOP key |
Several emulator functions are available under keys as well:
Cmd+P | Pause emulation |
Cmd+Q | Quit openMSX |
Cmd+D | Save current screen to a file (screen shot) |
Cmd+T | Toggle full throttle (maximum speed) |
Cmd+L | Toggle console display |
Cmd+U | Toggle audio mute |
Cmd+F | Toggle full screen mode |
Note: if you want to bind your custom keys on the console, use META
as a modifier for the Command (Apple logo) key.
If you have a joystick connected to your PC, use the following command to connect it to the emulated MSX:
To connect a fake joystick (emulated with the arrow keys), you can use this plug
command:
will connect a fake joystick to joystick port A. Button A of the joystick is mapped to the space bar and Button B to M, when using the default configuration. There are two keyjoysticks, 1 and 2. If you like, you can change the bindings in the console and save the settings as usual. Examples: set keyjoystick2.triga LCTRL
or set keyjoystick1.up KP8
.
To connect a mouse, you can also use the plug
command:
will connect a mouse to joystick port A. If you want the joystick emulation feature that some mice (like the Philips SBC-3810 and the Sony MOS-1) have, keep the left mouse key pressed when plugging it in, just as on a real MSX.
If you are using openMSX in windowed mode, it might be tricky to use the mouse. For that you may want to use the following setting: set grabinput on
. This makes sure all input goes to openMSX. Your cursor cannot leave the openMSX window with this setting. Just turn it back to off, if you want to disable this again. If you only want to escape the window briefly, use this command: escape_grab
. It permits you to leave the window, but the next time you enter it, the cursor is grabbed again. It might be a good idea to bind this command to a key, using the bind
command, which is mentioned above.
A renderer is a part of the emulator that generates the graphical part of the emulation: the MSX 'screen'. At the moment, there are three working renderers:
You can set the renderer with the renderer
setting. You can set full screen mode with the fullscreen
setting. Again, to make these settings permanent, use the save_settings
command to save them.
Note that openMSX can be compiled without the SDLGL and SDLGL-PP renderer; if that is true for the build you're using, you will not be able to switch to the SDLGL and SDLGL-PP renderer. In case your graphics card or driver doesn't support OpenGL framebuffer objects (or if you have an outdated GLEW library), switching to SDLGL-PP may abort openMSX.
The accuracy
setting controls how often the renderer is synchronised with the MSX video processor (VDP).
There are three options:
Most MSX screen modes are only 256×212 pixels big. This is quite small for PC screen resolutions of today. That's why you have the possibility to scale up the image. Normally, there are three possible scaling factors: 1, 2 and 3. If you select 1, all MSX pixels are mapped to a 320×240 pixels PC window, for 2 to a 640×480 pixels window and for 3 to a (surprise!) 960×720 window. The setting which determines this is called scale_factor
. In general, the higher the factor, the better the output image is; the downside: it takes a lot more CPU processing power.
Use scale_factor
1 only if you have a slow computer to run openMSX on, because it is very limited in possibilities and in the case of MSX screen modes with more pixels than 256×212, you even lose pixels! In that case, the pixels are interpolated. However, when using it full screen, the low resolution is not a problem, especially because most MSX software uses a 256×212 mode.
There is also a number of scaling algorithms (setting scale_algorithm
) that can be set. The scaling algorithm determines how exactly the mapping is done between the MSX input screen and the PC output screen. Especially for scaling factors bigger than 1, this allows for extra possibilities in the algorithms, like deinterlacing and adding scanlines, blur, anti-aliasing (rounding of blocky patters like stair cases) or even a Trinitron-like TV effect. When the factor is set to 1, you always get the simple
algorithm, see below.
An exception to all of this is the SDLGL-PP renderer. With this renderer (when using a suitable video card and driver), scaling is done on the graphics card hardware and will not take extra CPU power. This renderer gives you also the possibility to use a scale_factor
of 4. The down side is that not all scalers have been implemented for this renderer. See also below.
openMSX contains the following scaling algorithms:
blur
setting. This algorithm also includes scan lines. This scaler is not available in the SDLGL-PP renderer.
A small demonstration of some of the algorithms can be found on the openMSX web site.
PC monitors can have different gamma values than MSX monitors.
To compensate for this, openMSX has a gamma correction feature.
It is controlled by the gamma
setting.
A value of 1.0 disables gamma correction; a lower value makes the image darker; a higher value makes it brighter.
If you want to know what gamma correction really means, read this page about monitor gamma. The gamma correction value you can set in openMSX should be the gamma of your PC screen divided by the gamma of the MSX screen. I measured the gamma of my PC screen (TFT) at 2.0 and the gamma of my MSX monitor at 2.5. That puts the gamma correction at 2.0 / 2.5 = 0.8. So if I enter that value, the openMSX image will have comparable brightness to the MSX image. However, 0.8 is not the value I'm actually using: I prefer a brighter image than my MSX monitor, so I chose to use a gamma correction of 1.1.
openMSX contains a couple of special effects settings that can be applied to the video output:
deinterlace
deinterlace
setting controls this feature:
it can be on (enabled) or off (disabled); it is enabled by default. This feature needs a scaling factor of at least 2.
scanlines
simple
or RGBTriplet
is used and needs a scaling factor of at least 2.
blur
blur
settings control this:
0 means no blur (completely sharp), 50 means some blur (like a monitor),
100 means maximum blur (like a TV).
All other values between 0 and 100 are also possible of course.
This feature is disabled when a scaling algorithm other than simple
or RGBTriplet
is used and needs a scaling factor of at least 2.
glow
)glow
setting controls the amount of after glow:
0 means no after glow, 100 means maximum after glow.
This feature works only in the SDLGL
and SDLGL-PP
renderers.
noise
noise
setting controls the amount:
0 means no noise, 100 means maximum noise. The value is actually the deviation of the color of the original pixel and non-integer values are also possible.
display_deform
)normal
: no deformation (default)horizontal_stretch
: a horizontal stretch to achieve an aspect ratio of the screen that is closer to a real MSX screen3d
: emulates a 3D view on an arcade cabinet's screenSDLGL-PP
renderer.
openMSX has GFX9000 emulation. Note that it still a bit experimental: it is not complete and thus may show relatively many glitches. It is also quite slow and it does not work with the SDLGL renderer yet. Despite of all this, we thought you might wanted to play around with it anyway...
The real GFX9000 has an external video connector to which you can connect a
second monitor. Because of limits of the SDL library we used to create openMSX,
we cannot have more than one window for openMSX, so we cannot emulate a second
monitor. To see the GFX9000 in action, you need to switch the videosource
setting, which equals to a so-called SCART-switch in the real world: set
videosource GFX9000
. If you started openMSX without GFX9000 extension,
this option is not available.
To get your normal MSX screen back, you should
type set videosource MSX
. If you want to toggle with a hot key
between them, it might be useful to bind a key for it. E.g.: bind F6
cycle videosource
.
cycle
is a TCL command that cycles through the options of the setting in the parameter.
There is a master_volume
setting, which controls the overall output volume of openMSX (it applies to all sound devices). Volume 0 means no sound, volume 100 is maximum.
There is also a mute
setting, to disable all sound from openMSX at once. It can be on (muted) or off (sound is audible). By default, mute is bound to the F11 key.
Each sound device in the MSX you are emulating also has its own volume setting. Volume 0 means no sound, volume 100 is maximum. For example: set "MSX Music_volume" 50
.
All mono sound devices have an additional mode setting. You can use it to select whether this device should be audible on the left channel ("left"), the right channel ("right") or both channels ("mono"). Example: set PSG_mode left
. Any sound device can also be individually muted by setting the channel mode to "off".
For Windows users there is the choice to use DirectSound or SDL as an audio
driver. By default, DirectSound is used, because it gives a better quality in
most cases. Change it with the sound_driver
setting, if you like.
openMSX supports the MSX-MIDI interface of the MSXturboR GT.
To use this feature, start openMSX with the machine
Panasonic_FS-A1GT
and plug in a MIDI device on the console.
For example:
This logs all MIDI commands to a file. Because there is no timing information logged, this is not very useful yet.
It's more interesting to connect MSX-MIDI to an actual PC MIDI device,
such as a MIDI out port or the internal synthesizer of your sound card.
On Linux, you can use the midi-out-logger
and set a MIDI
device node, for example /dev/midi
, as its output file. This is
done by default. To play with this setting, use set
midi-out-logfilename
. On Windows, real MIDI devices are separate
pluggables.
A new feature as of openMSX 0.5.2 is the so-called sound logger. It enables you to record the sound you hear on the speakers to a WAV file. Note that recording sound to the uncompressed WAV format will take a lot of disk space. At 44.1kHz it will take about 176 kB per second.
You can simply start the recording of sound by issuing the command
soundlog start
. It will automatically choose a file name and save
it in the soundlogs
directory in your personal openMSX folder. You
can also add an extra parameter to specify the filename for the new WAV file.
The other two sub commands that speak for themselves are soundlog
stop
and soundlog toggle
. The latter is useful if you bind
this command to some hot key.
Note that for now, the exact sound as you can hear it from the speakers will be recorded, including any stutters that may be in it.
This chapter describes how the debug device, built in openMSX, can be used to the advantage of an MSX programmer. This is an artificial MSX device that is connected to an MSX I/O port. It can be used to send debug messages to the host operating system.
Note that openMSX also contains real built in debugging functions, which can be
accessed with the debug
command. More information about it is in
the aforementioned commands.txt
file. With that debugger you can
read and write all registers and memory of almost all devices that are
supported in openMSX. It also supports break points and stepping.
The easiest way to enable the debugdevice is to start openMSX with the
debugdevice extension. To do this, simply add -ext debugdevice
to the
openMSX command line.
Another way to make the device work is to add it to the hardwareconfig.xml
from
the machine that is used. If, for example, the device has to be used on the
Philips NMS 8250, the following lines can be added to the hardwareconfig.xml
file in the share/machines/Philips_NMS_8250
directory.
<DebugDevice id="Debug Device"> <io base="0x2E" num="2" type="O"/> <filename>stdout</filename> </DebugDevice>
The third line is optional and can specify any filename you
like, including stdout
.
Controlling the device is done from within an MSX program. For this purpose, the output ports 0x2E and 0x2F are used. The first port is the Mode Set Register. Bytes sent to this port have the following meaning.
bit(s) | meaning |
---|---|
7 | unused |
6 | line feed mode (0 = line feed at mode change, 1 no line feed) |
4-5 | output mode (0 = OFF, 1 = single byte, 2 = multi byte) |
0-3 | parameters for mode 1 (see below) |
0-1 | parameters for mode 2 (see below) |
When using mode 1, single byte mode, these are the parameters:
bit(s) | meaning |
---|---|
0 | hexadecimal mode on/off |
1 | binary mode on/off |
2 | decimal mode on/off |
3 | ASCII mode on/off |
So, every parameter bit turns an output format on or off and more than one output format can be specified at the same time.
The parameters for mode 2 (multi byte mode) are as follows:
bit(s) | meaning |
---|---|
0-1 | mode (0 = hex, 1 = binary, 2 = decimal, 3 = ASCII mode) |
In mode 1, any write to port 0x2F will result in output. This way, the
programmer can see if a specific address is reached by adding a single OUT
to
the code. The output depends on the parameters set with the mode register. Each
bit represents a specific format, and by turning the bits on and off, the
programmer can decide which formats should be used.
Here is an example:
LD A,65 OUT ($2f),A
This will give the following output:
41h 01000001b 065 'A' emutime: 36407199578
(when all bits are on, mode register = 0x1F)
or
41h 065 'A' emutime: 36407199578
(when the binary bit is off, mode register = 0x1D)
or
41h emutime: 36407199578
(when only the hexbit is on, mode register = 0x11)
and so on.
The EmuTime part is a special number that keeps track of the openMSX emulation. The larger this number is, the later the event took place. This is a great way to get an idea of the timing of things.
If the character to print is a special character, like carriage return, linefeed, beep or tab, the character between the ' ' will be a dot (.) and the normal character is 'displayed' at the very end of the line, so it won't mess up the layout of the whole line.
In mode 2, writing to 0x2F does not output any text. All bytes written to this register are stored in a buffer and only when the mode register is set again the output is shown. Unlike mode 1, the data in this mode is always shown in one mode only. It's either in hex mode, binary mode, decimal mode or ASCII mode, but never a combination. Also the EmuTime bit is left out.
Here is an example:
LD A,xx OUT ($2e),A LD A,$41 OUT ($2f),A OUT ($2f),A OUT ($2f),A LD A,xx OUT ($2e),A
Only at this last instruction the output appears.
If we substitute $20
for xx
, we get:
41h 41h 41h
and if we substitute $22
for xx
, we get:
065 065 065
The extra zero is added to keep alignment. Finally, if we want ASCII
output, all we need to do is change xx
for $23
:
AAA
In this special case, the space in between the data is left out. Any special character like carriage return, linefeed, beep or tab will be printed as you would expect.
The openMSX console can be used to control the output of the device. This is
done by the setting debugoutput
. You can set it to any file name or to the special settings stdout
and stderr
, which lets the output go to these special streams.
Because openMSX is still in heavy development, feedback and bug reports are very welcome!
If you encounter problems, you have several options:
openmsx-user
mailing list.
More info on the
openMSX mailing lists,
including an archive of old messages, can be found at SourceForge.
#openMSX
on irc.freenode.net
and ask your question there.
openmsx-devel
mailing list.
More info on the
openMSX mailing lists,
including an archive of old messages, can be found at SourceForge.
In any case, try to give as much information as possible when you describe your bug or request.
$Id: user.html,v 1.70 2006/07/19 21:17:55 m9710797 Exp $