From cbd837123ee7c6dc874e16d5a776b1a43e0d8fe1 Mon Sep 17 00:00:00 2001 From: Natalia Portillo Date: Wed, 25 Mar 2015 02:30:33 +0000 Subject: [PATCH] Added information for Tandy CoCo disk images --- cocotech.htm | 1486 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1486 insertions(+) create mode 100644 cocotech.htm diff --git a/cocotech.htm b/cocotech.htm new file mode 100644 index 0000000..e620ba5 --- /dev/null +++ b/cocotech.htm @@ -0,0 +1,1486 @@ + + + + + + + +Color Computer Emulator v1.00 Documentation (Technical) + + + + +

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. 

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Byte 0If this byte is set to FFH the disk is + `write protected', 00H allows writing.
Byte 1Number of tracks on virtual disk. Since + tracks start at 0 this value will be one greater than the + highest track written to the disk. So a disk with 35 + tracks will have a value of 35 (23H) in this field after + formatting while the highest track written would be 34. + This field is updated after a track is formatted if the + track formatted is greater than or equal to the current + number of tracks. Re-formatting a disk with fewer tracks + will NOT reduce the number of tracks on the virtual disk. + Once a virtual disk has allocated space for a track it + will NEVER release it. Formatting a virtual disk with 80 + tracks then re-formatting it with 35 tracks would waste + space just like formatting only 35 tracks on an 80 track + drive. The emulator and COCO operating systems don't + care. To re-format a virtual disk with fewer tracks use + the re-create the virtual disk first, then re-format to + save space. 

Note: This field should NEVER be + modified. Changing this number will cause COCO operating + system disk errors. (Like reading an 80 track disk in a + 35 track drive)

+
Byte 2 & 3This is the track length for the virtual + disk. By default the value is 1900H, 80H bytes more than + the actual track length, this gives a track length of + 6272 bytes. A real double density track length is aprox. + 6250 bytes. This is the default value when a virtual disk + is created. Values for other disk and format types are + 0CC0H for single density 5.25" floppies, 14E0H for + single density 8" floppies and 2940H for double + density 8" floppies. The max value is 2940H. For + normal formatting of disks the values of 1900H and 2940H + for 5.25" and 8" are used. The emulator will + write two bytes and read every second byte when  in + single density to maintain proper sector spacing, + allowing mixed density disks. Setting the track length + must be done before a virtual disk is formatted or the + disk will have to be re-formatted and since the space for + the disk has already been allocated no space will be + saved. 

WARNING: Bytes are entered in reverse + order (ex. 2940H would be entered, byte 2=40, byte + 3=29). 
+ Note: No modification of the track length is necessary, + doing so only saves space and is not necessary to normal + operation. The values for all normal 5.25" and + 8" disks are set when the virtual disk is created. + DON'T modify the track length unless you understand these + instructions completely. Nothing in the PC world can be + messed up by improper modification but any other virtual + disk mounted in the emulator with an improperly modified + disk could have their data scrambled.

+
Byte 4Virtual disk option flags. 

Bit 4 + of this byte, if set, means this is a single sided ONLY + disk. This bit is set if the user selects single sided + during disk creation and should not require modification. + This flag is used only to save PC hard disk space and is + never required. 

+

Bit 6 of this byte, if set, means this disk is to be + single density size and the emulator will access one byte + instead of two when doing I/O in single density. Double + density can still be written to a single density disk but + with half the track length only 10 256 byte sectors can + be written in either density. Mixed density is also + possible but sector timing may be off so protected disks + may not work, a maximum of 10 256 byte sectors of mixed + density can be written to a single density disk. A + program like "Spook House" which has a mixed + density track 0 with 1 SD sector and 1 DD sector and the + rest of the disk consisting of 10 SD sectors/track will + work with this flag set and save half the PC hard disk + space. The protected disk "Super Utility + 3.0" + however has 6 SD and 6 DD sectors/track for a total of 12 + 256 byte sectors/track. This disk cannot be single + density. 

+

This bit is set if the user selects single density + during disk creation and should not require modification. + This flag is used only to save PC hard disk space and is + never required. 

+

Bit 7 of this byte, if set, means density is to be + ignored when accessing this disk. The disk MUST be + formatted in double density but the emulator will then + read and write the sectors in either density. The + emulator will access one byte instead of two when doing + I/O in single density. 

+

This flag was an early way to support mixed density + disks it is no longer needed for this purpose. It is now + used for compatibility with old virtual disks created + without the double byte now used when in single density. + This bit can be set manually in a hex editor to access + old virtual disks written in single density.

+
Byte 5-Breserved for future options
Byte C-FMust be zero if virtual disk is in + emulator's native format. 

Must be 12345678h if + virtual disk is a REAL disk specification file used to + access REAL COCO floppies in compatible PC drives.

+
Track HeaderEach track has a 128 (80H) byte header + which contains an offset to each IDAM in the track. This + is created during format and should NEVER require + modification. The actual track data follows this header + and can be viewed with a hex editor showing the raw data + on the track. Modification should not be done as each + IDAM and sector has a CRC, this is just like a real disk, + and modifying the sector data without updating the CRC + value will cause CRC errors when accessing the virtual + disk within the emulator. 

Note: Modification + within MSDOS could however be done to emulate a protected + disk in the TRS-80 & COCO emulators.

+
+ +

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 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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FDD0_360.DSKReads 35/40 track disks on a PC A: 360k + (DD) drive.
FDD1_360.DSKReads 35/40 track disks on a PC B: 360k + (DD) drive
FHD0_360.DSKReads 35/40 track disks on a PC A: 1.2meg + (HD) drive. (double steps head)
FHD1_360.DSKReads 35/40 track disks on a PC B: 1.2meg + (HD) drive. (double steps head)
FHD0_720.DSKReads 80 track disks on a PC A: 1.2meg + (HD) drive.
FHD1_720.DSKReads 80 track disks on a PC B: 1.2meg + (HD) drive.
F350_720.DSKReads 80 track 3.5" disks on a PC A: + 1.44meg (HD) drive.
F351_720.DSKReads 80 track 3.5" disks on a PC B: + 1.44meg (HD) drive.
+ +

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VDD0_360.DSKReads 35/40 track disks on a PC A: 360k + (DD) drive.
VDD1_360.DSKReads 35/40 track disks on a PC B: 360k + (DD) drive
VHD0_360.DSKReads 35/40 track disks on a PC A: 1.2meg + (HD) drive. (double steps head)
VHD1_360.DSKReads 35/40 track disks on a PC B: 1.2meg + (HD) drive. (double steps head)
VHD0_720.DSKReads 80 track disks on a PC A: 1.2meg + (HD) drive.
VHD1_720.DSKReads 80 track disks on a PC B: 1.2meg + (HD) drive.
V350_720.DSKReads 80 track 3.5" disks on a PC A: + 1.44meg (HD) drive.
V351_720.DSKReads 80 track 3.5" disks on a PC B: + 1.44meg (HD) drive.
+ +

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. 

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Byte 0 & 1Identifier 56h & CBh
Byte 2Version: set to 11h when file created (version 1.1)
Byte 3Checksum of bytes 0-31 (excepting byte 3) XORed with + 4Ch
Byte 4Number of 256 byte blocks in header: should be 1
+ (anything other than 1 is not supported by this emulator)
Byte 5-unused- Currently set to 4 for compatibility
Byte 6Media type: 0 for hard disk
Byte 7Bit 7 set if hard disk is write protected, all other + bits -unused-
Byte 8 & 9-unused-
Byte 10FFh = created with this emulator
Byte 11-unused- (DOS type)
Byte 12Creation month
Byte 13Creation day
Byte 14Creation year (offset from 1900)
Byte 15-26-unused-
Byte 27If 'byte 10' = FFh then bits 0-1 contains high bits + of cylinder count (max value 1024)
+ else -unused-
Byte 28If 'byte 10' = FFh then contains low byte of cylinder + count
+ else contains total number of cylinders on disk
Byte 29Number of sectors per cylinder
+ This value must be divisible by 32. A value of 00h = 256 + sectors
Byte 30-unused- but is set to 'byte 29' divided by 16 when + file created (granules per cylinder)
Byte 31-unused- but is set to 1 when file created (directory + cylinder)
Byte 32-63Volume label, set to TRS80 or COCO when file is + created (31 bytes terminated by 00h)
Byte 64-71-unused- (Creation filename)
Byte 72-255-unused-
+
+ +

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:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
bit 0If clear then this is an unshifted COCO key
+ When this key is pushed a value corresponding to the + first byte of this map entry will be stored in the COCO + keyboard memory matrix.
bit 0If set then this is a shifted COCO key
+ When this key is pushed a value corresponding to the + first byte of this map entry will be stored in the COCO + keyboard memory matrix.
+ A shift will also be stored in the matrix.
bit 1-reserved-
bit 2If bit 2 is set then this key is also used as a + joystick emulator key. Bits 4-6 is the joystick value + that the key will change. Values for bits 4-6 are:

000 + - joystick up
+ 001 - joystick down
+ 010 - joystick left
+ 011 - joystick right
+ 100 - right joystick button
+ 101 - left joystick button
+ 110 - extra button
+ 111 - extra button

+
The + above bits are valid only if bit 7 is clear
128No function
+ Pushing this key does nothing in the emulator
129Command function
+ These keys execute emulator command functions like + rebooting the emulator (F10). These map entries should + not be modified. Incorrect entries to this type of entry + can result in emulator functions not working, emulator + lockups and system crashes.
130Shift Key
+ Whenever this key is pushed and held the emulator will + use the second half of the keyboard map. The first byte + of this type of entry contains the type of shift key. For + the COCO this value should always be 1.
+
+ +

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 .

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Byte 0-3Identifier 'CART'
Byte 4Write protect:
+ If this byte is zero, the emulator automatically updates + any changes to the .CAR file when a cartridge is removed + or upon exiting the emulator.
+ If this byte is non-zero changes made to a loaded + cartridge's options are not saved.
Byte 5 & 6Length of ROM image:
+ This value is created when a cartridge ROM image is + loaded for the first time. It contains the actual length + of the image to a maximum of $3F00.
+ If this value is modified and is smaller then the actual + ROM image length only the number of bytes in this field + will be loaded.
+ If the value is modified to a value larger than the + actual ROM image length this field will be changed to the + actual ROM image length the next time the cartridge is + loaded.

WARNING: Bytes are entered in reverse order + (ex. $2000 would be entered, byte 5=00, byte 6=20).

+
Byte 7Cartridge label color:
+ Contains a value between 0 & 15.
Byte 8Cartridge label text color:
+ Contains a value between 0 & 15.
Byte 9Hardware options addressed using SCS* + (spare select signal)
+ Bit 0:    Floppy Disk Controller
+ Bit 1-7: reserved for additional hardware
Byte 10Hardware options addresses using CTS* + (cartridge select signal)
+ Bit 0-6: reserved for addition hardware
+ Bit 7:    cartridge interrupt signal + (enabled if set)

By default the cartridge interrupt + signal is set enabled when the .CAR file is initalized + for a new ROM image.

+
Byte 11Hardware options addressed whenever + cartridge is inserted in Multi-Pak Interface:
+ Bit 0:    Orchestra-90 Music + Synthesizer
+ Bit 1-7: reserved for additional hardware
Byte 12reserved
Byte 14-37Cartridge description #1 (zero + terminated)
byte 38-61Cartridge description #2 (zero + terminated)
+
+ +

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:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Memory rangeReadWrite
FF00PIA #0 data port APIA #0 data port A
FF01PIA #0 control port APIA #0 control port A
FF02PIA #0 data port BPIA #0 data port B
FF03PIA #0 control port BPIA #0 control port B
FF04-FF1Fmirrors of FF00-FF03mirrors of FF00-FF03
FF20PIA #1 data port APIA #1 data port A
FF21PIA #1 control port APIA #1 control port A
FF22PIA #1 data port BPIA #1 data port B
FF23PIA #1 control port BPIA #1 control port B
FF24-FF3Fmirrors of FF20-FF23mirrors of FF20-FF23
FF40-FF47Disk select register-unused-
FF48FDC status registerFDC command register
FF49FDC track registerFDC track register
FF4AFDC sector registerFDC sector register
FF4BFDC data registerFDC data register
FF40-FF5FSCS - spare select signalSCS - spare select signal

Used by bank switched ROM + cartridges
+ Bit 0 = A14
+ Bit 1 = A15
+ Bit 2 = A16
+ Bit 3 = A17

+
FF68 & FF6CReceiver data registerTransmit data register
FF69 & FF6DSoft resetStatus register
FF6A & FF6ECommand registerCommand register
FF6B & FF6FControl registerControl register
Deluxe + RS-232 Program Pak $FF68-$FF6B
+ Direct Connect Modem Pak $FF6C-$FF6F
FF7A-unused-Orcherstra-90 (left channel)
FF7B-unused-Orchestra-90 (right channel)
FF7FMulti-Pak programming register
+ Get active slots

bits 0-1: number of active SCS slot + (FDC)
+ bits 4-5: number of active CTS slot (ROM)
+ bits 2,3,6,7: all set means value given is select switch + setting

+ 		Multi-Pak programming register
+ Set active slots

bits 0-1: number of active SCS slot + (FDC)
+ bits 4-5: number of active CTS slot (ROM)
+

+
FFC0-FFC5-unused-Graphics mode V0-V2
FFC6-FFD3-unused-Video page offset
FFD8-FFD9-unused-CPU speed (.895mhz / 1.78mhz)
FFDE-FFDF-unused-ROM enable/disable
FFF0-FFF1reserved-unused-
FFF2-FFF3SWI3 vector-unused-
FFF4-FFF5SWI2 vector-unused-
FFF6-FFF7FIRQ vector-unused-
FFF8-FFF9IRQ vector-unused-
FFFA-FFFBSWI vector-unused-
FFFC-FFFDNMI vector-unused-
FFFE-FFFFReset vector-unused-
All + vectors are mapped to Color BASIC ROM address $BBF2-$BBFF
+ +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Memory rangeReadWrite
FFE0-FFE7up to 16 sets of 8bit or 16bit I/O dataup to 16 sets of 8bit or 16bit I/O data
FFE8CPU register A used by enhanced + instructionsCPU register A used by enhanced + instructions
FFE9CPU register B used by enhanced + instructions
+ -or-
+ CPU register CC returned by enhanced instructions		CPU register B used by enhanced + instructions
FFEA-FFED-unused--unused-
FFEEEnhanced instruction status registerEnhanced instruction command register
+ Valid command are $00-$1F
FFEFBits 0-3: equal
+ current data set for $FFE0-$FFE7

Bit 4: if set means
+ $FFE0-$FFE7 are 16bit values

+

Bit 5-7: -unused-

+ 		Bits 0-3: set the current data set for $FFE0-FFE7

Bit + 4-7: -unused-

+
Anytime + $FFEF is accessed the high/low 8bit toggle for 16bit + values is set to the high 8 bits.
Memory + address $FFEF equal $00
FFE0-FFE7Work area used by enhanced instructionsWork area used by enhanced instructions
Memory + address $FFEF equal $01
FFE0seconds in BCD format-unused-
Reading + this address loads $FFE0-$FFE6 with the PC's system date + and time.
FFE1minutes in BCD format-unused-
FFE2hours in BCD format-unused-
FFE3year in BCD format-unused-
FFE4day in BCD format-unused-
FFE5month in BCD format-unused-
FFE6century in BCD format (19 or 20)-unused-
Memory + address $FFEF equal $02
FFE0-FFE7Read PC portWrite PC port
The + PC port read or written is defined by the 16bit values + stored in $FFE0-$FFE7 when $FFEF equal $03
Memory + address $FFEF equal $03
FFE0-FFE716bit PC port address16bit PC port address
Memory + address $FFEF equal $04
FFE0read PC mouse and load buttons and current X & Y + coordinates

bit 0: left button was pushed
+ bit 1: right button was pushed
+ bit 2: middle button was pushed

+

bit 4: left button is pushed
+ bit 5: right button is pushed
+ bit 6: middle button is pushed

+ 		set mouse buttons

bit 0: set/clear + left button was pushed
+ bit 1: set/clear right button was pushed
+ bit 2: set/clear middle button was pushed

+
Reading + this address load $FFE1 & FFE2 with the current mouse + X & Y coordinates.
+ These coordinates will always be greater than or equal to + the minimum and less than or equal to the maximum.
FFE1get mouse current X coordinateset mouse current X coordinate
FFE2get mouse current Y coordinateset mouse current Y coordinate
FFE3get mouse min X coordinateset mouse min X coordinate
FFE4get mouse min Y coordinateset mouse min Y coordinate
FFE5get mouse max X coordinateset mouse max X coordinate
FFE6get mouse max Y coordinateset mouse max Y coordinate
Make + sure that the minimum value is less than the maximum + value or the X & Y coordinates will be unknown.
FFE7get mouse sensitivity

bits 0-3: X axis (0-15)
+ bits 4-7: Y axis (0-15)

+ 		set mouse sensitivity

bits 0-3: X axis (0-15)
+ bits 4-7: Y axis (0-15)

+
All + X & Y coordinate values are 16bit. The mouse buttons + and sensitivity are 8bit values mirrored into 16 bits.
+
+ WARNING
+ Memory mapped mouse functions are disabled when COCO + joystick emulation is set to PC mouse.

+ Memory address $FFEF equal + $05 - $0F
+ -undefined-
+
+ +

Return to contents:

+ +