TRS-80 COLOUR COMPUTER II EMULATOR Ver. 1.30 (C) 1993,94 Jeff Vavasour
======================================================================

(Internet e-mail to jeffv@physics.ubc.ca)

1. DESCRIPTION
--------------

This package is a complete* emulator designed to make your PC imitate a 
genuine CoCo II with 64K and four disk drives.  It has also been tested
successfully with the Dragon 32's 16K ROM, though you must use the Options
Menu (F6 in the emulator) to select the Dragon keyboard.

It requires EGA graphics and 256K RAM.  Also, a 286 with at least 12 MHz 
is recommended, though you'll need a faster processor to get operating 
speed that matches the real machine.  (A 33 MHz 486, on the other hand, 
is drastic overkill.  A slowdown option is provided for users fortunate 
enough to posess such a beast.)

Version 1.30 is the second release of this package, and includes several     |
corrections and enhancements.  Most notable of the bugs which have been      |
addressed are those which can cause emulator lockup in OS/9 Level 1 and      |
certain non-standard accesses to the joystick or keyboard.  Enhancements     |
include a powerful 6809 debugger/monitor, improved keyboard handling, and    |
a utility to move files between the CoCo and MS-DOS environments.  Through-  |
out this .DOC file, the "|" character on the right indicates changes to the  |
documentation from version 1.20.                                             |

This program is freeware, though copyright remains with the author.  You
are permitted to distribute the UNALTERED .ZIP package, as long as all  
programs listed in section 2 are included.  Also, this package may not be
sold or distributed commercially or for profit, though a reasonable media 
charge for distribution is acceptable.  

Please feel free to forward any comments to me at the email address above,
or the postal address given in the "comments" section below.  (Alternate 
email addresses are given there as well, but they should only be used if my 
primary email address fails.)


* Footnote: For those technically inclined, all features and hardware of the
  standard equipped CoCo have been reproduced with the exception of the
  cassette port and the 63.5us horizontal sync interrupt.  The standard 60Hz
  clock interrupt *is* reproduced.  The "bit-banger" serial output has also
  been rerouted to the PC's printer port, allowing for its use as a printer
  port.  The DSKINI command will also not work within the emulator, but all
  disks are automatically formatted when first used anyway.


2. GETTING STARTED
------------------

This emulator is provided as a .ZIP package containing the following files:

COCO.DOC        - this file
COCO.EXE        - the main emulator program
COCOUTIL.DSK    - CoCo program to retrieve your ROM
DSKINI.EXE      - a utility to format CoCo-compatible disks
PORT.BAS        - an MS-DOS BASIC program to move files between virtual      |
                  disks used by the emulator, and your MS-DOS directory      |           
RETRIEVE.EXE    - a utility to read CoCo-compatible disks

All files except COCOUTIL.DSK have been revised since version 1.20.          |

The only thing that you will need that is not provided with the emulator
is the ROM of a genuine CoCo.  Naturally, this could not be included here
for copyright reasons, but any CoCo I or CoCo II will do to get you started.

If you don't have a disk drive with your CoCo, you'll need to build a special
cable to connect your CoCo and PC, but don't worry it's *very* straight 
forward and requires only three wires.  Detailed instructions are given in
the Appendix.  

Section 2.1 explains how to retrieve the ROM via disk, while section 2.2
explains how to do it on a diskless system.  (No additional hardware is
required for those using disk.)

Also, Paul Burgin's Dragon 32 emulator (available via ftp from "ftp.funet.fi"
in the "/pub/msdos/interfaces/emulators" directory as "PCDGN101.ZIP")
is capable of reading the ROMs from a CoCo-generated cassette using the 
SoundBlaster.  As an alternative to the cable method for diskless systems,
section 2.3 explains how to convert these files for use with my emulator.


2.1 OBTAINING THE ROM VIA DISK
------------------------------

In MS-DOS, place a blank 5 1/4" disk in your drive and type:

DSKINI d: COCOUTIL

where "d:" identifies the drive containing the disk (e.g. "A:", "B:", etc.).
Place this disk in drive 0 of your CoCo and type (on the CoCo):

RUN"GETROM"

Next, place the disk back into your PC and type:

RETRIEVE /R d: COCO.ROM

