		TRSF-80 - TRS-80 Model I Emulator Version 0.1
		=============================================
			      December 4, 1996


The TRSF-80 program is designed to emulate a TRS-80 Model I computer on a
DOS-based Intel x86 platform.  Though it is a DOS application, it should 
operate correctly under most varieties of Windows.

Contained in this distribution, you should have the following files:

README.TXT   - This file
TRSF80.EXE   - The main emulator executable
FILE_ID.DIZ  - A quick description of the release.

The current release of 0.1 is a beta test release.  All of the features 
contained in it are fully functional.  The main reason it is a beta test
release is that it still needs user feedback.  Please feel free to make 
comments about features you would like to have added.  Also, if there are 
any features that you either don't like or find hard to use, please make 
suggestions on those as well.

TRSF-80 is freeware.  You may use it free of charge and distribute it 
to your friends.  You may not sell this emulator for a profit, though it 
can be included in a distribution with other freeware/shareware.

Though this emulator is freeware, I will be more than happy to accept any
donations.  Just drop me a line at rfries@tcmail.frco.com and I'll send 
you my current mailing address.

Don't worry about trying to reverse engineer TRSF-80.  Once I get the 
source code cleaned up, I will be releasing it.  Right now, it's still a
hack. :) 

This emulator was written by Ron Fries.  Should you have questions or
comments, I can be reached at rfries@tcmail.frco.com.  If you are pleased
with this software and find it useful, let me know.  A few words of 
encouragement will keep me motivated to work on future freeware.

--------------------------------------------------------------------------

BACKGROUND:
===========

I was only 12 years old when I got my first computer, a TRS-80 Model I
Level II with only 16k (yes, 'k') of RAM and a tape recorder to store files!
Probably most amusing is that simple computer cost about $850.  Of course, 
I later upgraded it to add an Expansion Interface to give me 48k of total 
RAM, one disk drive, printer support and eventually modem support.

Recently I got involved in emulating different systems on today's more
powerful computers.  I was first exposed to emulating the TRS-80 through
the efforts of Jeff Vavasour.  Though his emulator works quite well, I was
interested in one that supports sound.  Only the registered version of Jeff's
does, and he is currently asking a $25 registration fee.  Though I would say
its probably worth the $25 fee, I decided to take the challenge of developing
my own instead.  I actually found it to be easier than I expected.

Because Jeff's has been the standard for several years (his is the only DOS
version I'm aware of), I tried to keep several of the features similar.  I 
guess you could say I used his as a model.  You will probably notice many
similarities, though each will have a different look.

Of the features in Jeff's emulator, I have adopted the following:

Hardware emulation:
-------------------
   o  48K CPU with Z-80 microprocessor
   o  Expansion Interface (currently only floppy drive emulation)
   o  4 80-track single-sided disk drives
   o  Lowercase and numeric keypad upgrade
   o  Audio support of TRS-80 cassette audio output through Sound Blaster

User options:
-------------
   o  A Disk Menu which allows disks to be mounted on-line
   o  A variety of screen colors
   o  A configurable volume for sound output
   o  A choice of keyboard layouts
   o  An integrated debugger
   o  An adjustable processor speed


Features currently not supported (may be added later):
------------------------------------------------------
   o  Emulation of RS-232 COM Port
   o  Emulation of Printer
   o  Emulation of Expansion Interface 40Hz clock interrupt
   o  User-Configurable keyboard layout
   o  Snapshot control
   o  Write-protected disks
   o  Creation of new unformatted disks


Features intentionally left out (no plans to support):
------------------------------------------------------
   o  TRS-80 Cassette Emulation (ability to save/load cassette files)
   o  Ability to shell to DOS

There are two main limitations with this release.  The first is the screen
size.  I've used the exact character set used in the original TRS-80 to try
to keep it as authentic as possible.  The only problem is, the original
TRS-80 character set requires a screen resolution of 384x192.  There isn't
a good EGA/VGA option that supports this resolution well, so I've had to 
choose something higher (640x400).  The result is a fairly small screen 
window that is slightly distorted.  I may work to change this in the future.
 
The other limitation of this emulator is speed.  The main 'processor' in 
an emulator usually performs most of the work; thus, the overall performance 
of the emulator is based primarily on the performance of the processor 
emulation.  In order to keep my work simple, I choose to use a Z-80 emulator
that was already complete.  For TRSF-80, I choose to use a Z-80 emulator
written by Marat Fayzullin.  

When Marat wrote his emulator, his main focus was portability, not
performance.  To his credit I must say he has done an excellent job in 
keeping the Z-80 emulator portable, the only problem is it is impossible to
provide optimum performance on all platforms.  If I am able to find the time,
I will convert the Z-80 emulator to assembly language.  

I would like to give a special thanks to Marat for his work.  Without it, it
would have taken much longer to get this working.  With his code, it only
took me 1-2 weeks to get the main TRS-80 emulator working!

