Technical Info:

What follows is technical information for users who want to know more about the emulator or want to develop support programs for the emulator or new software for the Color Computer running on the emulator. Nothing contained here is required to use the emulator.

Return to contents: 

Technical info - DMK type virtual disks:

This information on what has become known as the DMK virtual disk format is provided for users wanting to better understand the operation of the emulator and for programmers writing their own emulators wanting to add support for this format and/or the creation of PC utilities to work with the DMK virtual disk format.

This virtual disk format is as close to the way data on a real disk is stored as possible. There is very little added overhead and the data is easily examined and edited using PC based hex editors. The actual design is really quite simple and enables support of ALL the WD-1771 and WD-19xx controller functions and formats. While the design is simple however the programming requirements for this format are much more extensive then for the JV1/JV3 formats.

Disk header:

Virtual disks have a 16 byte disk header which is initialized when the user creates a new virtual disk. This header may be modified before or after a virtual disk has been formatted to change some of its characteristics. 

Track header:

Each side of each track has a 128 (80H) byte header which contains an offset pointer to each IDAM in the track. This allows a maximum of 64 sector IDAMs/track. This is more than twice what an 8 inch disk would require and 3.5 times that of a normal TRS-80/COCO 5 inch DD disk. This should more than enough for any protected disk also.

These IDAM pointers MUST adhere to the following rules.

• Each pointer is a 2 byte offset to the FEh byte of the IDAM. In double byte single density the pointer is to the first FEh.
• The offset includes the 128 byte header. For example, an IDAM 10h bytes into the track would have a pointer of 90h, 10h+80h=90h.
• The IDAM offsets MUST be in ascending order with no unused or bad pointers.
• If all the entries are not used the header is terminated with a 0000h entry. Unused entries must also be zero filled..
• Any IDAMs overwritten during a sector write command should have their entry removed from the header and all other pointer entries shifted to fill in.
• The IDAM pointers are created during the track write command (format). A completed track write MUST remove all previous IDAM pointers. A partial track write (aborted with the forced interrupt command) MUST have it's previous pointers that were not overwritten added to the new IDAM pointers.
• The pointer bytes are stored in reverse order (LSB/MSB).

Each IDAM pointer has two flags. Bit 15 is set if the sector is double density. Bit 14 is currently undefined. These bits must be masked to get the actual sector offset. For example, an offset to an IDAM at byte 90h would be 0090h if single density and 8090h if double density.

Track data:

The actual track data follows the header and can be viewed with a hex editor showing the raw data on the track. If the virtual disk doesn't have bits 6 or 7 set of byte 4 of the disk header then each single density data byte is written twice, this includes IDAMs and CRCs (the CRCs are calculated as if only 1 byte was written however). The IDAM and sector data each have CRCs, this is just like on a real disk.

Modification should not be done since doing so without updating  the CRCs would cause data errors. Modification could be done however to create protected tracks for importing protected disks to virtual disk format. Examples of disks created using this technique are the TRS-80 programs "Super Utility+ 3.0" and "Forbidden City".

Return to contents: 

Technical info - JV1/JV3 type virtual disks:

This emulator is capable of reading and writing to JV1/JV3 type virtual disks. Support for this type of virtual disk is limited by both the limits of the format type and this emulators support of it.

The emulator supports read sector, read address and write sector commands to the JV1 type virtual disk. JV1 disks are single density (Model 1) and double density (COCO), only. They can be up to 254 tracks long and always have a protected directory track at track 17. Read track and write track commands are not supported for this disk type. This disk  type can be write protected from the "virtual floppy disk selection screen" but the write protect status will always default to off when ever a JV1 disk is opened.

The emulator supports read sector, read address and write sector commands to the JV3 type virtual disk. JV3 disks are single/double density and can be up to 96 tracks long. Read track and write track commands are not supported for this disk type. This disk  type can be write protected from the "virtual floppy disk selection screen" but the write protect status will always default to what ever status is in the the JV3 virtual disk file (byte 21FFh) when the disk is opened, the write protect status is not updated. The density and CRC error flags are also supported but not updated. DAM types FB/F9 report FB and F8/FA report F8. Sector writes that change the DAM type from what is in the virtual disk file are not supported. This will not cause problems unless you try to change the protection status of a directory track. Standard IBM sector sizes are supported of 128, 256, 512 & 1024 bytes. A second sector header block is not supported.

Return to contents: 

Technical info - REAL COCO floppy disks:

This emulator is capable of reading, writing and formatting REAL COCO floppy disks in compatible PC floppy drives. Support for this is limited by both the limits of the NEC type floppy disk controller and this emulators support of it.