Again, "d:" identifies the drive containing the disk.  (Note that in both
cases, "A:" is the default if this parameter is omitted.)

You are now ready to run the emulator.  (See section 3.)

   
2.2 OBTAINING THE ROM FROM DISKLESS MACHINES
--------------------------------------------

This method requires at least version 1.1 of the CoCo BASIC ROM.

Once the cable is built and tested, connect your PC and CoCo together and 
load your favourite terminal program on your PC, setting it to 2400 baud,
no parity, 1 stop bit, 8 bit word length.  Select the file capture option 
and record all data received to the file "COCO.ROM".  Then, run the 
following program on your CoCo:

10 POKE 150,18
20 PRINT#-2,CHR$(0);CHR$(128);
30 FOR X=32768 TO 49151
40 PRINT#-2,CHR$(PEEK(X));
50 NEXT

Pay particular attention to the semicolons in this program.  Once the CoCo
is done and the "OK" prompt returns, close the captured file.  Check that
it should be 16386 bytes long in your MS-DOS directory.  You may now run
the emulator.  (See section 3.)

If the file is too long, there may be a problem with your terminal program
and you should try another.  (The file is being transmitted as a binary
file so no filters should be used in your terminal program.)


2.3 USING PCDGN101.ZIP'S ROM FILES (DISKLESS SYSTEMS)
-----------------------------------------------------

Follow the instructions with Paul Burgin's emulator to generate the *.DGN
ROM file.  Then, type the following commands in MS-DOS:

DEBUG filename.DGN
M 110 L 4000 102
A 100
DW 8000
{press ENTER an extra time here to get the "-" prompt back.}
N COCO.ROM
W
Q

You have now generated the file "COCO.ROM" which COCO.EXE can use.


3. RUNNING THE EMULATOR
-----------------------

With COCO.ROM in the default directory, type "COCO" at the MS-DOS prompt and
press ENTER.  The emulator will start, with a title banner and list of 
function keys appearing.  Pressing any key will begin the operation of the
emulator.  This screen may be redisplayed at any time by pressing F10.

Some other functions are as follows:

F1: Activates the 6809 debugger.  See section 7 for details on its use.      |
    If you enter this option accidentally, press "C" to return to the        |
    emulator.  Pressing "Q" will quit the emulator and return to MS-DOS.     |
    You will be prompted to enter "Y" to confirm if you attempt to quit.     |
    (Now users of version 1.20 know what the F1 key was reserved for...)     |

F2: The virtual disk menu.  The emulator uses special "virtual disk files"
    to represent disks (with the extension .DSK, like "COCOUTIL.DSK" provided
    with the emulator).  This menu allows you to place these "disks" into one
    of the four "disk drives" of the emulated CoCo.  This is done by 
    selecting a drive number and then typing in or selecting the disk's
    name from the directory listing on the right.  New "virtual disks" may
    be created by entering an unused name.  They will already be formatted
    once created, eliminating the need for the CoCo's DSKINI command.

    Also, drives may be "write protected" by pressing SHIFT and a drive 
    number.  A bar around a drive number indicates that it is write protected.

    ESC returns to normal emulation.

F3: Snapshots.  The entire state of the emulator, such as a program or a 
    game-in-play may be saved to an MS-DOS file, to be retrieved later
    (even if you exit the emulator or turn off the computer between 
    sessions.)

    To save a snapshot, press "S" and then type in a name or select it from
    those already in the directory.  To load, press "L" and select a name
    as before.  ESC aborts this option.

F4: This turns the sound option on or off.  With sound on, 1-bit and 6-bit
    CoCo sound is reproduced on the PC's feeble internal speaker.

F5: This changes the keyboard layout.  You have a choice between the PC's
    layout or the CoCo's.  In the CoCo layout, SHIFT-2 would be a quote
    will in the PC layout, SHIFT-2 is an "@".  Other keys may not be so
    obvious: ESC is the BREAK key, ALT is the CLEAR key.  The arrow keys 
    on the keypad also work, but NUM LOCK should be off for this.  

