This document describes how the debugdevice, built in openMSX, can be used to
the advantage of an MSX programmer. 

1) Enable the device

a) easy method: use extension

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-commandline.

b) less easy method: modify machine configuration

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.

<device id="DebugDevice"> <type>DebugDevice</type> 
  <parameter> filename="~/debugout.txt"></parameter>
</device>

The third line, <parameter> ..., is optional and can contain any filename you
like.

2) The output ports

Controlling the device is done from within an MSX program. For this purpose, the
output ports 0x2E and 0x2F are used. Below the meaning of these ports are
described:

Port 0x2E: Mode set register 
bit 6-7 unused 
bit 4-5 output mode (0 = OFF, 1 = single byte, 2 = multi byte) 
bit 0-3 parameters for mode 1 (see below) 
bit 0-1 parameters for mode 2 (see below)

Parameters for mode 1 (singe byte mode):
bit 0 hexadecimal mode on/off 
bit 1 binary mode on/off
bit 2 decimal mode on/off
bit 3 ascii mode on/off

Parameters for mode 2 (multibyte mode):
bit 0-1 mode (0 = hex, 1 = binary, 2 = decimal, 3 = ascii mode)

3) Description of mode 1

In mode 1, any write to port 0x2E 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.

example:

LD  A,65
OUT ($2f),A

will lead to 

41h 01000001b 065 'A' EmuTime:087a09c75a  (when all bits are on, modereg = 0x1f)

41h 065 'A' EmuTime: 087a09c75a (when de binary bit is off, modereg = 0x1d)

41h EmuTime: 087a09c75a (when only the hexbit is on, modereg = 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 find out in what order things are called. 

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 and of the line, so it won't mess up
the layout of the whole line.

4) Description of mode 2

In mode 2, writing to 0x2E 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 hexmode, binary mode, decimal mode or ascii mode, but
never a combination. Also the EmuTime bit is left out.

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	<--- at this point the output appears

if we substitude $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 this equally aligned.  Finally, if we want ascii
output, all we need to do is change xx for $23:

AAA

In this special case, the space inbetween de data is left out. Any special
character like carriage return, linefeed, beep or tab will be printed as can be
espected.

5) Controlling the output

The openMSX console can be used to control the output of the device. This is
done by a normal setting type. Refer to commands.txt how to use the settings.
This setting can contain the following:

stdout 			  output goes to standard output 
stderr  		  output goes to standard error
any other filename	  output goes to the file with that filename
























