WinTRS80 - TRS-80 Model I/III/4 emulator for Windows 95/NT  
Systems

Syntax
WinTRS80 [/model]

Description
WinTRS80 is built on top of a Z-80 emulator, with added routines to 
support keyboard and video I/O through a Windows interface.  The hardware 
emulation can operate as a TRS-80 Model I, Model III, or Model 4.

WinTRS80 supports 48K of RAM in Model I or Model III mode, 128K in Model 4 
mode. Floppy disks and hard disks are emulated using files to store the 
data.  A printer is emulated by sending its output to PRN.  If this is 
spooled, a Print Output menu item is provided.  There is also a fairly 
complete emulation of cassette I/O that uses files for cassette tapes 
(Model I/III mode only).

Fonts
WinTRS80 exactly duplicates all fonts of the original Model I/III/4 
including the special characters and Kana set.  To do so, I have created 5 
True-type fonts.  These are the standard and kana sets in both regular and 
wide modes as well as a supplemental set to handle some differences and to 
cover the fact that Windows will not display certain characters in a font 
set.  These 5 fonts must be installed for WinTRS80 to work properly.

Keys
The following keys have special meanings to WinTRS80:

LeftArrow or Backspace is the TRS-80 left arrow key.  RightArrow or Tab is 
the right arrow key.  UpArrow is the up arrow key.  DownArrow is the down 
arrow key.  Esc is the Break key.  Home is the Clear key.  Control is the 
Model 4 Ctrl key (address bit 7, data bit 2).  Pause sends a Shift-@ to 
pause execution.

F1, F2, and F3 are the Model 4 function keys (address bit 7, data bits 4, 
5, and 6).  F1 is also the Model I Electric Pencil control key that some 
users added to their machines.  CAPS is the Model 4 Caps Lock key (address 
bit 7, data bit 3).  This is a toggle so ignore the light!  F5 is 
equivalent to the @ key (so that @ can be used as a modifier key).  F4 is 
equivalent to the 0 key (so that a shifted 0 can be obtained).

Due to a problem in VC++ the shift keys are the same (not distinct as they 
should be for the Model III/4.  For this reason, F7 and F8 are the left 
and right shift keys for programs that need them.  The keys [, \, ], ^, _, 
{, |, }, and ~ activate unused positions in the keyboard matrix (address 
bit 3, data bits 3-7).  These keys map to the corresponding ASCII 
characters under some TRS-80 keyboard drivers; under others, they do 
nothing.  F9 is equivalent to underscore (address bit 3, data bit 7), so 
that a shifted underscore can be obtained; this maps to ASCII code 0x7f 
under some TRS-80 keyboard drivers.

Emulated cassette
To control the emulated cassette, a file called "cassette.ctl" in the 
current directory keeps track of what file is currently "loaded" as the 
cassette tape and the current position within that file.  The operation 
works very much like an actual tape recorder.  The cassette emulation 
works only in Model I or III mode.  Make SURE the file has been rewound 
for a read and the name is correct as there is no way to break out of a 
read loop!

Printer
For printer support, any text sent to the TRS-80's printer (using LPRINT 
or LLIST, for example) is sent to PRN.  A print screen is also available 
on the file menu.

Emulated floppy disks
In Model I mode, WinTRS80 emulates a Radio Shack Expansion Interface with 
the Percom Doubler or Radio Shack Doubler installed.  The Doubler provided 
double-density disk access by allowing either the stock WD1771 FDC chip or 
a WD1791 chip to be selected under program control.  At powerup the 1771 
is selected, so operating systems with no Doubler driver see a stock 
system. The emulator pretends to be both a Percom and Radio Shack Doubler 
at the same time -- it responds to the special commands of both -- so a 
driver for either should work.  Under LDOS, use the command "FDUBL" (newer 
versions of LDOS), or "PDUBL" or "RDUBL" (older versions) to install the 
driver.

In Model III or 4 mode, WinTRS80 emulates the stock Model III/4 floppy 
controller, which used a WD1793 chip (software-compatible with the WD1791) 
to provide both single and double density.

Four floppy drives are emulated.  If all file names are blank or the 
drives disabled flag is set, a drive with no disk is emulated (but see 
below). If the user does not have write permission for a floppy file, a 
write-protect tab is emulated.  To change floppies in an emulated drive, 
select a new file.  To change an already set file back to blank, simply 
enter a file name that does not exist.

