6809 TRS-80 CoCo 3 Emulator (C) 1993-1998 Jeff Vavasour
6309 Microprocessor Enhancements (C) 2002-2004 John Collyer

For contact information and more details:

http://users.zoominternet.net/~johncollyer/


The COCO3X.EXE in this directory represents version 1.9 of the CoCo 3 Emulator.

This code is provided as-is and without warranty. Copyright remains with the author.
Not for public or commercial distribution, in whole or in part.  If you wish to refer
others to this code, please do so by the URL above.  Please do NOT link directly to
any files The 6309 Micro Processor Project.


The 6309 Micro Processor Project includes these enhancements to the
TRS-80 COLOUR COMPUTER 3 EMULATOR.

You get a new 6309 microprocessor to replace the 6809 microprocessor.
Here is a little bit of history to get you in the mood to appreciate
your new 6309 microprocessor and all the neat tricks it'll do for you.

Plus you will still be able to run all of your 6809-microprocessor programs,
and they run exactly the same as before except now they run faster.


History:

A 6309 microprocessor is a third party, backwards-compatible replacement
processor for the Motorola 6809.  It has a much more powerful instruction
set, making it popular amongst hardcore CoCo hobbyists.  HITACHI says in
the manual of the 6309 that the 6309 are compatible with 6809, but some
OS-9 hackers found that it has secret features.  At first the 6309 was
thought to be a flaky chip because it would sometimes crash or change the
values of registers when it encountered an addressing mode or opcode invalid
to the 6809.  This was later found to be an extended instruction set and a
feature that would trap some programming errors and jump to a specified
location in memory.


Enhancements:

In keeping with the OS-9 hacker philosophy, there is a new 6309 instruction
operation code has been added to the 6309 microprocessor core, a program
break point instruction.  The byte sequence $11FC is interpreted as (BREAK POINT)
instruction, which is used by debuggers to trap program break points.  You insert
the byte sequence wherever you want a break point and the CoCo 3 Emulator will
jump to the 6309 Monitor and Debug Facility located on the next instruction, ready
to step through your code or use any of the other debugging aids available.

You can enable (BREAK POINT) by writing $4A to $FF86 and $56 to $FF87 to allow
enhanced instructions.  Once this is done, the 6309 opcode $10FC will take on a
special meaning namely the BREAK POINT instruction.

Inside of the Mode Register (MD) there are two new mode register enhancements
(BLITZ and DEBUG).  The BLITZ mode lets you switch between logical results going
to a register's bit# or to the direct page memory's bit#.

See the HD63B09EP Technical Reference Guide for more details.

The DEBUG mode lets you use the 6309 Monitor and Debug Facility for illegal instruction
and divide by zero errors instead of the emulation handling them.  This can be useful
for debugging your programs, because you can quickly catch any errors and fix them
before you release your software to the CoCo community.


The 6309 Monitor and Debug Facility:

The 6309 Monitor and Debug Facility, was completely overhauled to help support the 6309
microprocessor.  The 6309 Register display now includes all the 6309 registers.  Under
the 6309 Register display is the GIME register display.  This register display will show
you how and where you have used the Gime command in conjunction with the GIME bits of the
Option register.  Additionally, this display will become a stack of return values for the
Gime command, which will allow you to undo your work; unless you want to keep the Gime
Registers the way you set them for any particular reason.  This will prevent a crash of
the emulator when you use the Continue command to return to the emulation.

There is the Mode register (MD) and it works exactly like the 6309 FLAG register.
You can access the Mode register by the [Z] for the RegZ command.

See the HD63B09EP Technical Reference Guide for more details.

The 6309 Monitor and Debug Facility [D] command (Disassemble) includes the disassembly
of all the new 6309's instruction set and also the OS-9 command for SWI2 interrupt,
which will aid you in the disassembly of OS-9 code.

You will find the addition of a [P] Option register and the [G]  Gime command.

First the Option register, which consists of 8 BITS (1 byte).  These bits are like
the records that you find in (MASM).

The fields are made up of the (A B C D G I M E) bits.  So far there are three fields.
Two of the fields are toggles (Flags) just like in programming, and they are either OFF/ON.

