-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathcocotech.htm
1486 lines (1358 loc) · 54.3 KB
/
cocotech.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author" content="David Keil">
<meta name="GENERATOR" content="Microsoft FrontPage 2.0">
<title>Color Computer Emulator v1.00 Documentation (Technical)</title>
</head>
<body>
<p><a name="Technical"></a><font size="5"><b>Technical Info:</b></font>
</p>
<p>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. </p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr align="left">
<p><a name="Technical-DMK-disks"></a><font size="5"><b>Technical
info - DMK type virtual disks:</b></font> </p>
<p>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. </p>
<p>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. </p>
<p><font size="4">Disk header:</font> </p>
<p>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. </p>
<table border="1" width="100%" cols="2">
<tr>
<td width="15%">Byte 0</td>
<td width="85%">If this byte is set to FFH the disk is
`write protected', 00H allows writing.</td>
</tr>
<tr>
<td width="15%">Byte 1</td>
<td width="85%">Number 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. <p>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)</p>
</td>
</tr>
<tr>
<td width="15%">Byte 2 & 3</td>
<td width="85%">This 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. <p>WARNING: Bytes are entered in reverse
order (ex. 2940H would be entered, byte 2=40, byte
3=29). <br>
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.</p>
</td>
</tr>
<tr>
<td width="15%">Byte 4</td>
<td width="85%">Virtual disk option flags. <p>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. </p>
<p>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. </p>
<p>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. </p>
<p>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. </p>
<p>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.</p>
</td>
</tr>
<tr>
<td width="15%">Byte 5-B</td>
<td width="85%">reserved for future options</td>
</tr>
<tr>
<td width="15%">Byte C-F</td>
<td width="85%">Must be zero if virtual disk is in
emulator's native format. <p>Must be 12345678h if
virtual disk is a REAL disk specification file used to
access REAL COCO floppies in compatible PC drives.</p>
</td>
</tr>
<tr>
<td width="15%">Track Header</td>
<td width="85%">Each 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. <p>Note: Modification
within MSDOS could however be done to emulate a protected
disk in the TRS-80 & COCO emulators.</p>
</td>
</tr>
</table>
<p><font color="#000000" size="4">Track header:</font> </p>
<p>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. </p>
<p>These IDAM pointers MUST adhere to the following rules. </p>
<ul>
<li>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.</li>
<li>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.</li>
<li>The IDAM offsets MUST be in ascending order with no
unused or bad pointers.</li>
<li>If all the entries are not used the header is terminated
with a 0000h entry. Unused entries must also be zero
filled..</li>
<li>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.</li>
<li>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.</li>
<li>The pointer bytes are stored in reverse order (LSB/MSB).</li>
</ul>
<p>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. </p>
<p><font size="4">Track data:</font> </p>
<p>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. </p>
<p>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". </p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr align="left">
<p><a name="Technical-JV1-disks"></a><font size="5"><b>Technical
info - JV1/JV3 type virtual disks:</b></font> </p>
<p>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. </p>
<p>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. </p>
<p>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. </p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr align="left">
<p><a name="Technical-REAL-disks"></a><font size="5"><b>Technical
info - REAL COCO floppy disks:</b></font> </p>
<p>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. </p>
<p>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). </p>
<p>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. </p>
<table border="1" width="100%" cols="2">
<tr>
<td width="20%">FDD0_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC A: 360k
(DD) drive.</td>
</tr>
<tr>
<td width="20%">FDD1_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC B: 360k
(DD) drive</td>
</tr>
<tr>
<td width="20%">FHD0_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC A: 1.2meg
(HD) drive. (double steps head)</td>
</tr>
<tr>
<td width="20%">FHD1_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC B: 1.2meg
(HD) drive. (double steps head)</td>
</tr>
<tr>
<td width="20%">FHD0_720.DSK</td>
<td width="80%">Reads 80 track disks on a PC A: 1.2meg
(HD) drive.</td>
</tr>
<tr>
<td width="20%">FHD1_720.DSK</td>
<td width="80%">Reads 80 track disks on a PC B: 1.2meg
(HD) drive.</td>
</tr>
<tr>
<td width="20%">F350_720.DSK</td>
<td width="80%">Reads 80 track 3.5" disks on a PC A:
1.44meg (HD) drive.</td>
</tr>
<tr>
<td width="20%">F351_720.DSK</td>
<td width="80%">Reads 80 track 3.5" disks on a PC B:
1.44meg (HD) drive.</td>
</tr>
</table>
<p>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. </p>
<table border="1" width="100%" cols="2">
<tr>
<td width="20%">VDD0_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC A: 360k
(DD) drive.</td>
</tr>
<tr>
<td width="20%">VDD1_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC B: 360k
(DD) drive</td>
</tr>
<tr>
<td width="20%">VHD0_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC A: 1.2meg
(HD) drive. (double steps head)</td>
</tr>
<tr>
<td width="20%">VHD1_360.DSK</td>
<td width="80%">Reads 35/40 track disks on a PC B: 1.2meg
(HD) drive. (double steps head)</td>
</tr>
<tr>
<td width="20%">VHD0_720.DSK</td>
<td width="80%">Reads 80 track disks on a PC A: 1.2meg
(HD) drive.</td>
</tr>
<tr>
<td width="20%">VHD1_720.DSK</td>
<td width="80%">Reads 80 track disks on a PC B: 1.2meg
(HD) drive.</td>
</tr>
<tr>
<td width="20%">V350_720.DSK</td>
<td width="80%">Reads 80 track 3.5" disks on a PC A:
1.44meg (HD) drive.</td>
</tr>
<tr>
<td width="20%">V351_720.DSK</td>
<td width="80%">Reads 80 track 3.5" disks on a PC B:
1.44meg (HD) drive.</td>
</tr>
</table>
<p>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. </p>
<p>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). </p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr>
<p><a name="Technical-HDV-disk"></a><font size="5"><b>Technical
info - Virtual hard disks:</b></font> </p>
<p>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.</p>
<p>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.</p>
<p>The existing HDV format has been extended to support 1024
cylinder hard drives using the WD1010 hard drive controller
emulation.</p>
<p><font size="4">Disk header:</font> </p>
<p>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. </p>
<div align="center"><center>
<table border="1" width="100%">
<tr>
<td width="15%">Byte 0 & 1</td>
<td width="85%">Identifier 56h & CBh</td>
</tr>
<tr>
<td>Byte 2</td>
<td>Version: set to 11h when file created (version 1.1)</td>
</tr>
<tr>
<td>Byte 3</td>
<td>Checksum of bytes 0-31 (excepting byte 3) XORed with
4Ch</td>
</tr>
<tr>
<td>Byte 4</td>
<td>Number of 256 byte blocks in header: should be 1<br>
(anything other than 1 is not supported by this emulator)</td>
</tr>
<tr>
<td>Byte 5</td>
<td>-unused- Currently set to 4 for compatibility</td>
</tr>
<tr>
<td>Byte 6</td>
<td>Media type: 0 for hard disk</td>
</tr>
<tr>
<td>Byte 7</td>
<td>Bit 7 set if hard disk is write protected, all other
bits -unused-</td>
</tr>
<tr>
<td>Byte 8 & 9</td>
<td>-unused-</td>
</tr>
<tr>
<td>Byte 10</td>
<td>FFh = created with this emulator</td>
</tr>
<tr>
<td>Byte 11</td>
<td>-unused- (DOS type)</td>
</tr>
<tr>
<td>Byte 12</td>
<td>Creation month</td>
</tr>
<tr>
<td>Byte 13</td>
<td>Creation day</td>
</tr>
<tr>
<td>Byte 14</td>
<td>Creation year (offset from 1900)</td>
</tr>
<tr>
<td>Byte 15-26</td>
<td>-unused-</td>
</tr>
<tr>
<td>Byte 27</td>
<td>If 'byte 10' = FFh then bits 0-1 contains high bits
of cylinder count (max value 1024)<br>
else -unused-</td>
</tr>
<tr>
<td>Byte 28</td>
<td>If 'byte 10' = FFh then contains low byte of cylinder
count<br>
else contains total number of cylinders on disk </td>
</tr>
<tr>
<td>Byte 29</td>
<td>Number of sectors per cylinder<br>
This value must be divisible by 32. A value of 00h = 256
sectors</td>
</tr>
<tr>
<td>Byte 30</td>
<td>-unused- but is set to 'byte 29' divided by 16 when
file created (granules per cylinder)</td>
</tr>
<tr>
<td>Byte 31</td>
<td>-unused- but is set to 1 when file created (directory
cylinder)</td>
</tr>
<tr>
<td>Byte 32-63</td>
<td>Volume label, set to TRS80 or COCO when file is
created (31 bytes terminated by 00h)</td>
</tr>
<tr>
<td>Byte 64-71</td>
<td>-unused- (Creation filename)</td>
</tr>
<tr>
<td>Byte 72-255</td>
<td>-unused-</td>
</tr>
</table>
</center></div>
<p><font color="#FF0000"><strong>WARNING: </strong>Once hard disk
support is added to the COCO emulator this file layout may have
minor changes.</font></p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr align="left">
<p><a name="Technical-MC6809"></a><font size="5"><b>Technical
Info - Enhanced MC6809 instructions</b></font></p>
<p><font size="3">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.</font></p>
<p><font size="3"><strong>NOTE: </strong>These instructions are
only available in the emulators.</font></p>
<p>The following links contain a list of the enhanced
instructions and documentation for each instruction.</p>
<p><a href="../../~dmkeil/coco/coco6809.htm">Enhanced Instruction Documentation</a>
(on-line)</p>
<p><a href="../../~dmkeil/coco/coco6809.doc">Enhanced Instruction Documentation</a>
(Microsoft Word 96k)</p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr>
<p><a name="Technical-I/O"></a><font size="5"><b>Technical Info -
Memory mapped PC I/O commands</b></font></p>
<p><font size="3">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.</font></p>
<p><font size="3">The memory mapped I/O commands allow access to
the I/O functions between $10 and $1F as defined in the </font><a
href="../../~dmkeil/coco/coco6809.htm">Enhanced Instruction Documentation</a>.
Access to the other enhanced instructions 00-$0F are also
possible but are less useful in BASIC programs.</p>
<p>These memory mapped I/O commands also allow access to the PC's
hardware clock, PC's I/O ports & PC mouse.</p>
<p>These memory mapped functions use the MC6809 memory address
$FFE0-FFEF:</p>
<hr width="50%">
<p>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.</p>
<p>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.</p>
<p>For example to write the 16bit value of $1234 to $FFE0 do the
following:</p>
<p>POKE &HFFEF, 3: REM TO INSURE THE HIGH 8BITS OF DATA SET 3
ARE SELECTED<br>
POKE &HFFE0,&H12<br>
POKE &HFFE0,&H34</p>
<p>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. </p>
<p>For example executing the following:</p>
<p>POKE &HFFEF, 3: REM TO INSURE THE HIGH 8BITS OF DATA SET 3
ARE SELECTED<br>
PRINT PEEK(HFFE0)<br>
POKE &HFFE1,0</p>
<p>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.</p>
<hr width="50%">
<p>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.</p>
<p>Reading from memory address $FFEE will return the status of
the last enhanced instruction executed.</p>
<p>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.</p>
<p>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.</p>
<hr width="50%">
<p>Some program listings of BASIC programs are available as
examples of using the memory mapped I/O commands:</p>
<p><a href="../../~dmkeil/coco/cocobas.htm">BASIC Examples</a></p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr>
<p><a name="Technical-mouse"></a><font size="5"><b>Technical info
- Memory mapped PC mouse functions:</b></font> </p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p><strong>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.</strong></p>
<p>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.</p>
<p>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.</p>
<p>See the BASIC programming examples, PGM4 for an example of how
to use the PC mouse I/O function.</p>
<p><a href="../../~dmkeil/coco/cocobas.htm">BASIC Examples</a></p>
<p><a href="../../~dmkeil/coco/cocodoc.htm#Contents">Return to contents:</a> </p>
<hr>
<p><a name="Technical-keymaps"></a><font size="5"><b>Technical
info - Keyboard maps:</b></font> </p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<table border="2" cellpadding="4" cellspacing="0"
bordercolor="#000000">
<tr>
<td><img src="../../~dmkeil/images/pckey.gif" width="868"
height="238"></td>
</tr>
</table>
<p>As said before each scancode points to a two byte pair. The
second byte is the entry type, it has the following values:</p>
<div align="left">
<table border="2">
<tr>
<td align="center" width="5%">bit 0</td>
<td>If clear then this is an unshifted COCO key<br>
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.</td>
</tr>
<tr>
<td align="center">bit 0</td>
<td>If set then this is a shifted COCO key<br>
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.<br>
A shift will also be stored in the matrix.</td>
</tr>
<tr>
<td align="center">bit 1</td>
<td>-reserved-</td>
</tr>
<tr>
<td align="center">bit 2</td>
<td>If 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:<p>000
- joystick up<br>
001 - joystick down<br>
010 - joystick left<br>
011 - joystick right<br>
100 - right joystick button<br>
101 - left joystick button<br>
110 - extra button<br>
111 - extra button</p>
</td>
</tr>
<tr>
<td align="center" colspan="2"><font color="#FF0000"><strong>The
above bits are valid only if bit 7 is clear</strong></font></td>
</tr>
<tr>
<td align="center" width="5%">128</td>
<td>No function<br>
Pushing this key does nothing in the emulator</td>
</tr>
<tr>
<td align="center" width="5%">129</td>
<td>Command function<br>
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.</td>
</tr>
<tr>
<td align="center" width="5%">130</td>
<td>Shift Key<br>
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.</td>
</tr>
</table>
</div>
<p>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.</p>
<p><img src="../../~dmkeil/coco/images/cocokey1.gif" width="511" height="129"></p>
<p>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.</p>
<p>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 "@").</p>
<p>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.</p>
<p><img src="../../~dmkeil/coco/images/cocokey2.gif" width="511" height="129"></p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>I hope this documentation will give users the information
needed to create custom keyboard layouts.</p>
<p><a href="file:///C:/My%20Documents/trsdoc.htm#Contents">Return
to contents:</a> </p>
<hr align="left">
<p><a name="Technical-CAR file"></a><font size="5"><b>Technical
info - Cartridge .CAR files</b></font></p>
<p><font size="3">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.</font></p>
<p><font size="3">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.</font></p>
<p><font size="3">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 .</font></p>
<div align="center"><center>
<table border="1" width="100%">
<tr>
<td width="15%">Byte 0-3</td>
<td width="100%">Identifier 'CART' </td>
</tr>
<tr>
<td width="15%">Byte 4</td>
<td width="100%">Write protect:<br>
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.<br>
If this byte is non-zero changes made to a loaded
cartridge's options are not saved.</td>
</tr>
<tr>
<td width="15%">Byte 5 & 6</td>
<td width="100%">Length of ROM image:<br>
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.<br>
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.<br>
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.<p>WARNING: Bytes are entered in reverse order
(ex. $2000 would be entered, byte 5=00, byte 6=20).</p>
</td>
</tr>
<tr>
<td width="15%">Byte 7</td>
<td width="100%">Cartridge label color:<br>
Contains a value between 0 & 15.</td>
</tr>
<tr>
<td width="15%">Byte 8</td>
<td width="100%">Cartridge label text color:<br>
Contains a value between 0 & 15.</td>
</tr>
<tr>
<td width="15%">Byte 9</td>
<td width="100%">Hardware options addressed using SCS*
(spare select signal)<br>
Bit 0: Floppy Disk Controller<br>