If you try to boot with no drive 0 name  (that is, no disk in drive 0), 
WinTRS80 emulates having no disk controller.  The behavior of a real 
machine with a disk controller in this case didn't seem useful to emulate 
faithfully: A real Model I hangs with a screen full of garbage; a real 
Model III or 4 goes into a retry loop printing "Diskette?" on the screen 
and rechecking whether you've inserted one.

Due to a limitation of the original Model I hardware, drive :3 cannot be 
double-sided in Model I mode.  In the original Model I, you could not have 
a drive :3 at all if any drive in the system was double-sided, but the 
emulator is able to be more forgiving.

Emulated floppy image files can be any of three types: JV1, compatible 
with Jeff Vavasour's popular freeware Model I emulator for the PC;  JV3, 
a compatible extension of a format first used in Vavasour's commercial 
Model III/4 emulator, or DMK, the newest format that allows even copy
protected disks to be emulated.  All types work in WinTRS80 regardless of what
model it is emulating.  A heuristic is used to decide which type of image 
is in a drive, as none has a "magic number" or signature.

JV1 supports only single density, single sided, with directory on track 
17. Sectors must be 256 bytes long.  Use FORMAT (DIR=17) to format JV1 
disks with more (or less) than 35 tracks under LDOS.

JV3 is much more flexible, though it still does not support everything the 
real controllers could do.  It is best to use JV3 for all the disk images 
you create, unless you need to exchange images with someone who is using 
the Vavasour Model I emulator.  A JV3 disk can be formatted with 256 byte 
sectors, 1 or 2 sides, single or double density, with either FB (normal) 
or F8 (deleted) data address mark on any sector.  You cannot format a 
sector with an incorrect track number or head number, or with length other 
than 256 bytes.  You can format a sector with an intentional CRC error in 
the data field.  The original JV3 format had a limit of 2901 total 
sectors, but WinTRS80 allows up to 5802.  If you format more than 2901 
sectors on a disk image, however, other emulators may be unable to read 
the additional sectors.  An 80 track, double-sided, double-density (18 
sector) 5-inch floppy will fit within the original 2901 sector limit; the 
extension to 5802 is primarily for future emulation of 8-inch drives.

DMK supports most everything that the original hardware could handle.
Even protected disk formats should work. (Mostly...)

The program mkdisk makes a blank emulated floppy or "bulk erases" an
existing one.  By default, mkdisk makes a JV3 floppy, but with the -1 flag 
it makes a JV1 floppy.  With the -k option, it makes a DMK disk.
See the mkdisk man for more information.

Early Model I operating systems used an FA data address mark for the 
directory (a nonstandard value supported only by the WD1771, but not the 
WD1791/3), while later ones wrote F8 (for Model III/4 compatibility) but 
could read either.  To deal nicely with this problem, WinTRS80 implements 
the following kludge.  On writing, any data address mark other than FB is 
recorded as F8.  On reading in single density with the emulated WD1771 
(available in Model I mode only), F8 is returned as FA.  In all other 
modes, F8 is returned as F8.  This trick makes the different operating 
systems perfectly compatible with each other, which is better than on a 
real Model I!


Emulated hard disks
WinTRS80 can emulate a hard disk in a file with the aid of a special LDOS 
driver called XTRSHARD/DCT.  This driver has been tested and works under 
both LDOS 5.3.1 for Model I or III and TRSDOS/LS-DOS 6.3.1 for Model 4.  
It may or may not work under earlier LDOS versions.  It definitely will 
not work under other TRS-80 operating systems or with emulators other than 
WinTRS80.  The hard disk format was designed by Matthew Reed for his Model 
I/III and Model 4 emulators; WinTRS80 duplicates the format so that users 
can exchange hard drive images across the emulators.

To use the hard disk emulation, first run the mkdisk program to create a 
blank hard drive (.hdv) file.  Typical usage would be: mkdisk -h 
mydisk.hdv.  See the mkdisk man for other options.

Second, WinTRS80 supports up to eight hard drives, with names selected 
from the Hard Drive menu.

Third, make sure an appropriate version of LDOS is in emulated floppy 
drive 0, and the supplied file utility.dsk is in another emulated floppy 
drive. Boot LDOS.  If you are using Model I LDOS 5.3.1, patch a bug in the 
FORMAT command by typing PATCH FORMAT/CMD.UTILITY M1FORMAT/FIX.  You need 
to apply this patch only once.  It must not be applied to Model III or 
Model 4 LDOS.

