Model 4 Emulator Documentation

Introduction

This program emulates a popular early microcomputer, the TRS-80 Model 4. It is an extremely fast emulation, written and optimized from the ground up in 80386 assembly language. The unregistered shareware version of the program emulates a 64K Model 4 with four floppy disk drives. The registered version adds support for Model 3 mode, the 128K memory upgrade, a high resolution graphics board, a virtual hard drive, a hardware clock, and RS-232 communications.

Either version of the Model 4 emulator will run on an IBM-compatible computer with an 80386 or better processor, 640K of memory, MS-DOS 3.0 or higher, VGA graphics, and a hard drive. A parallel printer and Sound Blaster-compatible sound card are optional. If you want to read physical TRS-80 disks using the emulator, your computer will need an appropriately-sized disk drive (usually 5 1/4") and a capable floppy disk controller.

Features

M4.EXE emulates a Model 4 with the following hardware:

• Z-80 microprocessor (including all undocumented instructions) with 64K (unregistered shareware version) or 128K (registered version) of RAM
• FD1793 floppy disk controller
• 4 double-sided double-density 80 track drives
• Hard disk drive, with capacity of up to 13 megabytes (registered version only)
• Real time clock interrupt (30 ms in Model 3 mode, 60 ms in Model 4 mode)
• Hardware clock (registered version only)
• 80 by 24 screen with double-wide mode
• 64 by 16 screen with double-wide mode in Model 3 mode (registered version only)
• High resolution graphics board (Micro-Labs or Radio Shack, registered version only)
• Parallel printer port (only with PC parallel printer)
• Amplifier for sound output (through PC speaker or Sound Blaster card)
• RS-232 communications port (registered version only)
• Mouse driver (registered version only)

Obviously, no emulation can ever achieve complete software and hardware compatibility, but this emulator comes very close. It has been able to run all of the operating systems and applications software I have tried, including versions of LS-DOS, MULTIDOS for the Model 4, DOSPLUS for the Model 4, Montezuma Micro CP/M, LeScript, Allwrite, Scripsit Pro, PRO-MRAS, PRO-EnhComp, and many more.

The character sets used in this emulator include all of the characters in the Model 4 (and Model 3) character sets, including the international characters (with the exception of the katakana characters). The emulator also supports a double-wide display in both 80 by 24 and 64 by 16 modes.

Installation

To install the Model 4 emulator, create a directory for it on your hard drive and unzip the file M4V10.ZIP (unregistered shareware version) or M410REG.ZIP (registered version) into it. This directory should also hold any virtual disk files you want to use.

If you have the registered version of the emulator and plan to use Model 3 mode, you should also create a MODEL4.ROM file and place it in this directory. There are two ways to create MODEL4.ROM:

1. If you have a virtual disk image of LS-DOS 6.3.1, use the TRSREAD program (supplied with the registered version of the emulator) to extract the file MODELA/III. Copy it into your Model 4 emulator directory and rename it MODEL4.ROM.
2. If you have a real Model 4, start it up in Model 3 mode using an operating system such as LDOS. Go into BASIC, then type and run the following program:

10 OPEN "O",1,"MODEL4/ROM"
20 FOR X=0 TO &H37FF: PRINT#1,CHR$(PEEK(X));: NEXT X
30 CLOSE 1

Of course, there must be enough room on an available drive to hold this file. You will then need a means to transfer the file to your PC, such as TRSREAD (supplied with the registered version of the emulator) or a null modem transfer.

Operation

To start the Model 4 emulator, just type M4 at the MS-DOS prompt. On its first run, the emulator will calculate your machine speed and create a configuration file (M4.CFG) in the current directory. Subsequently, the emulator will read your machine speed and other options you have selected from that configuration file.

After the emulator displays its startup screen, it will wait for you to press a key. The first time you use the emulator, you will not have any virtual disk files "mounted" in the virtual drives, so it will prompt you to press F8 and do so.

To exit the emulator, press SHIFT F7 and answer the question with a "Y" (for "Yes").

Keyboard

Only a few "hot keys" are needed to control the emulator. If you press any of these hot keys by accident (except for SHIFT F8), press ESC to return to the emulation.

F5	Invokes the delay menu (described later).
F6	Invokes the snapshot menu (described later).
F7	Invokes the debugger (described later).
SHIFT F7	Exits the emulator. You will be asked if you are sure. If you really want to exit the emulator, press "Y"; otherwise, press "N".
F8	Invokes the virtual disk menu (described later).
SHIFT F8	Resets the emulator, much like pressing the orange reset button on a real Model 4.
F9	Invokes option menu #1 (described later).
SHIFT F9	Invokes option menu #2 (described later)

The other keys on the PC keyboard are mapped to their appropriate Model 4 counterparts. This means that most of the keys you press will produce the character that you expect. (The exception is the TRS-80 keyboard layout, described later.) The following keys have special mappings, no matter which keyboard layout you are using:

F10 and ESC:	BREAK
ALT and HOME:	CLEAR
BACKSPACE:	Left arrow
END:	@ (at sign)

One of the biggest differences between the PC keyboard and the Model 4 keyboard is the shifted number values. For instance, SHIFT and 8 on a PC generates an asterisk (*), but on a Model 4 it generates a left parenthesis [(]. One way around this is to use the TRS-80 keyboard layout (described later), but another is to use the numeric keypad. With the NUMLOCK state on, pressing a key on the numeric keypad will generate a number, but if you press SHIFT and a number on the keypad, the result will be the same as if you had pressed SHIFT and a number on the Model 4 keyboard. For instance, pressing SHIFT and 8 on the numeric keypad will generate a left parenthesis [(], just like it would on a real Model 4.

Delay Menu (F5)

The Model 4 emulator automatically adjusts itself to as close to true Model 4 speed as possible. However, there are times when this adjustment is not quite right, or when you want to run your emulated Model 4 faster or slower than normal. This is where the delay menu comes in.

To invoke the delay menu, press F5. You will see a menu with a list of saved delays. To select an existing delay, use the up and down arrow keys to highlight the appropriate name, then press ENTER.

To modify an existing delay, use the up and down arrow keys to highlight the appropriate name, then use the left and right arrow keys to adjust the delay value. Then press ENTER.

To delete the highlighted delay, press D.

To create a new delay, press N. Then type a name for the delay and press ENTER. Now you can change the delay value using the left and right arrow keys.

To exit from the delay menu, press ENTER or ESC.

Snapshot Menu (F6)

Note: Snapshot support is included in the registered version of the emulator only.

A snapshot is a saved image of the emulated Model 4 at a particular point in time. You can be in the middle of an application (or a game), save a snapshot, exit the emulator, and turn off the computer. At some later time, when you re-enter the emulator and load that snapshot, you will be right back where you were, as though you had never left the machine.

(Note: Snapshots can be a very satisfying and helpful feature when you are playing a complicated game that does not have a "save game" option!)

To invoke the snapshot menu, press F6. You will see a directory of snapshot files (they have a .SNP extension). To save a snapshot, press S. You now have three options:

1. Press ESC to exit without saving a snapshot.
2. Type the filename of the snapshot you want to save, then press ENTER. (You do not need to include the .SNP extension.)
3. Press TAB to switch to directory mode, then use the arrow keys to highlight the snapshot filename you want to use. Then press ENTER.

Note that if you save a snapshot under the same filename as a previous snapshot, the previous snapshot will be erased.

To load a snapshot, press L. Again, you now have three options:

1. Press ESC to exit without loading a snapshot.
2. Type the filename of the snapshot you want to load, then press ENTER. (You do not need to include the .SNP extension.)
3. Press TAB to switch to directory mode, then use the arrow keys to highlight the snapshot you want to load. Then press ENTER.

To exit from the snapshot menu, press ENTER or ESC.

Virtual Disk Menu (F8)

To invoke the virtual disk menu, press F8. You will see a menu with a directory display of virtual disk files at the top and a listing of virtual drives at the bottom. To place a virtual disk file in a virtual drive, press the number of the virtual drive (zero to three). You now have three options:

1. Type the filename of the virtual disk file and press ENTER. (You do not need to include the .DSK extension.) If the virtual disk file does not exist, you will be asked if you want to create it. If you do want to create a new virtual disk file, remember that the new file is like a new, unformatted floppy disk. You will have to format it with the operating system of your choice before you can use it with the emulator.
2. Press TAB to select a virtual disk file from the directory display. Use the arrow keys to highlight your selection. To change subdirectories, highlight the appropriate subdirectory name and press ENTER. When you have highlighted the proper virtual disk file, press ENTER.
3. Press ENTER or ESC without typing anything else to leave the virtual drive empty.

To map a virtual drive to an actual PC drive, press the number of the virtual drive. Then type A: or B: (depending on which PC drive you want to use) and press ENTER.

To write protect a virtual drive, hold down the SHIFT key, then press the number of the virtual drive.

To reboot the emulator from within the virtual disk menu, press R. Otherwise, press ENTER or ESC to exit from the virtual disk menu.

Remember to treat virtual disk files with the same care as you would treat real TRS-80 disks. Don't swap virtual disks while the virtual drives are being accessed, and don't remove the system disk from virtual drive zero. Also, be aware that the emulator will not allow the same virtual disk file to be mounted in more than one virtual drive at a time.

IMPORTANT NOTE: LS-DOS requires that you turn on support for drives 2 and 3 before you can use them. Use these commands from the "LS-DOS Ready" prompt:

SYSTEM (DRIVE=2,ENABLE)
SYSTEM (DRIVE=3,ENABLE)

These commands can be SYSGENed, if you wish (use the LS-DOS HELP command for more information).

Option Menu #1 (F9)

To invoke option menu #1, press F9. You will see a list of options (described below). To select an option, press its first letter (except for the Volume option — see below). To exit from option menu #1, press ENTER or ESC.

Sound — This option controls how sound sent to the Model 4 speaker and cassette port is handled. If Sound is set to "disabled", all Model 4 sound is discarded. If Sound is set to "PC Speaker" or "Sound Blaster", all Model 4 sound is played through the appropriate device.

Volume — This option is applicable only if Sound is set to "Sound Blaster" (see above). It controls how loud the Sound Blaster sound will be played. Higher numbers represent louder sound. To increase the volume, press V or the plus sign (+). To decrease the volume, press the minus sign (-).

Printer port — This option controls where Model 4 printer output is sent. If Printer port is set to "none", all printer output is discarded (but the Model 4 applications doing the printing will think the job was successful). If Printer port is set to "LPT1", "LPT2", or "LPT3", all printer output is sent to the appropriate device.

LF after CR — This option is important only if printer output is being sent to an actual device. Most TRS-80 printers were set up to require only a CR (ASCII 13) at the end of a printed line. PC printers require a CR, LF combination (ASCII 13 followed by ASCII 10). If LF after CR is set to "enabled", the emulator will convert TRS-80 style printer output to PC style printer output. If LF after CR is set to "disabled", no conversion is performed.

RS-232 port — This option is supported in the registered version of the emulator only. It controls which PC communications port should be used as the TRS-80 communications port. Available options are "none", "COM1", and "COM2".

The unregistered shareware version of the emulator does not have RS-232 support and sets this option to "none".

Keyboard — This option controls which keyboard layout to use. The available options are "United States", "United Kingdom", "Germany", "Netherlands", "France", and "TRS-80". The first five options map keys on the PC keyboard to appropriate equivalents on the Model 4 keyboard. The "TRS-80" option maps PC keys to their physical position on the TRS-80 keyboard (SHIFT 2 produces a double quote ["], SHIFT 7 produces a single quote ['], etc.). The "TRS-80" option also uses these special keys:

Left backet ([)	Left arrow
Right bracket (])	Right arrow
Reverse single quote (`)	Up arrow
TAB	Down arrow

When an international keyboard is selected, any keys that produce symbols that can't be generated by a real Model 4 keyboard are ignored. In the "German" layout, some other keys, such as the accented vowels, produce the codes that were commonly used for Model 4 word processing. They may look wrong on screen, but will print out correctly with the proper printer setup.

Option Menu #2 (SHIFT F9)

To invoke option menu #2, press SHIFT F9. You will see a list of options (described below). To select an option, press its first letter. To exit from option menu #2, press ENTER or ESC.

Foreground — This option cycles through the foreground colors that the emulator will display. Note that the foreground color can't be the same as the background color.

Background — This option cycles through the background colors that the emulator will display. Again, note that the background color can't be the same as the foreground color.

Character set — This option selects the character set to be used by the emulated Model 4. There are two settings: "early" and "later". The "early" character set was used in in the Model 3 and early Model 4's. The "later" character set was used in later Model 4's and includes the international characters.

HALT state — This option changes the action of the HALT instruction (76H). There are two settings: "normal" and "enter debugger".

Interrupt rate — This option controls the interrupt rate of the emulated Model 4. The available options are "United States (60)" and "International (50)".

Graphics board — This option is supported in the registered version of the emulator only. It specifies which high resolution graphics board will be emulated. The available options are "none", "Micro-Labs", and "Radio Shack".

The unregistered shareware version of the emulator does not have high resolution graphics support and sets this option to "none".

Memory — This option is supported in the registered version of the emulator only. It specifies how much memory is available in the emulated Model 4. The available options are "64K" and "128K".

The unregistered shareware version of the emulator sets this option to "64K".

Debugger (F7)

I wrote the built-in debugger primarily to help debug the Z-80 emulation, but it could also be useful to assembly language programmers. If you are familiar with the commands used by most TRS-80 debuggers, then you should feel right at home. If you enter the debugger accidentally, just press F7 or ESC to exit.

Here are the commands:

D address/register:	Display memory at address or register address
U address/register:	Unassemble (disassemble) instructions at address or register address
+ (plus sign):	Increase memory display by 128 (if not viewing register address)
- (minus sign):	Decrease memory display by 128 (if not viewing register address)
R register,value:	Change register to value
V:	View Model 4 screen
I:	Single-step next instruction
C:	Single-step next instruction or execute next CALL
G address/register,breakpoint:	Leave the debugger, transferring control to the address or register address. If no address or register is specified, control is transferred to the address in register PC. If a breakpoint is specified, the debugger will restart when the breakpoint is reached.
E number:	Execute the next number of instructions
H register/address:	Edit memory in hexadecimal starting at register or address. Press ESC to exit the modification mode.
A register/address:	Edit memory in ASCII starting at register or address. Press ESC to exit the modification mode.

Features Present in the Registered Version Only

This section described features and utilities present in the registered version of the emulator only.

HDFORMAT.EXE

One of the more useful features of this emulator is its virtual hard drive support under LS-DOS (Model 4 mode) and LDOS (Model 3 mode). The virtual hard drive used by the emulator is actually an MS-DOS file (HARDDISK.HDV) containing the hard disk image (like normal virtual disk files, but on a larger scale). Like a real hard drive, the emulator's virtual hard drive must be formatted before it can be used. For this purpose, the emulator package includes HDFORMAT.EXE, an MS-DOS utility that performs the equivalent of both a low and high-level format.

The easiest way to set up a virtual hard drive is to run HDFORMAT with no parameters. From an MS-DOS prompt (before you enter the emulator), type:

HDFORMAT

and press ENTER. HDFORMAT will automatically create a hard disk image file that is capable of storing around 5 megabytes. The image file will start out fairly small, but will grow in size as you add TRS-80 files to it.

Why doesn't HDFORMAT create an image file with the maximum 13 megabytes of capacity? The reason is simple: the larger the hard drive, the greater the wasted space per file. On a 13 megabyte TRS-80 hard drive, every file will take up at least 8K, regardless of its actual size. This can lead to a great deal of wasted space and can cause the hard disk image file to become unnecessarily large. In addition, all TRS-80 operating systems limit the number of files per data disk to 254. This means that people with large hard drives sometimes found themselves with no more file slots, even though they still had plenty of free space on the drive. Of course, there were solutions to these problems, such as the MISOSYS DiskDISK program, which created virtual disk files on the TRS-80 hard drive (much the same way that the emulator creates virtual disk files on the PC hard drive); but if you aren't using any special software to manage your hard drive use, 5 megabytes is a good compromise between capacity and efficiency.

If you want to create a larger hard disk image file, you will need to run HDFORMAT with a command line option:

/?	Displays a brief help screen.
/V	Specifies the volume label to use when formatting the hard disk (the default is "HARDDISK").
/M	Specifies the capacity of the hard disk image file (from 5 to 13, to the nearest megabyte)

As an example, if you want to create a 13 megabyte hard drive with a volume label of "MYDRIVE", you should use this command line:

HDFORMAT /M13 /V:MYDRIVE

IMPORTANT NOTE: HDFORMAT is intended to be used only once, to create and format your hard disk image file. If you use it on a hard disk image that already contains files, all of those files will be erased. After you create the initial hard disk image, it might be a good idea to rename HDFORMAT.EXE, or remove it from your emulator directory altogether, just to make sure that it can't be accidentally invoked.

HARD/CMD

The first utility on UTILITY.DSK, HARD/CMD, is a hard disk driver that works under either LS-DOS (Model 4 mode) or LDOS (Model 3 mode). It provides the linkage between the operating system and the hard drive emulation. As an added bonus, it also sets the operating system time and date.

To install the driver, make sure UTILITY.DSK is mounted in one of the virtual drives. Then type:

HARD

at the "LS-DOS Ready" or "LDOS Ready" prompt and press ENTER. The hard disk driver will install itself and map the virtual hard drive as drive 4. Remember that before you install the hard disk driver, you must have set up the hard disk image file using HDFORMAT (see above for details). Also remember that HARD/CMD works only under LS-DOS and LDOS; it has not been tested to work under any other operating system.

HARD/CMD has two possible command line options. Any options should be enclosed in parentheses, and if you use more than one option, separate them with commas, like this:

HARD (DRIVE=5,QUIET)

Here are the possible options:

DRIVE	Specifies the desired hard drive number (the default is 4)
QUIET	Hides all messages unless an error is encountered (this is useful if you run HARD/CMD as an AUTO command — see below)

Unlike HDFORMAT (described above), HARD/CMD should be run every time you want to use the virtual hard drive with LS-DOS or LDOS. HARD/CMD cannot be SYSGENed, but it can be run as an AUTO command. From the "LS-DOS Ready" or "LDOS Ready" prompt, type:

AUTO HARD (QUIET)

and press ENTER. From now on, whenever you start up LS-DOS or LDOS, the hard disk driver will automatically be installed.

CLOCKSET/CMD

The second utility on UTILITY.DSK is CLOCKSET/CMD, which will set the TRS-80 time and date. This program works with all TRS-80 Model 4 and Model 3 operating systems. Since HARD/CMD (described above) also sets the time and date, CLOCKSET/CMD is primarily useful if you don't want to use a virtual hard drive, or if you use an operating system other than LS-DOS or LDOS.

CLOCKSET/CMD has only one command line option:

QUIET

Hides all messages unless an error occurs (this is useful if you run CLOCKSET/CMD as an AUTO command — see below)

If you use the QUIET option, it should be enclosed in parentheses, like this:

CLOCKSET (QUIET)

CLOCKSET/CMD needs to be run every time you start up your operating system. It cannot be SYSGENed, but it can be run as an AUTO command. Under most operating systems, if you type:

AUTO CLOCKSET (QUIET)

from the "DOS Ready" prompt, CLOCKSET/CMD will run automatically whenever your operating system starts up.

MOUSE/CMD

The third utility on UTILITY.DSK is MOUSE/CMD, a Model 4 mouse driver that converts information from a PC mouse (serial or bus version) to a format that Model 4 mouse-aware programs can understand. Very few Model 4 programs use a mouse, but the ones that do (such as MDRAW, the freeware high resolution drawing program) can be very useful and fun.

MOUSE/CMD has only one command line option:

REMOVE

Disables the mouse driver and removes it from memory (if possible)

If you use the REMOVE option, it should be enclosed in parentheses, like this:

MOUSE (REMOVE)

TRSREAD.EXE

TRSREAD.EXE is an MS-DOS program that will read selected files from a TRS-80 virtual disk file or a real TRS-80 disk and transfer them to MS-DOS files. The TRSREAD command line looks like this:

TRSREAD [options] virtual_disk [files]

The [options] and [files] on the command line are optional. Possible options are:

-s	Include system files
-i	Include invisible files
-e	Extract files from virtual disk
-v	Display directory of virtual disk (default)
-8	Use 80 track disk in 80 track drive

For example, to look at the directory of SAMPLE.DSK, the command line would look like this:

TRSREAD SAMPLE

You don't actually have to use the -v option, because it is the default, and you also don't need to specify the .DSK extension. However, if you would prefer, you could also use this command line to accomplish the same thing:

TRSREAD -v SAMPLE.DSK

To extract all files from SAMPLE.DSK that begin with the letter S, including invisible and system files. the command line would look like this (notice the use of MS-DOS style wildcards):

TRSREAD -e-i-s SAMPLE S*.*

To extract the visible, non-system files LETTER1/TXT, LETTER2/TXT, and ADDRESS/TXT from SAMPLE.DSK, the command line would look like this:

TRSREAD -e SAMPLE LETTER1/TXT LETTER2/TXT ADDRESS/TXT

To extract all visible, non-system files from the TRS-80 disk in PC drive A:, the command line would look like this:

TRSREAD -e A: *.*

Note that when files are extracted from virtual disk files or TRS-80 disks, the resulting files are always copied into the current MS-DOS directory.

TRSWRITE.EXE

TRSWRITE.EXE is an MS-DOS program that will copy MS-DOS files into TRS-80 virtual disk files or onto real TRS-80 disks. The TRSWRITE command line looks like this:

TRSWRITE [option] virtual_disk file_or_wildcard

There is only one possible option:

-8	Use 80 track disk in 80 track drive

For example, to copy the MS-DOS file LETTER1.TXT into the virtual disk file SAMPLE.DSK, the command line would look like this:

TRSWRITE SAMPLE LETTER1.TXT

To copy all files starting with B and with a .DOC extension onto the TRS-80 disk in drive A:, the command line would look like this:

TRSWRITE A: B*.DOC

To copy the files LETTER1.TXT, LETTER2.TXT, and ADDRESS.TXT into SAMPLE.DSK would require three command lines:

TRSWRITE SAMPLE LETTER1.TXT
TRSWRITE SAMPLE LETTER2.TXT
TRSWRITE SAMPLE ADDRESS.TXT

Note that the files to be copied must exist in the current MS-DOS directory.

Registration

The unregistered shareware version of the Model 4 emulator is a very powerful and capable program, but its features are limited compared to the registered version. Specifically, these features are available in the registered version of the emulator only:

• Model 3 mode
• 128K support
• High resolution graphics (Micro-Labs or Radio Shack)
• RS-232 communications
• Virtual hard drive support
• Hardware clock support
• Mouse driver
• Standalone file transfer utilities (TRSREAD and TRSWRITE)

Registration costs only $49 (for e-mail delivery), and you can register using the secure registration form. Fill out the appropriate parts of the form, including your credit card number and expiration date, and press the "Submit Registration Information" button. You will receive the latest version of my Model 4 emulator (with all the added features) and all the extra utilities mentioned above.