Depending on compatibility of your PC you should be able to read/write single density & double density 5.25" and 3.5" disks in 360k and 720k PC floppy drives (commonly known as low/double density drives, DD). You should be able to read/write double density 5.25" and 3.5" disks in 1.2meg and 1.44meg PC floppy drives (commonly known as high density drives, HD).

Eight fixed sector length REAL floppy specification virtual disks are supplied to read/write 256 byte/sector floppies in a PC's A: and B: drives.

Eight variable sector length REAL floppy specification virtual disks are supplied to read/write 128-1024 byte/sector floppies in a PC's A: and B: drives. These specification disks are slower than the fixed length ones and should only be used on disks un-readable with the fixed length specification disks.

Because of the limitations of the PC's NEC type floppy disk controller the PC cannot read most protected disks. The emulator does not support the track read commands with REAL floppies. Because of limitations of the PC's controller most disk zap utilities (like Hyperzap and Super Utility) cannot work with REAL floppies. Also the write track command has to translate format data to the PC's controller form and is therefore unable to format anything but standard sectors. Because of the translation for PC disk I/O, access to real TRS-80 disks is apt to be slow, formatting in some cases can take as long as 8 seconds/track. This is unavoidable and should not present problems since REAL disk support is mainly for importing your existing COCO disks and transferring data and programs to the COCO. If your PC has a hard time reading your COCO disks then use the emulator to format a disk on the PC and then copy the disk on the COCO to the PC formatted disk, this should correct most problems.

Some PC's cannot read any COCO disks without errors. This is a compatibility problem with different PC controllers and not a problem with the emulator. Try using a different brand of PC or an older model PC. If you are still unable to read your disks and really need the data converted, e-mail me and maybe I can convert the disk for you (my PC has been able to read every disk I've tried so far).

Return to contents: 

Technical info - Virtual hard disks:

This information on what are known as the HDV virtual hard disks is provided for users wanting to better understand the operation of the emulator and for programmers writing their own emulators wanting to add support for this format and/or the creation of PC utilities to work with the HDV virtual disk format.

Currently the COCO emulator does not support hard disks. This is the current HDV format that is used by other TRS-80 emulators and is provided so a compatible hard disk driver can be written for the COCO.

The existing HDV format has been extended to support 1024 cylinder hard drives using the WD1010 hard drive controller emulation.

Disk header:

Virtual hard disks have a 256 byte disk header which is initialized when the user creates a new virtual disk. This header may be modified before or after a virtual disk has been formatted to change some of its characteristics. 

WARNING: Once hard disk support is added to the COCO emulator this file layout may have minor changes.

Return to contents: 

Technical Info - Enhanced MC6809 instructions

The emulator has a set of enhanced MC6809 instructions. These instructions allow COCO programs to interface with the PC's disk drives, ports, memory and other hardware. These instructions also add high level math functions to the MC6809 instruction set.

NOTE: These instructions are only available in the emulators.

The following links contain a list of the enhanced instructions and documentation for each instruction.

Enhanced Instruction Documentation (on-line)

Enhanced Instruction Documentation (Microsoft Word 96k)

Return to contents: 

Technical Info - Memory mapped PC I/O commands

In addition to the enhanced MC6809 instructions described above the emulator can also interface with the PC using memory mapped commands. These commands provide an easier to use interface when writing programs in BASIC or other high level language eliminating the need for machine language calls.

The memory mapped I/O commands allow access to the I/O functions between $10 and $1F as defined in the Enhanced Instruction Documentation. Access to the other enhanced instructions 00-$0F are also possible but are less useful in BASIC programs.

These memory mapped I/O commands also allow access to the PC's hardware clock, PC's I/O ports & PC mouse.

These memory mapped functions use the MC6809 memory address $FFE0-FFEF:

Memory addresses $FFE0-$FFE7 allow access to up to 16 different sets of I/O data. These data sets can be either 8bit or 16bit values. The set of data available is determined by memory address $FFEF. When a value between 0 and 15 is written to $FFEF the desired set of data is mapped into memory $FFE0-FFE7. When the data set is 16bit, each memory address must be read/written twice to load/store the 16 bit value.

When accessing 16bit values, each read/write of memory $FFE0-FFE7 toggles which 8bits are available. Therefore when accessing 16bit data knowing which 8bits are currently available is very important. To make this possible, anytime $FFEF is written to, the high 8bits of the 16bit word is always selected. Then by accessing each memory address twice the programmer will always know which 8bits of the 16bit value are available.