Fourth, type the following commands.  Here d is the LDOS drive number you 
want to use for the hard drive (a typical choice would be 4) and u is the 
unit number you chose when naming the file (most likely 0).

SYSTEM (DRIVE=d,DRIVER="XTRSHARD",ENABLE)
Enter unit number ([0]-7): u
FORMAT d (DIR=1)

Answer the questions asked by FORMAT as you prefer.  If you are curious 
about the DIR=1 parameter to FORMAT, see mkdisk.  You can repeat these 
steps with different values of d and u to have more than one hard drive.

Finally, it's a good idea to give the SYSTEM (SYSGEN) command (Model 
I/III) or SYSGEN command (Model 4).  This command saves the SYSTEM 
settings, so the drive will be available again the next time you reboot or 
restart the emulator.  If you need to access the hard disk file after 
booting from a floppy that hasn't been SYSGENed, simply use the same 
SYSTEM command(s) again, but don't FORMAT.  You can freely use a different 
drive number or a different unit number.

Technical note:
XTRSHARD/DCT is a small Z-80 program that implements all the 
required functions of an LDOS disk driver.  Instead of talking to a 
real (or emulated) hard disk controller, however, it uses special 
support in WinTRS80 that allows Z-80 programs to open, close, read, 
and write files directly.  This support is described further in the 
next section.  Because WinTRS80 does not emulate real hard drive 
controller hardware, hard disk drivers other than XTRSHARD/DCT will 
not work with it.


Beginning in version 2.0, Wintrs80 also emulates the Radio Shack hard disk
controller (based on the Western Digital WD1010) and will work with the native
drivers for this hardware.  This emulation uses the same hard drive (.hdv)
file format that XTRSHARD/DCT does. 

To get started, run the mkdisk program to create a blank harddrive (.hdv)
file.  Typical usage would be: mkdisk -h mydisk.hdv.  See the mkdisk man
file for other options.

Second, link the file to an appropriate name.  The WD1010 emulation sup-
ports up to four hard drives.

Note that if hard drive unit 0 is present on a Model 4P,
the Radio Shack boot ROM will always try to boot from it, even if the
operating system does not support booting from a hard drive.  If you have
this problem, either hold down F2 while booting to force the ROM to boot
from floppy, or simply avoid using unit number 0.  Stock TRSDOS/LS-DOS 6
systems do not support booting from a hard drive; M.A.D. Software's HBUILD6
add-on to LS-DOS for hard drive booting should work, but is untested.  Mon-
tezuma CP/M 2.2 does boot from the emulated hard drive.

Finally, obtain the correct driver for the operating system you will be
using, read its documentation, configure the driver, and format the drive.
Detailed instructions are beyond the scope of this manual page.



Data import and export
The emulated floppy utility.dsk contains some programs for transferring 
data between the emulator and ordinary files.  All the programs run on the 
emulator under Model I/III LDOS and Model 4 TRSDOS/LS-DOS 6; some also 
work under other TRS-80 operating systems.

IMPORT/CMD imports a file and writes it to an emulated disk.
Usage:
IMPORT [-n] dosfile trsfile.  The -n flag converts Dos newlines (\n) 
to TRS-80 newlines (\r).  IMPORT/CMD may not work correctly under 
operating systems other than Model I/III LDOS and Model 4 TRSDOS/LS-
DOS 6.  IMPORT/BAS is a much slower program that performs the same 
function but should work under more operating systems.  Simply run 
it under Disk Basic and answer the prompts.

EXPORT/CMD reads a file from an emulated disk and exports it to a Dos 
file.
Usage:
EXPORT [-n] trsfile dosfile.  The -n flag converts TRS-80 newlines 
(\r) to Dos newlines (\n).  EXPORT/CMD may not work correctly under 
operating systems other than Model I/III LDOS and Model 4 TRSDOS/LS-
DOS 6. EXPORT/BAS is a much slower program that performs the same 
function but should work under more operating systems.  Simply run 
it under Disk Basic and answer the prompts.

SETTIME/CMD reads the date and time from Windows and sets the TRS-80 DOS's 
date and time accordingly.  It has been tested only under LDOS but 
probably runs on other Model I/III operating systems.  SETTIME6/CMD is the 
same program compiled for Model 4 TRSDOS/LS-DOS 6.