The first flag is the B (bit), which will toggle a flag that will affect the way the 6309
Monitor and Debug Facility interprets the SWI2 interrupt opcode.  It can be either
(BASIC/OS-9) style.  The second flag is the C (bit), which will toggle a flag that will
affect the way the 6309 Monitor and Debug Facility outputs disassembled instructions.
They can be either (UPPER/lower) case.  Lastly is the GIME (bits) field.  This field will
affect the Gime command and must be set right, for the Gime command to work the way it
should.  The G (bit) toggles the Gime command (Off/On).  The IME (bits) give you the
physical memory location that you want to move a virtual 8K block of memory too.

G       To use the Gime command this bit must be set.

I M E   This is the hard address to use for the memory mapping.
        This group of bits will be one of:

        Bit(s)    000 001 010 011 100 101 110 111

        cpu page   0   1   2   3   4   5   6   7

        cpu page  8k * 8 = 64k cpu virtual memory area

        So if you want to see physical memory page 7FFh (only with 16Mb)
        and you wanted to map page 7FFh to cpu virtual memory stating at

        &H2000 - &H3FFF the GIME bits would look like this - G I M E
                                                           - 1 0 0 1

        &H4000 - &H5FFF the GIME bits would look like this - G I M E
                                                           - 1 0 1 0

        Page#     | 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7
        Address:  0000h  2000h  4000h  6000h  8000h  A000h  C000h  E000h

Extreme caution is needed when you are altering the GIME registers in the Color Computer 3,
because if you alter any of the GIME registers and you return to the emulator by using the
Continue command, and the GIME registers are not exactly the way they were before you altered
any.  You might experience a crash if you are not careful about what and how you changed any
memory or GIME registers. Therefore, be careful and write down any changes you have made so
you will not have to reset the emulator because you altered any GIME registers or a  memory
area inside the cpu's address range.  However, later the GIME register display will become a
GIME stack area that will restore the previous GIME register values automatically for you.

The GIME register display can be seen below.

+---------------+
¦Registers:     ¦
¦D  000B (A/B)  ¦ The GIME display is; the current value of the GIME
¦W  0000 (E/F)  ¦ register you just altered by using the Gime command.
¦V  0000        ¦
¦X  028A        ¦ 
¦Y  A00E        ¦ However, this will later become a GIME stack, which will
¦U  ABEE        ¦ restore the GIME register values automatically for you.
¦S  7F2B        ¦
¦PC A7D5        ¦
¦DP 00          ¦
¦---------------¦
¦GIME  0000 0000¦ GIME: BLOCK NUMBER | CPU ADDRESS. Can be one of...
¦---------------¦       $0000-$8012  | $0000 = IME of the Option register
¦Stack U    S   ¦                    | $2000 = IME of the Option register
¦---------------¦                    | $4000 = IME of the Option register
¦ +00  4F4B A0D9¦                    | $6000 = IME of the Option register
¦ +02  0D00 0102¦                    | $8000 = IME of the Option register
¦ +04  0D42 DDA1¦                    | $A000 = IME of the Option register
¦ +06  5245 73A3¦                    | $C000 = IME of the Option register
¦ +08  414B 9DAC¦                    | $E000 = IME of the Option register
+---------------+


3. RAM extensions (for interest to advanced programmers)

    There are two extensions to the emulator's RAM beyond the 2 megs supported
    in version 1.6.  First, there is the additional 152K of native graphics and
    I/O RAM.  Second, on systems with 16 megs or more of EMS memory available,
    the emulator will make available 16 megs to the emulated CoCo's CPU.

    Both of these memory extensions are available through the MMU extension
    registers at $FF70-$FF7F.  When combined with the traditional $FFA0-$FFAF MMU
    registers, you form a 16-bit MMU page number (with the MSB drawn from $FF70-$FF7F)
    as follows:

    Pages           Description
    
    $0000-$003F     Traditional 512K of CoCo RAM
    $0040-$00FF     Additional banks available in 2Mb and 16Mb configuration
    $0100-$07FF     Additional banks available only in 16Mb configuration
    $8000-$8012*    152K native mode I/O memory (native video, keyboard, etc.)

    * IMPORTANT: before you can access pages $8000-$8012, you must first enable
      the NATIVE mode by writing $4A to $FF86 and $56 to $FF87.  This also
      enables the Intel native code support available since version 1.6 of the
      emulator.