For example to write the 16bit value of $1234 to $FFE0 do the following:

POKE &HFFEF, 3: REM TO INSURE THE HIGH 8BITS OF DATA SET 3 ARE SELECTED
POKE &HFFE0,&H12
POKE &HFFE0,&H34

After writing &H34 to the low 8bits of &HFFE0, $FFE0-$FFE7 are again pointing to the high 8bits. To read the data back, writing to $FFEF is not necessary since we know which 8bits are selected. A read or write to any address $FFE0-$FFE7 controls which 8bits all the memory addresses $FFE0-$FFE7 point to.

For example executing the following:

POKE &HFFEF, 3: REM TO INSURE THE HIGH 8BITS OF DATA SET 3 ARE SELECTED
PRINT PEEK(HFFE0)
POKE &HFFE1,0

would print the high 8bit value of the 16bit value stored in $FFE0 and then write a zero to the low 8bits of the 16bit value stored at $FFE1. This is more than likely not what the programmer wanted.

Writing to memory address $FFEE is used to execute enhanced MC6809 instructions. Valid values are $00-$1F. Each value corresponds to the second byte of an enhanced instruction. A write to $FFEE of a valid command executes the corresponding enhanced instruction. The instruction uses the values stored in memory addresses $FFE0-$FFE7 instead of the work area defined by register U and memory addresses $FFE8-$FFE9 instead of registers A & B that the instruction would have used when executed using assembler language. Memory addresses $FFE0-FFE9 must be initialized before execution of an enhanced instruction.

Reading from memory address $FFEE will return the status of the last enhanced instruction executed.

Memory addresses $FFE0-$FFE7 must be initilized to data set 0 by writing zero to $FFEF. Then, the up to 8 bytes of data used by the enhanced instruction is loaded into memory addresses $FFE0-$FFE7. Memory address $FFE8-$FFE9 always point to the last values sent to or returned by the last enhanced instruction executed, regardless of the setting of $FFEF.

The values stored in memory address $FFE8-$FFE9 are loaded into register A & B when executing enhanced MC6809 instructions. After an enhanced instruction's execution $FFE8 contains the register A value and $FFE9 contains register CC (condition codes) returned by the enhanced instruction.

Some program listings of BASIC programs are available as examples of using the memory mapped I/O commands:

BASIC Examples

Return to contents: 

Technical info - Memory mapped PC mouse functions:

The PC's mouse can be accessed from BASIC, assembler and other COCO languages through memory mapped I/O (see previous topic). Through simple reads and writes to COCO memory a COCO program can read the PC's mouse buttons and get its X & Y coordinates.

Writing a value of 4 to $FFEF will make the mouse I/O values available for access. The mouse values are 16bit and require two reads or writes to access all the values except for the buttons and sensitivity. These two 8bit values are also 16bit but the 8bit value is mirrored so a single read or write will access these values.

To read the PC mouse the program needs to read memory address $FFE0. This will load the X & Y coordinate values and return the current button status.

The button status shows which buttons have been pushed and which are currently pushed. Once a particular button has been pushed that flag will remain set until it is cleared by writing a zero to its bit at memory address $FFE0.

To get the current X & Y coordinates the program must read $FFE1 (X coordinate) and $FFE2 (Y coordinate) twice. For example the X coordinate is, the first value read at $FFE1 multiplied by 256 plus the second value read at $FFE1. The same is true for the Y coordinate.

Note: This assumes that the high byte of the 16bit value is available first. A read from memory address $FFEF will insure this condition. From that point on as long as the program always reads or writes each mouse I/O address twice the program will always be sure of the value available at each address.

The X & Y coordinate value returned is based on the PC's mouse movement and the minimum, maximum and sensitivity values loaded for the X & Y coordinates. The coordinate returned will always be in the range of the minimum and maximum values. The min/max values are 16bit values and are read and written the same way the actual coordinates are. The sensitivity is an 8bit value. The low 4bits the X axis sensitivity, the high 4bits the Y axis sensitivity. The larger the value the more sensitive that axis is.

Once the minimum, maximum and sensitivity values are loaded a program only need read $FFE0 to read the PC mouse buttons and update the X & Y coordinates then read $FFE1 & $FFE2 to read the X & Y coordinates. The emulator will insure the returned X & Y coordinates are always within the defined range. A program can also move the mouse to a new position by writing that new position to the X & Y coordinates. Note: no check is done to insure the new position is within the defined range, this must be done by the program.

See the BASIC programming examples, PGM4 for an example of how to use the PC mouse I/O function.