Interrupts
The emulator supports only interrupt mode 1.  It will complain if your 
program enables interrupts after powerup without executing an IM 1 
instruction first.  All Model I/III/4 software does this, as the built-in 
peripherals in these machines supported only IM 1.

The Model I has a 40 Hz "heartbeat" clock interrupt, while the Model III 
used 30 Hz, and the Model 4 could run at either 30 Hz or 60 Hz.  The 
emulator approximates this rather well even on a system where clock ticks 
come at some frequency that isn't divisible by the emulated frequency 
as long as the true frequency is not slower than the emulated frequency.

Options
/model
Specifies which TRS-80 model to emulate.  Values accepted are 1 
(Model I), 3 (Model III), and 4 (Model 4).  If none is given, 
WinTRS80 starts in the same mode it was in when last exited.

Registry Entries
WinTRS80 maintains it's settings in the system registry.  It uses the
Key HKEY_LOCAL_MACHINE\SOFTWARE\WinTRS80 with separate entries for each 
model.  Only the entry for the Sound Blaster I/O port must be edited here.  
All other entries are handled through the system menus.

Color
The color dialog box is selected from the options menu.  This allows 
values to be entered for both the foreground and background.  Values are 
from 0 to 255.

Sound
Sound is emulated in two different ways. 

Regular sound is now handled by DirectSound.  You will have to have this
installed for this type of sound to work properly.  To enable, check the
DirectX flag in the Options menu.

If DirectX is not enabled, standard sound is handled by direct writes to
a sound blaster compatible card.  This will cause problems with the windows
sound system but is the only way to get the sound to work correctly.  Even
after WinTRS80 exits, the sound card may still not work right until a reboot.

For emulation of the VS-100 voice synthesizer, DirectX is used.  You will
have to install DirectX for this to work.  Due to the limitation above, 
both sound emulations cannot be active at the same time.

Joysticks
Emulation is now provided for the Alpha Products Alpha Stick 3 joystick.  
This product worked by returning a code for each of the directions and the 
button from any port below 128.  Note that a 0UT 236,16 must have been 
called first to activate the external bus.  The values returned are shown 
here.

Control	Bit	Value

Center		255
Up		0	254
Down		1	253
Left		2	251
Right		3	247
Button	4	239

Combinations with the button just combine the values.
Please note that joystick emulation and VS-100 emulation cannot both be 
active as they duplicate ports.

Just to make games and such a little more enjoyable, I have added the 
option to use the joystick to send keys to the keyboard interface.  If 
this option is selected in the joystick menu, the regular joystick 
interface is disabled and joystick directions are fed to the keyboard as 
keystrokes.  You have 2 options for the button, it can either send a space 
or a return as these are the most common fire controls.

Mouse
A few Model 4 programs could use a mouse, such as the shareware hi-res
drawing program MDRAW-II. The program XTRSMOUS/CMD on the utility disk
(utility.dsk) is a mouse driver for Model 4/4P mode that should work with
most such programs.  Wintrs80 does not emulate the actual mouse hardware (a
serial mouse plugged into the Model 4 RS-232 port), so the original mouse
drivers will not work under Wintrs80.  Instead, XTRSMOUS accesses the X mouse
pointer using an emulator trap.  XTRSMOUS implements the same TRSDOS/LS-DOS
6 SVC interface as the David Goben and Matthew Reed mouse drivers. (It does
not implement the interface of the older Scott McBurney mouse driver, which
may be required by some programs.)

By default XTRSMOUS installs itself in high memory. This is done because
MDRAW-II tests for the presence of a mouse by looking to see whether the
mouse SVC is vectored to high memory. If the driver is installed in low
memory, MDRAW thinks it is not there at all. If you use mouse-aware pro-
grams that don't have this bug, or if you edit the first line of MDRAW to
remove the test, you can install XTRSMOUS in low memory using the syntax
"XTRSMOUS (LOW)".

The mouse data is also available in Model 3 and 4 modes via ports.  I use
the same ports as David does in his emulator for compatiblity.  They are:

Port    Read            Write
0x58    Button Status
0x59    X Position      Set X Position
0x5A    Y Position      Set Y Position

These values are scaled to 0-255, depending on where the mouse is in the
window.