The OPTIONS MENU (1.2MB drive as) option has been changed to the (Speed scale) option
and the (1.2MB drive as) option is now available from the command line in the form of
a parameter on the command line.

 * The parameter is enabled by including it on the command line "/8".  It must be the
   first option on the command line before you enter any other command line parameters.
   This will enable the 1.2MB disk drive support to behave like a 80 track disk drive.
   To ensure you have enabled the "/8" option you must delete the GENERALX.CC3 file from
   your directory, so the emulator can overwrite the default value, which is to have the
   1.2MB  disk drive act like a 40 track disk drive, or just set it with a older emulator
   version before replacing the emulator execution file with any newer version and the
   parameter should be set.  This version will only write the "/8" option to a new
   GENERALX.CC3 file, so you must delete the current GENERALX.CC3 file before you can
   expect any results with the "/8" parameter.

 * For a long time users of the emulator have wished for a way to have the directory window
   in the [F2] Virtual Disk Menu only show the number of disk drives they really have on
   their system.  Instead they have been forced to scroll down through 26 disk drives that
   represented (A-Z) LASTDRIVE in MS-DOS.  In MS-DOS you could use the LASTDRIVE= inside of
   your Config.Sys file, but if you are using a newer Operating System that option is gone.
   Also using the LASTDRIVE= in the Config.Sys file takes away precious memory from your
   system.  Now there is a way to get around this by using a brand new parameter "/L"  The
   "/L" parameter will be used only once to set up how the emulator shows the number of
   drives inside the directory window.  Just like the "/8" parameter you must follow strict
   steps to make it work, otherwise you'll wonder why it's not working like it should.

 * The first step to take is to delete the DRIVES.CC3 file from your emulators directory.
   The second step is to use a MS-DOS shell to run the emulator using the "/L" parameter.
   The "/L" parameter has a Hexadecimal digit right after it.  If you have more then $0F
   disk drives then do not even bother using this option, but if you have say 4, 5,6,...,
   or 15 disk drives then you can use this option to cut down on the number of disk drives
   shown in the directory window.

 * The command line would look something like this.  The command below would set the total
   number of disk drives to five.

       D:\coco3>coco3x /L5

 * The third step is to make the emulator save it's DRIVES.CC3 file.  It does this either
   when you do a Reset from the F6 menu or you just quit using the F1 menu Quit command.
   Once you have done all that you'll be ready to start enjoying the emulator a little
   bit more.

 * The speed scale option lets you change the scale of the speed slider to different scales.
   You have 1 through 5 scales available and are shown with the scale number and a percent
   sign.

====================================================================
| 1 click = 1  clicks | 1 click = 10  clicks | 1 click = 25 clicks |
| 1 click = 50 clicks | 1 click = 100 clicks |                     |
====================================================================

 * Use the speed slider as you did before, but when you change scales the speed slider
   gets reset and you must start again to decrease the emulation's speed (A slow motion
   adjuster for different speeds.)

+---------------------------------------------------------+
¦ SPEED:       - ###################################### + ¦
¦ EXT. VOLUME: < ###################################### > ¦
+---------------------------------------------------------+


The OPTIONS MENU [B] and [C]  (Select what to use as the  joystick  for the emulator)

Options are ("Game A", "Game B", "Mouse", "CoCo Max", "Hi-res", or "None").  If you want
to run "CoCo Max" you will need to select CoCo Max interface now.  The Hi-res interface
is used for OS-9 Level 2 and NitrOS-9 it works in the Multi-Vue environment, before this
new addition the Hi-res selection produced inadequate results for OS-9 Level 2 and
NitrOS-9.

BASIC users can access a PC's feature the mouse.  To read the mouse, use the following:

        X=PEEK(&HFF86)*256+PEEK(&HFF87)       'get X coordinate of mouse
        Y=PRINT PEEK(&HFF88)*256+PEEK(&HFF89) 'get Y coordinate of mouse

This will return the X and Y coordinate of the PC's mouse (regardless of the joystick
settings in the [F6] Options Menu).