One more note about the speed: on my 486-66, the system conveniently happens
to run at just above full speed.  At this point, I don't have much need to
change it!  It'll probably run at almost exactly full speed on a 486-33.

Where did the name TRSF-80 come from?  The TRS-80 part should be obvious,
but what about the 'F'?  Simple: my initials are RSF.  Sorry - I couldn't
think of a better name.


--------------------------------------------------------------------------

INSTALLATION:
=============

Installation of TRSF-80 is simple.  Choose a directory where you would
like to locate the emulator and copy the TRSF80.EXE file to that directory.
You will also need a copy of the Model I Level II ROM.  Since the ROM is
still copyrighted material by Tandy/Radio Shack, I have not included it
in my release.  As of this release, the ROM was still available at the
following ftp address:

ftp://ftp.kjsl.com/tandy/m1-3-4/rom_dos.zip

Simply copy the file "ROMIMAGE." to the directory where the TRSF80.EXE 
executable resides.  

DISCLAIMER:  The Level II ROM image is copyrighted material.  It is not to
be distributed with, nor should it be construed as a part of this package.

To invoke the emulator, set your current working directory to the TRSF80
directory and type TRSF80 from the command line prompt.  If it was able 
to successfully load the ROM image, you should see a title screen.  By
pressing any key, you should see the traditional TRS-80 'MEM SIZE?' or
'MEMORY SIZE?' message.  Pressing <ENTER> will take you to Level II Basic.


--------------------------------------------------------------------------

COMMAND LINE OPTIONS:
=====================

When invoking the TRSF80 emulator, there are several command line options
which can be used.  Each option is preceded with a '-' sign.  You can
also specify up to four filenames which will be 'installed' as disks in
the virtual TRS-80.  Unless an filename extension is specified, all disk
filenames will default to the '.DSK' extension.  The first disk listed
will be installed in drive 0, the second in drive 1, etc.

The current command line options include:

-aXXX  define SB base address in hex (for example 220, 240, etc.)
       (NOTE: the emulator will normally use the BLASTER environment 
	      variable for the base address.  This command should only be 
	      necessary if the BLASTER variable is not defined or a 
	      different base address is desired)

-d     disable sound support


 
--------------------------------------------------------------------------

FUNCTION KEYS:
==============

Once the emulator is running, there are several options available through
the function keys:

F1        -  Displays Help

Shift-F1  -  Performs a Reset of the TRSF-80, similar to pressing the
	     reset switch on the back left corner of the TRS-80 keyboard.

F2        -  Display disk menu - this menu allows the user to change the
	     disks currently mounted in the 'virtual' drives.

F3        -  Adjust Emulator Speed - this feature is quite crude at this 
	     point.      It simply inserts a delay between each Z-80 instruction.

F5        -  Adjust Output Volume - allows the sound volume level to be
	     adjusted.  Use the +/- or arrow keys to adjust, ENTER to exit.

F6        -  Invokes/Exits the TRSF-80 Z80 Debugger

F7        -  Selects the current keymap for the TRSF-80

F8        -  Selects the next of several color schemes

F9        -  Allows the user to Single-Step through the Z80 debugger

Shift-F9  -  Toggles the 'animate' mode (see the Z80 debugger section)

F10       -  Exits TRSF-80

F11       -  Allows the user to edit the Z80 registers (in debug only)

F12       -  Allows the user to edit the TRSF80 RAM     (in debug only)



--------------------------------------------------------------------------

VIRTUAL DISK DRIVE SUPPORT:
===========================

The TRSF-80 emulator will emulate up to four 80-track disk drives.  The
F2 key will invoke the disk menu which can be used to load or remove disks
on-line.  

When the menu is first displayed, the list of available disks (those with 
the extension ".DSK") in the current drive will be shown on the left side
of the screen.  Only the first forty disk names will be displayed.

To mount a disk, use the arrow keys to highlight the desired drive and type
in the name.  Unless an extension is specified, the system will automatically
append ".DSK" to the filename.  Once ENTER or one of the arrow keys is 
pressed, the system will attempt to mount the disk.  If successful, the 
message "OK" will appear to the right of the name.  If unsuccessful, the 
message "UNABLE TO OPEN FILE" will appear.  

An unsuccessful message can appear for several reasons if the selected file
does not exist in the current directory.  Check both the directory path and
the name entered.  This will also appear if the file is write-protected.
The emulator currently does not support write-protected disks.

To unmount a disk from a drive, simply leave the name for that drive blank.  
If you wish to abort an entry after starting to type, press the ESC key 
(note that this will not abort the entire disk menu session, only the current 
entry). 

If none of the four drives are mounted, pressing reset (SHIFT-F1) will reset
the virtual TRS-80 without disk support into Basic.



--------------------------------------------------------------------------

KEYBOARD EMULATION:
===================

There are two keyboard layout maps supported.  The first attempts to map the
IBM keyboard as best as possible into the TRS-80 key scan memory.  The main
purpose of this layout is to keep the familiar IBM layout but allow it to be
used with the TRS-80.