F6: Options menu.  Pressing the letter associated with an option changes it.
    Also, the "+" and "-" keys speed up or slow down the emulator.  All
    other menus may be selected from this screen as it is obtainable using
    the right mouse button.  The user can also change the character set
    between normal/inverse characters (factory standard) and upper/lowercase
    (sometimes more pleasant to look at).  The left and/or right joysticks
    can be linked to the mouse, with the left button being the "fire" button.
    Also, a feature called "artifacting" is provided.  When "red" or "blue"
    is selected, the screen will blur the highest resolution screen to 
    simulate the colour effects of a CoCo used with a standard TV set.  This
    was considered a "feature" in some games.

    You may also reset the CoCo or quit the emulator using this menu.  Once
    one of these options have been selected however, you must hit "Y" or "N"
    only to confirm or reject your choice.

    NOTE FOR DRAGON 32 USERS: (KEYBOARD SELECTION)

    The keyboard layout is also selectable in the F6 menu, though 
    it has four options rather than two.  They are "PC" and "CoCo" -- as
    described for the F5 key -- and "DragonPC" or "Dragon" which are the
    analogous choices for the Dragon 32 keyboard mapping.  If you select
    Dragon or DragonPC in this menu, the F5 key will then toggle between
    these two settings, rather than "PC" and "CoCo".

    If you use the keyboard selection for one of the CoCo or Dragon, but
    the ROMs of the other, then the keys will not respond properly.  (For
    example, the "A" and "1" keys will be exchanged.)  This is corrected
    simply by pressing F6 and using the keyboard layout option to select
    the correct keyboard. 


4. USING REAL DISKS WITH THE EMULATOR
-------------------------------------

The DSKINI and RETRIEVE programs have a more general purpose than just
retrieving the ROM.

Any virtual disk file may be written to a 5 1/4" disk, readable by the
CoCo by entering:

DSKINI [d:] [diskname[.DSK]]

where "d:" is the destination drive and "diskname" is the source virtual disk
file.  At least one of these two parameters must be given.  (The default
drive for "d:" is A:.)  Paths may be included in the diskname parameter.
If "diskname" is omitted, a blank disk is formatted.

Disks created by DSKINI.EXE may also be read back to virtual disk files 
using

RETRIEVE [d:] diskname[.DSK]

You can use this method to transfer files from your CoCo disks to the 
emulator by following these steps:

1. Create a CoCo disk on your PC using DSKINI.EXE.
2. On your CoCo, use BACKUP or COPY to copy the files onto the disk you've
   just created in step 1.
3. Put the disk back in your PC and use RETRIEVE.EXE to make a virtual disk
   file from it.

It may also be possible to use RETRIEVE directly on your original CoCo       |
disks, but most PCs' disk controllers are very picky about formats           |
(resulting in a read error on one sector per track).  If this happens,       |
your only choice is to follow the three steps above.                         |


5. USING PROGRAM PAKS WITH THE EMULATOR
---------------------------------------

There are two ways to read a Program Pak on a CoCo while staying in BASIC.   |
Either you can cover up the pin on the cartridge that tells the CoCo to      |
auto-start it, or you can plug the cartridge in with the power on, after     |
starting the following program.                                              |
                                                                             |
WARNING: THERE HAVE BEEN MANY HORROR STORIES OF AN IMPROPERLY INSERTED       |
         CARTRIDGE BLOWING THE UNPROTECTED CPU WHEN THE POWER IS ON.  If     |
         you elect to use the latter method, do so carefully and proceed     |
         at your own risk.                                                   |
                                                                             |
To transfer your Program Pak to a PC, you will need the same cable used for  |
the diskless ROM transfer.  Then, complete the following steps:              |
                                                                             |
1. IF YOU ARE USING THE COVER-THE-PIN METHOD, take the cartridge you are     |
   going to use and pull the cover back to expose the pins.  Then, cover     |
   up the fourth pin position in on the left on the bottom (pin 8, the       |
   "CART" signal).  (IMPORTANT: Most cartridges have no contacts for the     |
   first three positions, so this may be the first plated-contact from the   | 
   left.  In this case, you can usually see where the other three positions  | 
   should be by the scratch marks from frequent use.)  If needed, you can    |
   also cover up the pin on the top side directly above this one, as well as | 
   the three pin positions to each of their lefts if necessary.  Be careful  |
   not to cover the fifth pins in as this will make the cartridge            |
   unreadable.                                                               |
                                                                             |
   Once this is done, insert the Pak into your CoCo with the power off, then |
   turn on the computer.  If you are successful, the CoCo will power up into |
   BASIC's "OK" prompt despite the cartridge being present.                  |
                                                                             |