BASIC Examples

Return to contents: 

Technical info - Keyboard maps:

The COCO emulator support two keyboard maps. These files determine the relationship between the PC keyboard and the COCO keyboard. Each key on the PC keyboard can be mapped to a key on the COCO keyboard. More than one PC key can be mapped to the same COCO key (ex. Backspace & left arrow are both mapped to left arrow on the COCO keyboard).

Each keyboard map file contains 512 bytes which are organized in pairs. The first 128 byte pairs are unshifted keys the last 128 are the same keys shifted. The PC communicates with its keyboard using scancodes. Each PC key has a scancode and each scancode has a matching 2 byte value in the keyboard map. For example the 'ENTER' key has a scancode of 28, therefore the 2 keyboard map values at 2 times 28 plus 1 (57), contains the COCO keyboard value for an unshifted 'ENTER' key. The map values 2 times 28 plus 257 (313), contains the COCO keyboard value for a shifted 'ENTER' key.

Below is a graphic of a standard PC keyboard layout showing the scancodes for each key. All the scancodes shown correspond to a keyboard map entry. The PC key's table entry can be found by multiplying the scancode by 2 and adding 1 for unshifted values or adding 257 for shifted values.

Note: The scancodes for the cursor keys are not the actual scancodes but the scancode plus 32 because the actual scancodes are the same as for the number pad. The PC prefixes these keys with a special code. The emulator adds 32 to these prefixed scancodes so they can have their own keyboard map entries.

As said before each scancode points to a two byte pair. The second byte is the entry type, it has the following values:

The following table is to be used to find the first byte of the keyboard map value for entry type 0. The values in this table are in hex.

For example. If you look at the PC scancode graphic you will see that the 'ESC' key has a scan code of 1. If you look at the 3rd byte of the PCCOCO keyboard map file you will see a value of 38 (26 hex). Looking at the able above shows a value of 26H represents the COCO 'BREAK' key. The 'BREAK' key is in row 6 column 2 for the COCO keyboard matrix.

The 4th byte of the keyboard map file is a zero. This means the key is unshifted. If this value was 1 then anytime 'BREAK' was pushed the emulator would also push the COCO's shift key. This features allows keys that are not shifted on a PC keyboard to be shifted on the COCO keyboard (like '=') or shifted keys to be unshifted (like "@").

The following table is to be used to find the first byte of the keyboard map value for entry type 1. The values in this table are in hex.

For example. If you look at the PC scancode graphic you will see that the '= +' key has a scan code of 13. If you look at the 27th byte of the PCCOCO keyboard map file you will see a value of 85 (55 hex). Looking at the able above shows a value of 55H represents the COCO '- =' key. The '- =' key is in row 5 column 5 for the COCO keyboard matrix.

The 4th byte of the keyboard map file is a one. This means the key is shifted. When this key is pushed the COCO will be sent the '- =' key along with a shift key.

Most of the PC keys mapped to the COCO layout in the first half of the keyboard map will have an entry type of 0 since this section is used when neither of the PC shift keys are pushed. Most of the PC keys mapped to the COCO layout in the second half of the keyboard map will have an entry type of 1 since this section is used when either of the PC shift keys are pushed. Also, in most cases the first byte of a key entry in the first half of the map will be the same as the one in the second part of the map since it is just the shifted value of the other. Some of the PC keys however will have very different values in each half of the map (like' = +') for example because of the differences between the PC and COCO keyboard layouts.

I hope this documentation will give users the information needed to create custom keyboard layouts.

Return to contents: 

Technical info - Cartridge .CAR files

The emulator supports cartridge ROM images. These images are raw dumps of an actual cartridge ROM. The load address is assumed to be $C000 and the length is assumed to be the actual file length with a maximum length of $3F00.

Because PC-DOS filenames are not very descriptive and a cartridge may contain hardware in addition to the ROM there needed to be a way to maintain this information easily and without having to modify the actual ROM image. To do this the emulator creates and maintains .CAR files. These files contain important information about a cartridge. This file is created when a cartridge ROM is first loaded and most of its information can be changed by the user.

Below is the actual file structure. Most of the items can be changed within the emulator on the Multi-Pak screen. The rest should never need to be changed but can be by using a hex file editor the file layout below .

All the fields in the .CAR file are user modifiable within the emulator except bytes 4-6.
The proper hardware option field is automatically updated when the user enables a hardware option.

Return to contents: 

Technical Info - Emulator memory map:

The Color Computer emulator memory map is as follows:

The Color Computer emulator support an enhanced memory map as follows:

Return to contents: