forked from thierer/sd2iec
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME
1121 lines (937 loc) · 50.8 KB
/
README
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
sd2iec - a controller/interface adapting storage devices to the CBM serial bus
Copyright (C) 2007-2022 Ingo Korb <ingo@akana.de>
Parts based on code from others, see comments in main.c for details.
JiffyDos send based on code by M.Kiesel
Fat LFN support and lots of other ideas+code by Jim Brain
Final Cartridge III fastloader support by Thomas Giesel
IEEE488 support by Nils Eilers
Free software under GPL version 2 ONLY, see comments in main.c and
COPYING for details.
# Note #
If you found this file on Github, you found an unofficial clone of the
original repository. The original repository is available on
[https://www.sd2iec.de](https://www.sd2iec.de)
FIXME:This file still needs to be expanded. A lot.
FIXME: sprinkle mentions of IEEE488 where appropiate
Deprecation notices
===================
The following feature(s) will be removed in the next release:
- M2I support
M2I support has been redundant since the introduction of transparent
P00 support. To continue to use your M2I-format software, convert
your files to P00 format (e.g. with m2itopc64.c) and set your device
to extension mode 2 (XE2).
Introduction:
=============
sd2iec is firmware, used in hardware designs like MMC2IEC, SD2IEC, or uIEC,
that allows the Commodore serial bus to access removable storage devices
(MMC, SD, CF) - think of it as a 1541 with a modern storage medium instead
of disks. The project was inspired by (and uses a few bits of code from)
MMC2IEC[1] by Lars Pontoppidan and once ran on the same hardware before it
grew too big for the ATmega32 used there.
Currently, the firmware provide good DOS and file-level compatibility with CBM
drives, but much work remains. Unless specifically noted, anything that tries
to execute code on the 1541 will not work, this includes every software
fastloader.
[1] Homepage: http://pontoppidan.info/lars/index.php?proj=mmc2iec
Please note: Whenever this file talks about "D64 images" the text applies to
all Dxx image types, i.e. D64/D71/D81/DNP unless specifically noted.
If you are the author of a program that needs to detect sd2iec for
some reason, DO NOT use M-R for this purpose. Use the UI command
instead and check the message you get for "sd2iec" and "uiec" instead.
Supported commands:
===================
- General notes:
Any command not listed below is currently not supported.
- Directory filters:
To show only directories, both =B (CMD-compatible) and =D can be used.
On a real Commodore drive D matches everything.
To include hidden files in the directory, use *=H - on a 1541 this doesn't
do anything. sd2iec marks hidden files with an H after the lock mark,
i.e. "PRG<H" or "PRG H".
CMD-style "short" and "long" directory listings with timestamps are supported
("$=T"), including timestamp filters. Please read a CMD manual for the syntax
until this file is updated.
- Partition directory:
The CMD-style partition directory ($=P) is supported, including filters
($=P:S*). All partitions are listed with type "FAT", although this could
change to "NAT" later for compatibility.
- A:
Sets attributes on a file.
A:=foo removes all attributes
A:R=foo sets attribute Readonly, removes any other
A:H=foo sets attribute hidden, removes any other
- L/EL/EU/XL/XU:
Sets resp. clears reqad only flag
L:foo toggles flag on a single file
EL:foo sets flag on files, EL:$ locks whole image
EU:foo clears flag on files, EU:$ unlocks whole image
- EH
Toggles hidden flag
EH/:foo toggles flag on a single file - a Path must be present
- EH, D, R-H, XH: Change / Rename Header
R-H:foo chanegs header to foo
D:foo,ba changes header to 'foo' and id to 'ba' - colomn must follow the 'D' immediately.
EH:foo,ba changes header to 'foo' and id to 'ba' - a path must NOT be given.
XH:foo,ba changes header to 'foo' and id to 'ba'
- CD/MD/RD:
Subdirectory access is compatible to the syntax used by the CMD drives,
although drive/partition numbers are completely ignored.
Quick syntax overview:
CD:_ changes into the parent dir (_ is the left arrow on the C64)
CD_ dito
CD:foo changes into foo
CD/foo dito
CD//foo changes into \foo
CD/foo/:bar changes into foo\bar
CD/foo/bar dito
You can use wildcards anywhere in the path. To change into an M2I or D64
image the image file must be the last component in the path, either
after a slash or a colon character.
MD uses a syntax similiar to CD and will create the directory listed
after the colon (:) relative to any directory listed before it.
MD/foo/:bar creates bar in foo
MD//foo/:bar creates bar in \foo
RD can only remove subdirectories of the current directory.
RD:foo deletes foo
CD is also used to mount/unmount image files. Just change into them
as if they were a directory and use CD:_ (left arrow on the C64) to leave.
Please note that image files are detected by file extension and file size
and there is no reliable way to see if a file is a valid image file.
- CP, C<Shift-P>
This changes the current partition, see "Partitions" below for details.
- C:
File copy command, should be CMD compatible. The syntax is
C[partition][path]:targetname=[[partition][path]:]sourcename[,[[p][p]:]sourcename...]
You can use this command to copy multiple files into a single target
file in which case all source files will be appended into the target
file. Parsing restarts for every source file name which means that
every source name is assumed to be relative to the current directory.
You can use wildcards in the source names, but only the first
file matching will be copied.
Copying REL files should work, but isn't tested well. Mixing REL and
non-REL files in an append operation isn't supported.
- D
Direct sector access, this is a command group introduced by sd2iec.
Some Commodore drives use D for disk duplication between two drives
in the same unit, an attempt to use that command with sd2iec should
result in an error message.
D has three subcommands: DI (Info), DR (Read) and DW (Write).
Each of those commands requires a buffer to be opened (similiar
to U1/U2), but due to the larger sector size of the storage devices
used by sd2iec it needs to be a large buffer of size 2 (512 bytes)
or larger. The exception is the DI command with page set to 0,
its result will always fir into a standard 256 byte buffer.
If you try to use one of the commands with a buffer that is too
small a new error message is returned, "78,BUFFER TOO SMALL,00,00".
In the following paragraphs the secondary address that was used
to open the buffer is called "bufchan".
- DI
In BASIC notation the command format is
"DI"+chr$(bufchan)+chr$(device)+chr$(page)
"device" is the number of the physical device to be queried,
"page" the information page to be retrieved. Currently the
only page implemented is page 0 which will return the
following data structure:
1 byte : Number of valid bytes in this structure
This includes this byte and is meant to provide
backwards compatibility if this structure is extended
at a later time. New fields will always be added to
the end so old programs can still read the fields
they know about.
1 byte : Highest diskinfo page supported
Always 0 for now, will increase if more information
pages are added (planned: Complete ATA IDENTIFY
output for IDE and CSD for SD)
1 byte : Disk type
This field identifies the device type, currently
implemented values are:
0 IDE
2 SD
3 (reserved)
1 byte : Sector size divided by 256
This field holds the sector size of the storage device
divided by 256.
4 bytes: Number of sectors on the device
A little-endian (same byte order as the 6502) value
of the number of sectors on the storage device.
If there is ever a need to increase the reported
capacity beyond 2TB (for 512 byte sectors) this
field will return 0 and a 64-bit value will be added
to this diskinfo page.
If you want to determine if there is a device that responds
to a given number, read info page 0 for it. If there is no
device present that corresponds to the number you will see
a DRIVE NOT READY error on the error channel and the
"number of valid bytes" entry in the structure will be 0.
Do not assume that device numbers are stable between releases
and do not assume that they are continuous either. To scan
for all present devices you should query at least 0-7 for now,
but this limit may increase in later releases.
- DR/DW
In BASIC notation the command format would be
"DR"+chr$(bufchan)+chr$(device)
+chr$(sector AND 255)
+chr$((sector/256) AND 255)
+chr$((sector/65536) AND 255)
+chr$((sector/16777216) AND 255)
(or "DW" instead of "DR)
but this won't work on the C64 because AND does not accept
parameters larger than 32767. The principle should be clear
though, the last four bytes are a 32 bit sector number in
little-endian byte order.
DR reads the sector to the buffer, DW writes the contents
of the buffer to the sector. Both commands will update the
error channel if an error occurs, for DR the 20,READ ERROR
was chosen to represent read errors; for write problems
during DW it sets 25,WRITE ERROR for errors and 26,WRITE
PROTECT ON if the device is read-only.
- G-P
Get partition info, see CMD FD/HD manual for details. The reported
information is partially faked, feedback is welcome.
- P
Positioning doesn't just work for REL files but also for regular
files on a FAT partition. When used for regular files the format
is "P"+chr$(channel)+chr$(lo)+chr$(midlo)+chr$(midhi)+chr$(hi)
which will seek to the 0-based offset hi*2^24+midhi*65536+256*midlo+lo
in the file. If you send less than four bytes for the offset, the
missing bytes are assumed to be zero.
- N:
This command will be ignored for DNP images unless the current directory
is the root directory of the DNP image.
If an image is mounted, it will be formatted.
If the id is followed by a plus or minus sign, fast format is turned on
resp. off.
If no image is mounted and 1. the "name" part of the command includes a
known D64 file extension (.D64/.D41/.D71/.D81) and 2. no file with that
name exists, an image file in the respective format (.D41 is a synonym
for .D64) is created. The disk label is derived from the filename by
removing the extension. As this is a full format, it requires an id to
be present in the command string.
In case that the extension is .DNP, the is is treated as a three digit
value number of tracks and the image is created but not formatted.
If an image file with that name already exists, it is formatted, like
if it was mounted.
If the name doesn't end in a known D64 image extension, it defaults to
".D64". As a precaution and exception to the rules above, an existing
image will not be formatted if the filename results from adding the
default extension. In this case the command aborts with a "FILE EXISTS"
error instead.
Path specifiers are supported, so "N//SUBDIR:D64TEST.D64,XX" will
create the image in the directory "/SUBDIR".
- R
Renaming files should work the same as it does on CMD drives, although
the errors flagged for invalid characters in the name may differ.
- S:
Name matching is fully supported, directories are ignored.
Scratching of multiple files separated by , is also supported with no
limit to the number of files except for the maximum command line length
(usually 100 to 120 characters).
- T-R and T-W
If your hardware features RTC support the commands T-R (time read) and T-W
(time write) are available. If the RTC isn't present, both commands return
30,SYNTAX ERROR,00,00; if the RTC is present but not set correctly T-R will
return 31,SYNTAX ERROR,00,00.
Both commands expect a fourth character that specifies the time format
to be used. T-W expects that the new time follows that character
with no space or other characters inbetween. For the A, B and D
formats, the expected input format is exactly the same as returned
by T-R with the same format character; for the I format the day of
week is ignored and calculated based on the date instead.
The possible formats are:
- "A"SCII: "SUN. 01/20/08 01:23:45 PM"+CHR$(13)
The day-of-week string can be any of "SUN.", "MON.", "TUES", "WED.",
"THUR", "FRI.", "SAT.". The year field is modulo 100.
- "B"CD or "D"ecimal:
Both these formats use 9 bytes to specify the time. For BCD everything
is BCD-encoded, for Decimal the numbers are sent/parsed as-is.
Byte 0: Day of the week (0 for sunday)
1: Year (modulo 100 for BCD; -1900 for Decimal, i.e. 108 for 2008)
2: Month (1-based)
3: Day (1-based)
4: Hour (1-12)
5: Minute (0-59)
6: Second (0-59)
7: AM/PM-Flag (0 is AM, everything else is PM)
8: CHR$(13)
When the time is set a year less than 80 is interpreted as 20xx.
- "I"SO 8601 subset: "2008-01-20T13:23:45 SUN"+CHR$(13)
This format complies with ISO 8601 and adds a day of week
abbreviation using the same table as the A format, but omitting
the fourth character. When it is used with T-W, anything beyond
the seconds field is ignored and the day of week is calculated
based on the specified date. The year must always be specified
including the century if this format is used to set the time.
To save space, sd2iec only accepts this particular date/time
representation when setting the time with T-WI and no other ISo
8601-compliant representation.
- U0
Device address changing with "U0>"+chr$(new address) is supported,
other U0 commands are currently not implemented.
- U1/U2/B-R/B-W
Block reading and writing is fully supported while a D64 image is mounted.
- B-P
Supported, not checked against the original rom at all.
- UI+/UI-
Switching the slightly faster bus protocol for the VC20 on and off works,
it hasn't been tested much though.
- UI/UJ
Soft/Hard reset - UI just sets the "73,..." message on the error channel,
UJ closes all active buffers but doesn't reset the current directory,
mounted image, swap list or anything else.
- U<Shift-J>
Real hard reset - this command causes a restart of the AVR processor
(skipping the bootloader if installed). <Shift-J> is character code 202.
- X: Extended commands. If you use JiffyDOS, you can send them by using
@"X..." - without quotes you'll just receive an error.
- XEnum Sets the "file extension mode". This setting controls if
files on FAT are written with an x00 header and extension or not.
Possible values for num are:
0: Never write x00 format files.
1: Write x00 format files for SEQ/USR/REL, but not for PRG
2: Always write x00 format files.
3: Use SEQ/USR/REL file extensions, no x00 header
4: Same as 3, but also for PRG
If you set mode 3 or 4, extension hiding is automatically enabled.
This setting can be saved in the EEPROM using XW, the default
value is 1.
For compatibility with existing programs that write D64 files,
PRG files that have D64, D41, D71, D81, DNP or M2I as an extension
will always be written without an x00 header and without
any additional PRG file extension.
- XE+/XE- Enable/disable extension hiding. If enabled, files in FAT with
a PRG/SEQ/USR/REL extension will have their extension removed
and the file type changed to the type specified by the file
extension - e.g. APPLICATION.PRG will become a PRG file named
"APPLICATION", "README.SEQ" will become a SEQ file named "README".
This flag can be saved in the EEPROM using XW, the default
value is disabled (-).
- XInum Switches the display mode for mountables files (i.e. disk images
and M2I). num can be 0, in which case the file will be shown
with its normal type in the directory or 1 which will show all
mountable files as DIRectory entries (but they can still be
accessed as files too) or 2 in which case they will show up
twice - once with its normal type and once as directory.
The default value is 0 and this setting can be stored
permanently using XW.
It may be useful to set it to 1 or 2 when using software that
was originally written for CMD devices and which wouldn't
recognize disk images/M2I files as mountable on its own.
However, due to limitations of the current implementation of
the CD command such software may still fail to mount a disk
image with this option enabled.
- XN+/XN- Enable/disable fast format. In fast format mode, only the directory
track of an image is wiped during format.
- XH+/HN- Enable/disable hiding files with file type flag 0x20 in images.
- X*+/X*- Enable/disable 1581-style * matching. If enabled, characters
after a * will be matched against the end of the file name.
If disabled, any characters after a * will be ignored.
This flag can be saved in the EEPROM using XW, the default value
is enabled (+).
- XDdrv=val Configure drives. On ATA-based units or units with multiple
drive types, this command can be used to enable or reorder
the drives. drv is the drive slot (0-7), while val is one
of:
0: Master ATA device
1: Slave ATA device
4: Primary SD/MMC device
5: Secondary SD/MMC device
6: (reserved)
15: no device
Note that only devices supported by the specific hardware
can be selected. Unsupported device types will return an
error if requested. Also, note that you cannot select a device
in multiple drive slots. Finally, while it is possible to
re-order ATA devices using this functionality, it is strongly
discouraged. Use the master/slave jumpers on the ATA devices
instead. To reset the drive configuration, set all drive slots
to "no device". This value can be permanently saved in the
EEPROM using XW.
XD? View the current drive configuration. Example result:
"03,D:00=04:01=00:02=01,10,01". The track indicates the
current device address, while the sector indicates extended
drive configuration status information.
- X X without any following characters reports the current state
of all extended parameters via the error channel, similiar
to DolphinDOS. Example result: "03,J-:C152:E01+:B+:*+,08,00"
The track indicates the current device address.
- XS:name Set up a swap list - see "Changing Disk Images" below.
XS Disable swap list
- XR:name Set the file used for file-based M-R emulation.
XR Disable file-based M-R emulation.
See "M-R, M-W, M-E" below. This setting can be
permanently saved in the EEPROM using XW.
- XW Store configuration to EEPROM
This commands stores the current configuration in the EEPROM.
It will automatically be read when the AVR is reset, so
any changes you made will persist even after turning off
the hardware.
The stored configuration include the extension mode,
drive configuration and the current device address.
If you have changed the device address by software,
sd2iec will power up with that address unless
you have changed the device address jumpers (if available) to
a different setting than the one active at the time the
configuration was saved. You can think of this feature as
changing the meaning of one specific setting of the jumpers
to a different address if this sounds logical enough to you.
The "hardware overrides software overrides hardware" priority
was chosen to allow accessing sd2iec even when it is soft-
configured for a device number that is already taken by
another device on the bus without having to remove that
device to reconfigure sd2iec (e.g. when using a C128D).
- X? Extended version query
This commands returns the extended version string which
consists of the version, the processor type set at build time
and the suffix of the configuration file (usually corresponds
to the short name of the hardware sd2iec was compiled for).
- M-R, M-W, M-E
When no file is set up using XR, M-R will check a small internal
table of common drive-detection addresses and return data that
forces most of the supported fast loaders into a compatible mode
(e.g. 1541 mode for Dreamload and ULoad Model 3, disabled fastloader
for Action Replay 6). If the address is not recognized, more-or-less
random data will be returned.
This includes basic support for identifying the drive type based on
the type of D64 image mounted (1541 for D41, 1571 for D71 and 1581
for D81).
Unfortunately GEOS reads rather large parts of the drive rom using
M-R to detect the drive, which cannot be reasonably added into the
internal table. To enable the GEOS drive detection to work properly
with sd2iec and to allow switching between 1541/71/81 modes,
file-based M-R emulation has been implemented. If a file has been
set up as M-R data source using the XR command, its contents will be
returned for M-R commands that try to read an address in the range
of $8000-$ffff. The rom file should be a copy of the rom contents of
a 1541/71/81 drive (any headers will be skipped automatically), its
name must be 16 characters or less. When an M-R command is received,
the file will be searched in three locations on the storage medium:
1) in the current directory of the current partition
2) in the root directory of the current partition
3) in the root directory of the first partition
The internal emulation table will be used if the file wasn't found
in any of those locations or an error occured while reading
it. Please be aware that the rom file is ONLY used for M-R
commands. Except for some very specific situations where drive
detection fails (e.g. GEOS) it will probably decrease compatibility
of sd2iec because most of the implemented fast loaders will only
recognize the 1541 variation of the loader.
Memory writing knows about the address used for changing the device
address on a 1541 and will change the address of sd2iec to the
requested value. It will also check if the transmitted data
corresponds to any of the known software fastloaders so the correct
emulation code can be used when M-E is called.
Large buffers:
==============
To support commands which directly access the storage devices support
for larger buffers was added. A large buffer can be allocated by
opening a file named "##<d>" (exactly three characters" with <d> replaced
by a single digit specifying the number of 256-byte buffers to be
chained into one large buffer - e.g. "##2" for a 512 byte buffer,
"##4" for 1024 bytes etc. Unlike a standard buffer where the read/write
pointer is set to byte 1, a large buffer will start with the r/w pointer
pointing to byte 0 because that seems to be more sensible to the author.
If there aren't enough free buffers to support the size you requested
a 70,NO CHANNEL message is set in the error channel and no file is
opened. If the file name isn't exactly three bytes long a standard
buffer ("#") will be allocated instead for compatibility.
The B-P command supports a third parameter that holds the high byte
of the buffer position, For example, "B-P 9 4 1" positions to byte
260 (1*256+4) of the buffer on secondary address 9.
Long File Names:
================
Long file names (i.e names not within the 8.3 limits) are supported on
FAT, but for compatibility reasons the 8.3 name is used if the long
name exceeds 16 characters. If you use anything but ASCII characters
on the PC or their PETSCII equivalents on the Commodore you may
get strange characters on the other system because the LFN use
unicode characters on disk, but sd2iec parses only the low byte
of each character in the name.
EEPROM file system
==================
*WARNING*: The EEPROM file system is a newly-implemented file system
that may still contain bugs. Do not store data on it that you cannot
affort to lose. Always make sure that you have a backup. Also, the
format may change in later releases, so please expect that the
partition may need to be erased in the future.
Devices running sd2iec always have an EEPROM to store the system
configuration, but on some devices this EEPROM is much larger than
required. To utilize the empty space on these devices (currently any
microcontroller with at least 128K of flash), a special EEPROM file
system has been implemented. This can for example be used to store a
small file browser or fast loader so it can be used independent of the
storage medium that is currently inserted.
The EEPROM file system will always register itself on the last
partition number (see "Partitions" below). You can check the list of
partitions ("$=P") to find the current partition number of the EEPROM
file system or use the alias function (see below) to access it.
To simplify calculations, block numbers on the EEPROMFS are calculated
using 256 bytes per block instead of the usual 254 bytes as used by
Commodore drives. Internally, the allocation is even more fine-grained
(using 64 byte sectors), which means that the number of free blocks
shown on an empty file system may be less than the sum of the number
of blocks of all files on a full file system.
The EEPROM file system does not support subdirectories. It can be
formatted using the N: command as usual, but the disk name and ID are
ignored. The capacity of the EEPROM file system varies between
devices: On AVR devices it is 3.25 KBytes and at most 8 files can be
stored on it. On a2iec, the file system can hold 7 KBytes and at most
16 files can be stored on it. The actual number of files that can be
stored depends on the length of the files, longer files need more than
one directory entry.
Partitions:
===========
sd2iec features a multi-partition support similiar to that of the CMD
drives. The partitions (which may be on separate drives for some hardware
configurations) are accessed using the drive number of the commands
sent from the computer and are numbered starting with 1. Partition 0
is a special case: Because most software doesn't support drive numbers
or always sends drive number 0, this partition points to the currently
selected partition. By default, accesses to partition 0 will access
partition 1, this can be changed by sending "CP<num>" over the command
channel with <num> being an ASCII number from 1 to 255. "C<Shift-P"
(0x42 0xd0) works the same, but expects a binary partition number as the
third character of the command.
To allow a "stable" access to the EEPROM file system no matter how
many partitions are currently available, a special character has been
introduced that will always access the EEPROM file system (if
available). When sd2iec sees a "!" character where it expects a
partition number and the "!" character is directly followed by a colon
(i.e. "!:"), it will access the EEPROMFS if available. Direct access
using the assigned partition number is of course still
available. Additionally "$!" will always load the directory of the
EEPROM file system partition (if available), similar to "$1" to "$9"
for partitions 1 to 9.
Software fastloaders:
=====================
Note: Using sd2iec without an external crystal or similiar precise
clock source is not a supported configuration.
If you try that anyway, be prepared to suffer from random
data corruption. You have been warned.
Some fastloader implementations will actively refuse to work
if you use an unsuitable clock source.
Turbodisk
---------
Turbodisk is detected by the CRC of its 493 byte long floppy code and
the M-E address 0x0303. The same code seems to be used under various names,
among them "Turbodisk" (both 2.1 and 2.2) and "Fast-Load".
It is not known if there is an NTSC-compatible version of this fastloader.
Final Cartridge III
-------------------
Both the fast loader and the fast saver of Final Cartridge III are supported.
The FC3 is both PAL and NTSC compatible.
The slightly different fastloader used for files freezed with the FC3
is also supported.
EXOS V3 and The Beast System
----------------------------
Both supported, the loader used by these kernals is very similiar to
the FC3 fast loader.
Action Replay 6
---------------
The AR6 reads a byte from the drive rom to check which fastloader it should
use. When file-based M-R emulation is disabled sd2iec returns a value that
should force the cartridge to use the standard kernal loader instead of its
many fastloaders/-savers. This means that accessind sd2iec with
file-based rom emulation enabled will fail because the cartridge
will enable fastloader that will probably not be recognized.
Currently the only recognized AR6 fastloader and fastsaver are the
ones for the 1581.
Dreamload
---------
Dreamload uses direct track/sector access, so it is only supported
on D64 or similiar disk image formats. As sd2iec has to wait for commands
from the C64 constantly the disk change buttons may become unresponsive,
try multiple times if you need to. Dreamload is a "captive" fastloader,
sd2iec stay in Dreamload mode until it receives a "quit loader" command
from the C64. To force sd2iec to resume normal operation, hold the disk
change button until the red LED turns on (just like sleep mode).
Please note that Dreamload does not work with more than one device on the
serial bus due to the way it uses the ATN line.
ULoad Model 3
-------------
ULoad Model 3 uses direct track/sector access, so it is only supported
on D64 or similiar disk image formats. Currently there is exactly one
supported variant of ULoad Model 3, which is the one used by
Ultima 3 Gold. There are no other known variants at this time, but
this may change.
If you are a coder and want to use ULoad Model 3 in your own program,
either configure it to produce the same drive code as U3Gold or
contact me so we can work out a way to trigger ULoad M3 support
without uploading any drive code at all.
G.I. Joe Loader
---------------
Said to be the most-ripped IRQ loader. Unfortunately this is a
"captive" fastloader similiar to dreamload (but not restricted
to disk images because it is file name-based) and there is no
reliable way to detect if the computer has been reset to switch
back to the standard protocol. To exit this loader, hold down
the disk change button until the red LED turns on, just like
sleep mode.
Epyx FastLoad Cartridge
-----------------------
ONLY the fast loader from this cartridge is supported, no
disk editor/copier/whatever functions.
GEOS
----
GEOS 2.0 can be booted from D64 images made from original disks
as well as D41/71/81 images created using geoMakeBoot (make sure to
Configure the system for a 1541/1571/1581 before using geoMakeBoot).
When file-based M-R emulation is disabled, GEOS may detect sd2iec as
a 1541 or 1581, depending on the version of Configure used. This may
cause the system to fail to boot, e.g. if sd2iec is detected as a 1581
while booting from a D64 disk image. It is recommended to set up file-
based M-R emulation when using GEOS to avoid these problems.
GEOS 1.3 may or may not work - it boots, but wasn't tested in-depth.
Gateway seems to work but was not tested beyond booting it from a D64
image.
Using the buttons for changing the current disk image is supported,
but do make sure that you only access disk images that the drive
type that is selected in GEOS would support (i.e. D64 for a 1541,
D64/D71 for a 1571 and D81 for a 1581).
Wheels
------
Wheels can be booted from any disk image type it supports. The correct
rom emulation file (XR) MUST be set, especially for CMD HD emulation.
Do not use the disk change feature to change disk images when HD emulation
is in use - Wheels does not check for disk changes on that drive!
For other drive types the restrictions on disk image type of GEOS also
apply to Wheels.
ELoad Version 1
---------------
This loader was made for EasyProg but may also be used in other programs.
It detects and supports the sd2iec natively.
Maniac Mansion
--------------
Original versions of Maniac Mansion have an additional copy protection
check that is not supported by sd2iec. Please use a cracked version
instead - the ones from Gamebase 64 seem to work. Please remember to
add an empty D64 for the save/load disk to your swaplist if you want
to save your game.
The game uses a captive loader that unfortunately cannot detect if it
should exit automatically - to resume normal operation, you need to
hold down the NEXT button until the red LED turns on.
Zak McKracken
-------------
Same as Maniac Mansion, but this game only has a code list protection,
so images of original disks should work fine.
Sam's Journey
-------------
The loader in Sam's Journey expects that there is only a single
drive active on the serial bus and that this drive has ID 8. The
reimplementation in sd2iec can handle both disk images and extracted
files stored in a single directory directly on the SD
card. The loader is captive, but it tries to exit cleanly when
possible - but if you reset the C64 while it is reading data (busy
LED lit, e.g. during the intro), sd2iec will hang and requires a
reset or powercycle to recover.
Ultraboot
---------
Both standard Ultraboot and Ultraboot Menue are supported. Ultraboot
stores its data on the nonstandard tracks 36 to 40 with up to 21
sectors per track. It therefore only works from extended, "D41" style
D64 images. The D64 format is defined with a fixed number of 17 sectors
for these tracks, so the sd2iec implementation expects the additional
sectors to be linearly mapped to D64 sectors. That is, sectors 17 to 20
of track 36 are equivalent to sectors 0 to 3 of track 37 in standard
D64 format and so on. Likewise, sector 40/20 (the last possible sector
for Ultraboot) corresponds to D64 sector 41/19.
Ultraboot Maker can be used to add Ultraboot to D41 images mounted
on the sd2iec. The image will be automatically extended to either 40
or 42 tracks, depending on the size of the payload. This only works
if no error information block is present in the image, as relocating
the error information is not supported. An error info block is added
in the process and sectors on unused (mapped) tracks will have a NO
SYNC error set.
Hypra-Load
----------
Hypra-Load uses the ATN line for handshake, so it only works if no
other device is connected to the IEC bus.
Krill's IRQ Loader
------------------
The sd2iec implementation supports loading both from D41/D71/D81
images and files extracted to the SD card. Extracting the files
in a useable form can be a challenge for some releases, though:
Some use directory entries on a non-standard track, payload might
be read from files marked as deleted in the directory and the
"load next file" functionality of the loader relies on the order
of the files in the directory.
A small number of releases use track/sector addressing to load
files; these only work from a D64 image.
See doc/krills-loader.txt for additional remarks regarding specific
releases.
The loader is captive, but the sd2iec implementation should most
of the time be able to detect a host reset or uninstall and exit
accordingly.
As the ATN line is used as a clock line for transfers, no other
drives might be active on the bus. Starting with revision r164,
the loader tries to silence other devices by installing an "ATN
responder". If the sd2iec is used as a passive device on the bus,
this activates "Sleep Mode" (see below), which has to be ended
manually by holding the disk change button.
On a C128 host the loader uses the fast serial protocol if connected
to a 1571 or 1581. This is not yet supported by this implementation.
(The only known C128 release using this loader is "Colour Spectrum",
CSDb Release ID 205653).
With a few exceptions, only productions released on CSDb which
credit Krill for their loader were tested. Other productions might
use configuration options which are not supported and therefore
might not work.
Another World
-------------
The loader in Another World is captive and requires a reset to exit.
See docs/anotherworld.txt for deailed information about this loader
and its protocol.
Wings of Fury (PAL import)
--------------------------
This loader checks address $FFFE on the 1541 RAM for drive validation.
Thus, WoF needs a ROM file in the same directory as the game's D64
file. A real 1541 ROM can be used, but a fake ROM all zeroed-out
with just a single byte at $FFFE to pass validation is provided for
convenience at: doc/wingsoffury.
In addition to dropping the 1541.bin file along with the game's D64,
the following commands must be issued from BASIC to let sd2iec know
that it must use this file for memory read (M-R) DOS commands.
OPEN 1,8,15:PRINT#1,"XR:1541.BIN":CLOSE 1
OPEN 1,8,15:PRINT#1,"XW":CLOSE 1
Or, if you have a DOS enhancer (Epyx Fastload, etc.):
@XR:1541.BIN
@XW
Demo loaders: Bitfire, BoozeLoader, Sparkle, Spindle
----------------------------------------------------
All these loaders use sector addressing and non-standard directories
and therefore only work from the original D64 images, not from the
FAT filesytem.
The Highscore-Saver available in Sparkle >= 2.0 is supported.
Like Krill's Loader, Bitfire >= 1.0 and Spindle >= 3.0 include an
ATN responder which activates "Sleep Mode" in a sd2iec present on
the bus as a passive device.
The loaders are captive, but often support some form of command to
make the loader's job loop exit at the end of the demo (but not all
productions actually issue them). That said, host reset detection
works rather well in practice. Spindle 2.1 and Bitfire 0.1 are
slightly subpar in this regard, but even with these a second reset
will normally do.
With a few exceptions, only productions released on CSDb which
credit the respective author for the loader were tested. Others
might not work. For a list of known productions using these loaders
and known issues, see the tables at the end of the respective
documents in the "doc" directory of this repository.
JiffyDOS:
=========
The JiffyDOS protocol has very relaxed timing constraints compared to
Turbodisk, but still not as relaxed as the standard Commodore IEC protocol.
x00 files:
==========
P00/S00/U00/R00 files are transparently supported, that means they show
up in the directory listing with their internal file name instead of the
FAT file name. Renaming them only changes the internal name. The XE
command defines if x00 extensions are used when writing files, by
default sd2iec uses them for SEQ/USR/REL files but not for PRG.
Parsing of x00 files is always enabled even when writing them is not.
x00 files are recognized by checking both the extension of the file
(P/S/U/R with a two-digit suffix) and the header signature.
Disk Images:
============
Disk images are recognized by their file extension (.D64, .D41, .D71, .D81,
.DNP) and their file size.
D41 images with more than 35 tracks can be mounted, if the additional
data is a multiple of 17 sectors and within a maximum of 42 tracks total.
It's up to the individual loader implementations to actually make use of
these extra sectors. Allocation e.g. for SAVE won't take them into
account. Unlike original CBM DOS, B-R/U1 and B-W/U2 will access sectors
on non-standard tracks without error.
If the image has an error info block appended it will be used to simulate
read errors. Writing to a sector with an error will always work, but it
will not clear the indicated error. Formatting will not remove the error
info block but clear all errors.
Warning: There is at least one program out there (DirMaster v2.1/Style by
THE WIZ) which generates broken DNP files. The usual symptom is that
moving from a subdirectory that was created with this program back to
its parent directory using CD:_ (left arrow) sets the current directory
not to the parent directory, but to an incorrect sector instead. A
workaround for this problem in sd2iec would require an unreasonable
amount of system resources, so it is recommended to avoid creating
subdirectories with this version of DirMaster. It is possible to fix
this problem using a hex editor, but the exact process is beyond the scope
of this document.
M2I files:
==========
NOTICE: Support for M2I files will be removed in the next release, see
the deprecation notices at the top of this file for advice.
M2I files are fully supported. sd2iec supports SEQ and USR files in this
format in addition to PRG and DEL which were already implemented in MMC2IEC.
For compatibility reasons the file type is not checked when opening files.
Inside an M2I file the files are always shown as 0 (DEL) or 1 blocks
because calling stat for every file was slowing down the directory listing
too much. For compatibility with existing M2I files the data files do not
use P00 headers even when the file type is SEQ or USR.
REL files:
==========
Partial REL file support is implemented. It should work fine for existing
files, but creating new files and/or adding records to existing files
may fail. REL files in disk images are not supported yet, only as files
on a FAT medium. When x00 support is disabled the first byte of a REL
file is assumed to be the record length.
Changing Disk Images
====================
Because some programs require more than one disk side there is support
for changing the currently mounted disk image with two buttons called
NEXT and PREV connected to the AVR.
If your circuit doesn't have disk change pins/buttons you might be able to
add it yourself. In all cases the buttons need to connect the given
pins of the chip to ground.
- For the original MMC2IEC ("larsp"):
The NEXT button is in input PA4, the PREV button is on PA5.
PA4 is pin 36 on the DIL version of the controller or pin 33 on the
surface-mount version. PA5 is pin 35 on DIL, pin 32 on SMD.
- For Shadowolf's MMC2IEC 1.x PCBs ("sw1"):
The NExT button is on input PC4, the PREV button is on PC3.
PC4 is pin 26 on the DIL version of the controller or pin 23 on the
surface-mount version. PC3 is pin 25 on DIL, pin 22 on SMD.
- For Shadowolf's sd2iec 1.x PCBs ("sw2"):
The two required pins are available on the pin header which runs
parallel to the long side of the board. In the documentation of the
board, the NEXT button is named "DISKSWITCH", the PREV button is
named "RESERVE".
- Any other circuit without disk change pin on a convenient connector
somewhere and no button dedicated to that function: Please check
with the supplier of the board and read config.h in the sources
to find out how to connect it.
To use this functionality, you can either create a swap list file
yourself or let sd2iec create one for you.
Creating a swap list
--------------------
A swap list is a text file with one line per disk image or directory
you want to be able to change into. You are not limited to using disk
images, a swap list file may also refer to standard directories on the
SD card or anything else the CD command of sd2iec will accept.
The swap list file is relatively tolerant against multiple styles of
line-endings, sd2iec should be able to parse the file no matter if you
create it on a Windows system, Unix or even the C64 itself - as a side
effect, empty lines are also ignored. By default sd2iec assumes that
the file is encoded in ASCII (for files created on a PC or similar),
but if the first line of the file exactly reads "#PETSCII" (in hex: 23
50 45 54 53 43 49 49), file names are assumed to be encoded in PETSCII
instead and this marker line is skipped.
To add comments to a swap list, start a line with a semicolon (;). Any
such line will be skipped by sd2iec when parsing the swap list.
An example swap list file could look like this:
=== example 1 ===
FOO.D64
BAR.D64
BAZ.D64
=== end of example 1 ===
=== example 2 ===
//NEATGAME/:DISK1A.D64
//NEATGAME/:DISK1B.D64
//NEATGAME/:DISK2A.D64
//NEATGAME/:DISK2B.D64
; save disk in separate directory for easier backup
//SAVEDISKS/:NEATGAME.D64
=== end of example 2 ===
The swap list is enabled by sending "XS:filename" over the command