2. Next, for both methods, type in the following program in your CoCo:       |

   10 POKE 65315,54
   20 INPUT"INSERT PAK AND PRESS [ENTER] TO SEND";X$
   30 POKE 150,18
   40 PRINT#-2,CHR$(0);CHR$(32);
   50 PRINT#-2,CHR$(0);CHR$(192);
   60 FOR X=49152 TO 57343
   70 PRINT#-2,CHR$(PEEK(X));
   80 NEXT X
   90 FOR X=1 TO 33
   100 PRINT#-2,CHR$(0);
   110 NEXT X
   120 PRINT#-2,CHR$(0);CHR$(192);

   Note: You may omit lines 10 and 20 if using the covering-the-pin method.  |

3. Connect your PC to the CoCo and prepare a terminal capture program on your
   PC as described in section 2.2.  (Use the extension ".PAK" for Program 
   Paks.)

4. Run the BASIC program on your CoCo.  If you are using the insert-with-    |
   power-on method, insert the cartridge when you are prompted to do so and  |
   then press ENTER.  This will begin transmission of the cartridge's data.  |

The resulting file on your PC should be 8231 bytes long.  

To run the Program Pak in the emulator, simply use the Snapshot Menu.

For those who have copied their Program Paks to their PCs using some other
method, the general format of the file constructed by the above program is:

- 2 byte ROM length (LSB/MSB, usually 8192 decimal)
- 2 byte start address (LSB/MSB, usually C000H)
- ROM data (usually 8192 bytes)
- 33 bytes of 0's
- 2 byte entry address (LSB/MSB, usually C000H)

Selecting RESET in the Options Menu will return to BASIC.  (Disk BASIC users
may wish to copy over their Disk BASIC as a Program Pak so they may reload
it after running a Program Pak.)


6. MOVING FILES BETWEEN COCO DISKS AND YOUR MS-DOS DIRECTORY                 |
------------------------------------------------------------                 |
                                                                             |
As a side-beneift, the CoCo II emulator provides a way to move your CoCo     |
files to your PC environment.  The program "PORT.BAS" is a PC BASIC program  |
which will run on either GW-BASIC/BASICA or QBASIC, found on virtually all   |
MS-DOS systems.  This program can move files between your MS-DOS directory   |
and the virtual disk ".DSK" files used by the emulator.  To make a ".DSK"    |
file out of a CoCo disk, or to write a ".DSK" file to a floppy, follow the   |
instructions in section 4 above.                                             |
                                                                             |
After starting "PORT", select a target virtual disk to use.  (A directory    |
of .DSK files in the default directory is automatically shown.)  You will    |
then be presented with a menu of options which will allow you to read        |
files from the .DSK virtual disk to your MS-DOS directory, write files to    |
the virtual disk, delete files on the .DSK, or show directories of either    |
your default MS-DOS path or the virtual disk.                                |
                                                                             |
The PORT program's menu is pretty self-explanatory, but you should be aware  |
of the following:                                                            |
                                                                             |
1. Be sure to select "X" to exit or "N" for a new virtual disk when you are  | 
   finished, as the virtual disk's directory may not be updated until you do | 
   this.                                                                     |
                                                                             |
2. When prompted for files to read, write or delete, you may use either      |
   "filename.ext" or "filename/ext", but don't specify an MS-DOS path name   |
   with it.  Change the MS-DOS default path with the "C" option in the menu. |
                                                                             |
3. The PORT program will automatically change the line terminator of ASCII   | 
   files (as identified in the directory entry) to either CR/LF or CR as     |
   required by the destination system for the file.                          | 
                                                                             |
4. When writing files to a virtual disk, you are prompted to give an         |
   identifier for the file (e.g. "Basic program, data, M/L, or text file")   |
   as this information is not recorded in the MS-DOS directory.              |
                                                                             |
5. When using PORT with GW-BASIC, it may append a EOF byte (CTRL-Z) to the   |
   end of files read to your MS-DOS directory.                               |


7. THE DEBUGGER                                                              |
---------------                                                              |
                                                                             |