To allow you to have a mouse pointer on the screen and not have the windows
mouse pointer over it (like MDraw) you can turn off the windows mouse by
unchecking the Mouse selection in the Options menu.

Speed
Due to all the background processing that goes on and the necessary
interface with windows, WinTRS80 can be pretty slow.  To help compensate
for this, I have added a speed control.  In the CPU section, a positive
number represents the number of z80 instructions that are processed before
control returns to windows.  Setting this number very high will make system
response, like keyboard, mouse and sound, poor.  It is probably not good to go over
about 10 or so.  If the system is to fast, a negative number will slow the
system down by introducing a pause between each command.

Windows graphics is very slow in emulation.  To offset this the system only
updates the graphics screen when a change occurs and then only every so
often.  The higher number you put in this box, the longer the delay between
updates and the faster the emulator runs.

Utilities
I have included two other little utilities with WinTRS80.  TRSDIR simply 
displays the directory of a JV3 format TRSDOS disk file.  It prints out in 
exactly the same format as a TRSDOS DIR command.  This will not work on 
other Dos formats.  GetTRS dumps all files from a TRSDOS JV3 file to the 
current directory.  This is a quick way to export data!  Other packages 
are available to manipulate disk images that work better than these, but I 
had them handy....

VS-100 Voice Synthesizer
Make WinTRS80 TALK!!  I have now provided elementary emulation for the 
Alpha products VS-100 voice synthesizer.  To use it you must have DirectX 
installed on your system.  The emulation is not perfect as the sounds must 
be produced individually which limits the "smoothness" of the sound, but 
it seems to work well enough.  In order to use it, get the voice.zip file 
which has the software needed to run it and the documentation files.

Other Resources:
There are many other TRS-80 resources available on the Web, including 
shareware and freeware emulators that run under MSDOS and other operating 
systems, software for converting TRS-80 physical media to the emulator's 
disk file format, ROM images, and TRS-80 software that has already been 
converted.  For pointers, see

http://www.research.digital.com/SRC/personal/Tim_Mann/trs80.html.

Bugs and limitations
There may be bugs in the Z-80 emulator which we haven't found yet.  Some 
of the more bizarre undocumented Z-80 instructions are not implemented.

Cassette emulation does not work in Model 4 mode.  Even in Model I/III 
mode, it works only for programs that use the Level II ROM routines to 
access the cassette; the emulator looks for access to the cassette port 
from specific PC values to activate the feature.

Serial ports are not emulated.

Some features of the disk controller are not currently emulated.  (1) 
Force Interrupt with condition bits 0x01, 0x02, or 0x04 is not 
implemented.  (2) Read Track is not implemented.  (3) The multiple-sector 
flags in Read and Write are not implemented.

The emulator arbitrarily limits both JV1 and JV3 disk images to 96 tracks. 
The limit could easily be increased to 255 or maybe 256, but that would 
probably not be useful with existing TRS-80 operating systems, which don't 
expect floppies to have so many tracks.  For example, LDOS 5.3.1 allows at 
most 95 tracks on a floppy, though it allows more on hard drives.  256 
tracks is an absolute maximum for the TRS-80 floppy disk controller and 
for the JV3 format.

The extended JV3 limit of 5802 sectors is somewhat arbitrary as well.  It 
could be raised by generalizing the code to permit more than two blocks of 
2901.  Again, this does not seem too useful.  5802 sectors is already 
enough for a 3" HD (1.44MB) floppy, which the TRS-80 didn't support 
anyway.

The emulator guesses a romfile is in .hex format if its first byte is a 
colon (':'), so a raw binary ROM image can't start with that byte value. 
In the future it would be nice to accept MODELA/III files too.

The import/cmd and export/cmd programs do not work on NEWDOS/80.

If you discover other bugs, or write fixes for any of these, please let me 
know.  I expect to incorporate fixes into future releases.

Authors and acknowledgements
WinTRS80 was written by Wade Fincher <wade@sisko.asub.arknet.edu> at 
Arkansas State University - Beebe.  This was primarily a learning exercise 
in Visual C++ 5.0 and a trip down memory lane.  It is based on other 
emulators available with many enhancements.

xtrs was written by David Gingold <gingold@think.com> of Thinking Machines 
Corporation, Alec Wolman <wolman@crl.dec.com> of Digital Equipment 
Corporation, and Timothy Mann <mann@pa.dec.com> of Digital Equipment 
Corporation.