The second layout is designed to mimic the original TRS-80 keyboard.  This
keyboard has the following layout:

     
    ĿĿĿĿĿĿĿĿĿĿĿĿ
     !  "  #  $  %  &  '  (  )     *  = 
     1  2  3  4  5  6  7  8  9  0  :  - 
    
      ĿĿĿĿĿĿĿĿĿĿĿĿ
                                          
       Q  W  E  R  T  Y  U  I  O  P <-  ->
      
	ĿĿĿĿĿĿĿĿĿĿĿ
	                                 
	 A  S  D  F  G  H  J  K  L  ;  @ 
	
	  ĿĿĿĿĿĿĿĿĿĿ
	                        <  >  ? 
	   Z  X  C  V  B  N  M  ,  .  / 
	  

Additionally, the "TAB" key is used as the up arrow and the "CTRL" key
is the down arrow.  On both layouts, the "ESC" key is used as BREAK and
"HOME" or "ALT" serve as CLEAR.  To maintain compatibility with Jeff
Vavasour's emulator, the "CAPS LOCK" key also serves as SHIFT-@.


--------------------------------------------------------------------------

Z-80 ASSEMBLY LANGUAGE DEBUGGER:
================================

The Z-80 debugger is provided to allow programmers the ability to detect 
problems with the programs they have written.  It may also be useful in
detecting problems with my emulation :). 

The Z-80 debugger provides three main windows which display the current
state of the virtual TRS-80.  In the left window, the debugger displays a list
of Z-80 assembly language instructions which indicate both the commands
previously executed and the commands to be executed.

Z-80 Disassembly Window:
------------------------

The highlighted item in the center of the window indicates the command at the
current program counter (PC) location.  The lines which follow below indicate
the list of commands to be executed.  This list is based solely on the
subsequent memory locations, and may not be the exact commands executed due
to branching.  The first part of the window (the lines before the highlighted
line) indicates a history of commands that have been executed.  For every
change in the PC, the history list is scrolled up and the bottom line is
replaced with the instruction from the last PC.

Memory Contents Window:
-----------------------
 
The bottom window displays the current contents of memory.  Memory can be
edited by pressing the F12 key.  Once the memory edit option is invoked, the
arrow and PgUp/PgDn keys can be used to move the cursor to different memory 
locations.  Once the desired memory location is highlighted, the 0-9 and A-F
keys can be used to enter a new value.  All entries are in hexadecimal.

Z-80 Registers Window:
----------------------

The right window indicates the current contents of the emulated Z-80 processor
registers.  These registers can be edited by pressing the F11 key.  Once the
register edit option is invoked, use the up/down arrows to select the desired
register and type in the new value.  Pressing <ESC> will abort the current 
entry.

At the bottom of register window are two additional parameters listed.  The
first is the 'Memory Track' status and the second is the Breakpoint status.

Memory Track:
-------------

The 'Memory Track' feature was added to allow the address of the memory
window to track one of the Z80 registers.  To select the desired register to
track, select the 'MEMORY TRACK:' line in the register edit window.  The left
and right arrows change the current selection and also automatically update 
the memory display.  

The selection of 'FIXED' allows the memory window to be fixed on a specified
address.  This address is entered into the 'TRACK ADDR:' entry.  This address
is also adjusted automatically when the memory display is scrolled using the
arrow or PgUp/PgDn keys.  

Breakpoint:
-----------

The Breakpoint option allows the system to run at full speed until the 
specified breakpoint address is reached.  When a match is found, the debugger
is automatically invoked.  The breakpoint is adjusted through the F12 register
edit menu.  The breakpoint can be enabled/disabled by selecting the 'ACTIVE:'
line and pressing the left or right arrow keys.

Single-Step and Animate:
------------------------

Once the debugger is invoked, the emulator can proceed in one of two modes.
The first is the Single-Step mode in which the processor only executes 
instruction based on a command by the user.  Pressing the F9 key will cause
the emulator to execute only a single Z-80 instruction.  The display will be
updated, and control will be returned to the user.

In the 'Animate' mode, the emulator will proceed automatically, though the
debug display will be re-drawn between each step.  The 'Animate' mode can
be invoked be pressing Shift-F9.  Though the emulator will run at normal 
speed, the re-painting of the display will affect the performance.


--------------------------------------------------------------------------

License Information and Copyright Notice
========================================

TRSF80 is Copyright(c) 1996 by Ron Fries

This program is free software; you can redistribute it under the terms of 
version 2 of the GNU General Public License as published by the Free Software 
Foundation.

This software is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE.  I am not responsible for any damages caused through 
the use of this program.  See the GNU General Public License for more details.

NOTE: the GNU General Public License specifies that the source-code be 
released as well.  The source code has not been included with this release
as it is still in beta test.  The source code will be included with the 
first official release.

To obtain a copy of the GNU Library General Public License, write to the Free 
Software Foundation, Inc., 675 Mass Ave., Cambridge, MA 02139, USA.

Any permitted reproduction of these program, in whole or in part, must bear 
this legend.  