The debugger halts the emulator, displaying the current state of all the     |
registers in the "6809" CPU, and also includes a 128-byte memory map and     |
a disassembly of current instructions.  In the lower-left corner, the first  |
few entries on the U and S stacks are shown.  Several commands are available |
to you, as summarised in the box on the lower-right:  (These commands are    |
probably best understood through experimentation.  [ESC] will cancel any     |
option except [E]DIT, which is immediate.)                                   |
                                                                             |
[B] Sets a BREAKPOINT address.  The emulator will resume normal execution    |
    until the breakpoint is hit, at which time the debugger reappears.  Only |
    one breakpoint can be set at a time.  The breakpoint is cleared the next |
    the the debugger or another menu is displayed.                           |
                                                                             |
[C] CONTINUE emulation.  The breakpoint is cleared and the program returns   |
    to normal emulation.                                                     |
                                                                             |
[D] Change the start address of DISASSEMBLY.  A register or hexidecimal      |
    address can be specified.  If a register is given, the start address of  |
    the disassembly will always follow whatever is in that register.  The    |
    default for this prompt is the next byte after the last instruction      |
    displayed on the current disassembly.                                    |
                                                                             |
[E] EDIT memory.  Places a cursor on the memory map with which you can       |
    directly modify memory.  Arrows, PG UP and PG DN work.  ROM and memory-  |
    mapped device addresses behave as in the genuine machine.  ESC or ENTER  |
    when done.                                                               |
                                                                             |
[F] Change the 6809 FLAG registers.  Press the letter of the flag to toggle  |
    its true (1) or false (0) value.  ESC to abort, ENTER to keep changes    |
    and return to main debugger options.                                     |
                                                                             |
[H] HEXIDECIMAL CALCULATOR.  Enter a hex number or register to start.  You   |
    then enter one of the following operations:                              |
                                                                             |
    [+], [-], [*], [/], [A]nd, [O]r, [X]or, [N]eg, [S]hift, [R]ot, [D]ecimal |
                                                                             |
    The first seven of these will prompt for a second number or register to  |
    operate with.  [N] will NEGate the current result.  [S] or [R] followed  |
    by the left or right arrows will shift or rotate the bit positions of    |
    the result as appropriate ([ESC] to return to calculator options).  [D]  | 
    will display the decimal equivalent and/or allow you to enter a decimal  | 
    value.  [ESC] will return to the main debugger options.                  |
                                                                             |
[M] Change the MEMORY DUMP start address.  Enter either a hex address or a   |
    register.  If a register is used, the start address of the memory dump   |
    will always follow that register's contents.                             |
                                                                             |
[Q] QUIT EMULATOR.  Exits back to MS-DOS.  You must confirm this choice with |
    a "Y".  An other reply will return to the main debugger options.         |
                                                                             |
[R] Change REGISTER contents.  Select a register using the arrow keys        | 
    followed by [ENTER], or by pressing its letter.  Then type a new hex     |
    value for its contents, or the name of another register to copy that     |
    register's contents to the currently selected register.                  |
                                                                             |
[S] SINGLE STEP.  Execute one 6809 instruction and return to the debugger.   |
                                                                             |
[V] VIEW VIDEO.  Display the current CoCo screen and wait for a key to be    |
    pressed.  Pressing any key will return you to the debugger's main        |
    options.                                                                 |
                                                                             |
Register names are just there 6809 names, without brackets, except for the   |
D register.  D is entered as "A/B" to distinguish it from the hex numbers    |
000D, 000A, 000B, and 00AB.                                                  |


8. COMMENTS                                                                  |
-----------                                                                  |
                                                                             |
Please note, I CANNOT PROVIDE ROM IMAGES OR THE SOURCE CODE.  The lack of    |
availability of source code is a price you pay for this package being        |
freeware.                                                                    |
                                                                             |
One of the more common questions I have had after the first release of my    |
emulator (aside from bug reports) has been "will you be doing a CoCo III     |
Emulator?"  The answer to this is a bit difficult to say.  Part of the       |
reason that I decided to release the CoCo II emulator as a freeware package  |
(as opposed to shareware) is that I was afraid I wouldn't have the time to   |
provide as much support as I'd like.  This is one of four emulator packages  |
of mine.  The first was a shareware TRS-80 Model I (the Z-80 based machine   |
from 1977), followed by a freeware Timex/Sinclair 1000, then version 1.20 of |
this emulator, and finally a commercial TRS-80 Model III/4 Emulator (for     |
which the infrastructure of this CoCo II Emulator was the prototype, for the |
interest of those who might have seen both).                                 |
                                                                             |