To read the PC's mouse button press use the following:

        PRINT PEEK(&HFF8A) returns the BUTTON (n) information where (n) equals
        1 = left button, 2 = right button, -1 = no new button state.

The OPTIONS MENU.  Same as the [F6] key, Virtual Disk Menu.  Same as the [F2] key,
and Snapshot/Program Pak Menu.  Same as the [F3] key, will no longer be accessible
through the mouse buttons.  Instead you must use the [F6], [F2], [F3] key to get to
these option screens in the coco 3 emulator.


The OPTIONS MENU [J] (Port for RS-232)

Now lets you select between COM1, COM2, COM3 and COM4.  This will make it much easier
for you to use your dialup modem for the RS-232 Port.  You can play around with OS-9
sending files back and forth through some sort of virtual communication device, such
as /t2 and a modem. This would allow development of terminal-type programs, etc.

Now you can have 2 virtual hard disks in OS-9 ( /H0 and /H1)

This package includes a virtual hard disk driver on the OS9UTIL.DSK.  See the read.me
file on the OS9UTIL.DSK for details.

The Virtual Disk Menu [F2].  See Section 4 of (Read me version 6) for details on using
CoCo disks with the emulator.  I will describe only the new details here.  Now there is
support that will allow you to switch virtual hard disk (/H0 and H1) on the fly.

To accommodate this new support it was necessary to enable the [F2] menu to search for
all files, so you could see your vhd files.  I would recommend that you make two
subdirectories (dsk and vhd) and put all your dsk and vhd files in there.  This will cut
down on trying to see them through all the other files in the main coco3 directory.  You
can not write protect the vhd files.

If you want to switch between vhd files do this:

Go to the [F2] menu and select your vhd files, then press [Esc], and either press Ctr+F10
to reset or do a chd and chx to set the default data and execution directories in os9.


The DSKINI and RETRIEVE commands.


These commands have been enhanced and they now let you copy from double sided virtual
emulator disks to real double sided CoCo Diskettes.  Plus these commands retain all
their past functionality and work exactly as they did before.

You can use the RETRIEVE command to get OS-9 double sided boot disks you acquire from
The NitrOS-9 Project.  You can get the latest versions of  (OS-9, NitrOS-9, Basic-09
and other related items) there.

http://www.nitros9.org/

Using the double sided disk images you make with the RETRIEVE command inside of the
TRS-80 COLOUR COMPUTER 3 EMULATOR.  You will follow the documentation and insert
side 0 of the virtual double sided disk into the emulated disk drive 0 and insert
side 1 of the virtual double sided disk into the emulated disk drive 2.  Now you can
type DOS from BASIC and boot into the double sided disk image located in drives 0 and 2.

Here is how you can make boot disks from the CoCo OS-9 Source Project work with
the coco3 emulator:

Step 1:

1. Insert a blank 5.25" DS floppy in to your drive (we assume A:)

2. Type the following command, replacing the name of the image:

DSKINI /T40 /D A: <diskimagefile>

Where <diskimagefile> is the image file you want to transfer to the
floppy disk. The image file transfer should start. When it is done,
take out the disk and try booting your CoCo with it.

Repeat steps 2-3 for each additional disk.

Step 2:

1. With the double sided diskette you just made above:

2. Type the following command:

RETRIEVE /T40 A: SIDE0.DSK
RETRIEVE /2 /T40 A: SIDE1.DSK

3. Start the emulator and [F2] Virtual Disk Menu.

Then, select the CoCo drive number 0 for SIDE0.DSK
Then, select the CoCo drive number 2 for SIDE1.DSK

Type DOS and NitrOS-9 Level Two or OS-9 Level 2 should boot up and you'll be in greeted
by either NitrOS-9 Level Two or OS-9 Level 2.  Make a new boot disk,  I recommend that
you create a new boot disk specifically tailored toward the emulator using the vhd hard
drives, clock, and your desired virtual disk drive types; 35, 40, or 80 Track - Single
or Double sided virtual disk drives.  You have four such virtual disk drives that can be
one of the above type drives.


Project History
Start Date: 05/25/2002
Last Date : 02/17/2004

John Collyer