Certainly, I am intrigued by the possibility of doing a CoCo III emulator,   |
but, as I am still providing support for the Model I emulator and the        |
relatively young Z-80 III/4 emulator, my spare time is limited.  I have      |
toyed with the idea of developing a SHAREWARE CoCo III emulator once the     |
demands of these other projects dwindle... if there is sufficient interest.  |
My shareware Model I package has a registration fee of $25, so I'd probably  |
be proposing something similar here.  Of course, this all hinges on whether  |
there is sufficient demand for such a product.  So, if you are interested or |
have any comments, drop me a line.  (Don't send any money yet! :-)  I don't  |
actually have a CoCo III emulator yet.)                                      |

Send comments or questions to:

e-mail address: jeffv@physics.ubc.ca
postal address: Jeff Vavasour
                c/o Department of Physics
                6224 Agricultural Road
                University of British Columbia
                Vancouver, B.C.
                Canada  V6T 1Z1

If you are having trouble with the above email address, then try 
"jeffv@smaug.physics.mun.ca" or "jeffv@morgan.ucs.mun.ca".  For Internet
users, I also have an email discussion group for users of my emulators.  
Drop me a line if you want to be included.


Disclaimers:  Neither this software package nor its development is in any
way associated with the University of British Columbia.  It is merely the
most reliable address I currently have.  Also, I assume no responsibility
for any damage that may result.

Acknowledgements:  Thanks to Jim Veneskey and Lori Paniak for their helpful 
references in developing and debugging this package.


APPENDIX: THE SERIAL CABLE
--------------------------

For diskless users, you will need a cable to link the serial port of your
PC to the CoCo's built-in serial port.  There are two kinds of serial
connectors on most PCs - the 9-pin and the 25-pin versions.

To start you will need a connector to mate with your PC's serial port.  For
those not used to hardware, it's best to get the "crimping" version.  No
soldering is necessary.

You'll also need a male 4-pin DIN connector.  Though Radio Shack has 
discontinued this part, many other electronics stores may still stock them
stocks these parts.  Also some Radio Shacks may still have a dusty unit
or two in stock.

The cable itself is very simple.  The pin numbers on the 9-pin and 25-pin
PC serial connectors are actually visible on the connector itself, next to
each pin.  For the 4-pin DIN connector, I will use the convention of the
CoCo's technical reference manual.  Looking at the serial I/O port on the
back of the computer itself, the pins are numbered as shown:
     
     _____              
   /  |_|  \                    Pin names: 1 = CD
4 | o     o | 1                            2 = RS232 IN
  |         |                              3 = GND
3 |  o   o  | 2                            4 = RS232 OUT
   \ _____ /


Three wires must be connected in this cable, listed below.  (The names of
the pins are also given for the reference of those interested.)  Be sure
to select the column appropriate to your PC serial connector.

From CoCo       To PC's        To PC's
4-pin DIN       9-pin          25-pin 
=========       =======        =======
Pin 2 --------> Pin 4   - or - Pin 20
(RS232 IN)      (DTR*)         (DTR*)

Pin 3 --------> Pin 5   - or - Pin 7
(GND)           (GND)          (GND)

Pin 4 --------> Pin 2   - or - Pin 3
(RS232 OUT)     (RD)           (RD)

Once the cable is assembled, it may be tested by loading a terminal program
on your PC and selecting the appropriate COM: port with the settings:
2400 baud, 1 stop bit, 8 word length, no parity.  Next, power on your CoCo
and type the following:

POKE 150,18
PRINT#-2,"THIS IS A TEST"

If the cable is working properly you should see the message "THIS IS A TEST"
on your PC.  If no message appears on the PC, but the "OK" prompt returns 
on your CoCo, check the line connected to the CoCo's pin 4 (RS232 OUT).
(A ohmmeter or continuity checker would be useful for this.)  If the "OK"
prompt fails to return, check pin 2 (RS232 IN).  Also, it is a good idea
to check the GND line in both cases.
