fastloader-GEOS: Add missing track masking to 1581 reads
[sd2iec.git] / README
1 sd2iec - a controller/interface adapting storage devices to the CBM serial bus
2 Copyright (C) 2007-2014  Ingo Korb <ingo@akana.de>
3 Parts based on code from others, see comments in main.c for details.
4 JiffyDos send based on code by M.Kiesel
5 Fat LFN support and lots of other ideas+code by Jim Brain
6 Final Cartridge III fastloader support by Thomas Giesel
7 IEEE488 support by Nils Eilers
8
9 Free software under GPL version 2 ONLY, see comments in main.c and
10 COPYING for details.
11
12 FIXME:This file still needs to be expanded. A lot.
13 FIXME: sprinkle mentions of IEEE488 where appropiate
14
15 Deprecation notices
16 ===================
17 The following feature(s) will be removed in the next release:
18 - M2I support
19    M2I support has been redundant since the introduction of transparent
20    P00 support. To continue to use your M2I-format software, convert
21    your files to P00 format (e.g. with m2itopc64.c) and set your device
22    to extension mode 2 (XE2).
23
24 Introduction:
25 =============
26 sd2iec is firmware, used in hardware designs like MMC2IEC, SD2IEC, or uIEC,
27 that allows the Commodore serial bus to access removable storage devices
28 (MMC, SD, CF) - think of it as a 1541 with a modern storage medium instead
29 of disks. The project was inspired by (and uses a few bits of code from)
30 MMC2IEC[1] by Lars Pontoppidan and once ran on the same hardware before it
31 grew too big for the ATmega32 used there.
32
33 Currently, the firmware provide good DOS and file-level compatibility with CBM
34 drives, but much work remains.  Unless specifically noted, anything that tries
35 to execute code on the 1541 will not work, this includes every software
36 fastloader.
37
38 [1] Homepage: http://pontoppidan.info/lars/index.php?proj=mmc2iec
39
40 Please note: Whenever this file talks about "D64 images" the text applies to
41 all Dxx image types, i.e. D64/D71/D81/DNP unless specifically noted.
42
43 If you are the author of a program that needs to detect sd2iec for
44 some reason, DO NOT use M-R for this purpose. Use the UI command
45 instead and check the message you get for "sd2iec" and "uiec" instead.
46
47
48 Supported commands:
49 ===================
50 - General notes:
51   Any command not listed below is currently not supported.
52
53 - Directory filters:
54   To show only directories, both =B (CMD-compatible) and =D can be used.
55   On a real Commodore drive D matches everything.
56   To include hidden files in the directory, use *=H - on a 1541 this doesn't
57   do anything. sd2iec marks hidden files with an H after the lock mark,
58   i.e. "PRG<H" or "PRG H".
59
60   CMD-style "short" and "long" directory listings with timestamps are supported
61   ("$=T"), including timestamp filters. Please read a CMD manual for the syntax
62   until this file is updated.
63
64 - Partition directory:
65   The CMD-style partition directory ($=P) is supported, including filters
66   ($=P:S*). All partitions are listed with type "FAT", although this could
67   change to "NAT" later for compatibility.
68
69 - CD/MD/RD:
70   Subdirectory access is compatible to the syntax used by the CMD drives,
71   although drive/partition numbers are completely ignored.
72
73   Quick syntax overview:
74     CD:_         changes into the parent dir (_ is the left arrow on the C64)
75     CD_          dito
76     CD:foo       changes into foo
77     CD/foo       dito
78     CD//foo      changes into \foo
79     CD/foo/:bar  changes into foo\bar
80     CD/foo/bar   dito
81
82   You can use wildcards anywhere in the path. To change into an M2I or D64
83   image the image file must be the last component in the path, either
84   after a slash or a colon character.
85
86   MD uses a syntax similiar to CD and will create the directory listed
87   after the colon (:) relative to any directory listed before it.
88
89     MD/foo/:bar  creates bar in foo
90     MD//foo/:bar creates bar in \foo
91
92   RD can only remove subdirectories of the current directory.
93
94     RD:foo       deletes foo
95
96   CD is also used to mount/unmount image files. Just change into them
97   as if they were a directory and use CD:_ (left arrow on the C64) to leave.
98   Please note that image files are detected by file extension and file size
99   and there is no reliable way to see if a file is a valid image file.
100
101 - CP, C<Shift-P>
102   This changes the current partition, see "Partitions" below for details.
103
104 - C:
105   File copy command, should be CMD compatible. The syntax is
106    C[partition][path]:targetname=[[partition][path]:]sourcename[,[[p][p]:]sourcename...]
107   You can use this command to copy multiple files into a single target
108   file in which case all source files will be appended into the target
109   file. Parsing restarts for every source file name which means that
110   every source name is assumed to be relative to the current directory.
111   You can use wildcards in the source names, but only the first
112   file matching will be copied.
113
114   Copying REL files should work, but isn't tested well. Mixing REL and
115   non-REL files in an append operation isn't supported.
116
117 - D
118   Direct sector access, this is a command group introduced by sd2iec.
119   Some Commodore drives use D for disk duplication between two drives
120   in the same unit, an attempt to use that command with sd2iec should
121   result in an error message.
122
123   D has three subcommands: DI (Info), DR (Read) and DW (Write).
124   Each of those commands requires a buffer to be opened (similiar
125   to U1/U2), but due to the larger sector size of the storage devices
126   used by sd2iec it needs to be a large buffer of size 2 (512 bytes)
127   or larger. The exception is the DI command with page set to 0,
128   its result will always fir into a standard 256 byte buffer.
129   If you try to use one of the commands with a buffer that is too
130   small a new error message is returned, "78,BUFFER TOO SMALL,00,00".
131
132   In the following paragraphs the secondary address that was used
133   to open the buffer is called "bufchan".
134
135   - DI
136     In BASIC notation the command format is
137       "DI"+chr$(bufchan)+chr$(device)+chr$(page)
138
139     "device" is the number of the physical device to be queried,
140     "page" the information page to be retrieved. Currently the
141     only page implemented is page 0 which will return the
142     following data structure:
143      1 byte : Number of valid bytes in this structure
144               This includes this byte and is meant to provide
145               backwards compatibility if this structure is extended
146               at a later time. New fields will always be added to
147               the end so old programs can still read the fields
148               they know about.
149      1 byte : Highest diskinfo page supported
150               Always 0 for now, will increase if more information
151               pages are added (planned: Complete ATA IDENTIFY
152               output for IDE and CSD for SD)
153      1 byte : Disk type
154               This field identifies the device type, currently
155               implemented values are:
156                 0  IDE
157                 2  SD
158                 3  (reserved)
159      1 byte : Sector size divided by 256
160               This field holds the sector size of the storage device
161               divided by 256.
162      4 bytes: Number of sectors on the device 
163               A little-endian (same byte order as the 6502) value
164               of the number of sectors on the storage device.
165               If there is ever a need to increase the reported
166               capacity beyond 2TB (for 512 byte sectors) this
167               field will return 0 and a 64-bit value will be added
168               to this diskinfo page.
169
170     If you want to determine if there is a device that responds
171     to a given number, read info page 0 for it. If there is no
172     device present that corresponds to the number you will see
173     a DRIVE NOT READY error on the error channel and the
174     "number of valid bytes" entry in the structure will be 0.
175
176     Do not assume that device numbers are stable between releases
177     and do not assume that they are continuous either. To scan
178     for all present devices you should query at least 0-7 for now,
179     but this limit may increase in later releases.
180
181   - DR/DW
182     In BASIC notation the command format would be
183       "DR"+chr$(bufchan)+chr$(device)
184           +chr$(sector AND 255)
185           +chr$((sector/256) AND 255)
186           +chr$((sector/65536) AND 255)
187           +chr$((sector/16777216) AND 255)
188     (or "DW" instead of "DR)
189     but this won't work on the C64 because AND does not accept
190     parameters larger than 32767. The principle should be clear
191     though, the last four bytes are a 32 bit sector number in
192     little-endian byte order.
193
194     DR reads the sector to the buffer, DW writes the contents
195     of the buffer to the sector. Both commands will update the
196     error channel if an error occurs, for DR the 20,READ ERROR
197     was chosen to represent read errors; for write problems
198     during DW it sets 25,WRITE ERROR for errors and 26,WRITE
199     PROTECT ON if the device is read-only.
200
201 - G-P
202   Get partition info, see CMD FD/HD manual for details. The reported
203   information is partially faked, feedback is welcome.
204
205 - P
206   Positioning doesn't just work for REL files but also for regular
207   files on a FAT partition. When used for regular files the format
208   is "P"+chr$(channel)+chr$(lo)+chr$(midlo)+chr$(midhi)+chr$(hi)
209   which will seek to the 0-based offset hi*2^24+midhi*65536+256*midlo+lo
210   in the file. If you send less than four bytes for the offset, the
211   missing bytes are assumed to be zero.
212
213 - N:
214   Format works only if a D64 image is already mounted. This command will
215   be ignored for DNP images unless the current directory is the root
216   directory of the DNP image.
217
218 - R
219   Renaming files should work the same as it does on CMD drives, although
220   the errors flagged for invalid characters in the name may differ.
221
222 - S:
223   Name matching is fully supported, directories are ignored.
224   Scratching of multiple files separated by , is also supported with no
225   limit to the number of files except for the maximum command line length
226   (usually 100 to 120 characters).
227
228 - T-R and T-W
229   If your hardware features RTC support the commands T-R (time read) and T-W
230   (time write) are available. If the RTC isn't present, both commands return
231   30,SYNTAX ERROR,00,00; if the RTC is present but not set correctly T-R will
232   return 31,SYNTAX ERROR,00,00.
233
234   Both commands expect a fourth character that specifies the time format
235   to be used. T-W expects that the new time follows that character
236   with no space or other characters inbetween. For the A, B and D
237   formats, the expected input format is exactly the same as returned
238   by T-R with the same format character; for the I format the day of
239   week is ignored and calculated based on the date instead.
240
241   The possible formats are:
242    - "A"SCII: "SUN. 01/20/08 01:23:45 PM"+CHR$(13)
243       The day-of-week string can be any of "SUN.", "MON.", "TUES", "WED.",
244       "THUR", "FRI.", "SAT.". The year field is modulo 100.
245
246    - "B"CD or "D"ecimal:
247      Both these formats use 9 bytes to specify the time. For BCD everything
248      is BCD-encoded, for Decimal the numbers are sent/parsed as-is.
249       Byte 0: Day of the week (0 for sunday)
250            1: Year (modulo 100 for BCD; -1900 for Decimal, i.e. 108 for 2008)
251            2: Month (1-based)
252            3: Day (1-based)
253            4: Hour   (1-12)
254            5: Minute (0-59)
255            6: Second (0-59)
256            7: AM/PM-Flag (0 is AM, everything else is PM)
257            8: CHR$(13)
258
259       When the time is set a year less than 80 is interpreted as 20xx.
260
261    - "I"SO 8601 subset: "2008-01-20T13:23:45 SUN"+CHR$(13)
262      This format complies with ISO 8601 and adds a day of week
263      abbreviation using the same table as the A format, but omitting
264      the fourth character. When it is used with T-W, anything beyond
265      the seconds field is ignored and the day of week is calculated
266      based on the specified date. The year must always be specified
267      including the century if this format is used to set the time.
268      To save space, sd2iec only accepts this particular date/time
269      representation when setting the time with T-WI and no other ISo
270      8601-compliant representation.
271
272 - U0
273   Device address changing with "U0>"+chr$(new address) is supported,
274   other U0 commands are currently not implemented.
275
276 - U1/U2/B-R/B-W
277   Block reading and writing is fully supported while a D64 image is mounted.
278
279 - B-P
280   Supported, not checked against the original rom at all.
281
282 - UI+/UI-
283   Switching the slightly faster bus protocol for the VC20 on and off works,
284   it hasn't been tested much though.
285
286 - UI/UJ
287   Soft/Hard reset - UI just sets the "73,..." message on the error channel,
288   UJ closes all active buffers but doesn't reset the current directory,
289   mounted image, swap list or anything else.
290
291 - U<Shift-J>
292   Real hard reset - this command causes a restart of the AVR processor
293   (skipping the bootloader if installed). <Shift-J> is character code 202.
294
295 - X: Extended commands. If you use JiffyDOS, you can send them by using
296   @"X..." - without quotes you'll just receive an error.
297
298   - XEnum    Sets the "file extension mode". This setting controls if
299              files on FAT are written with an x00 header and extension or not.
300              Possible values for num are:
301                0: Never write x00 format files.
302                1: Write x00 format files for SEQ/USR/REL, but not for PRG
303                2: Always write x00 format files.
304                3: Use SEQ/USR/REL file extensions, no x00 header
305                4: Same as 3, but also for PRG
306              If you set mode 3 or 4, extension hiding is automatically enabled.
307              This setting can be saved in the EEPROM using XW, the default
308              value is 1.
309
310              For compatibility with existing programs that write D64 files,
311              PRG files that have D64, D41, D71, D81, DNP or M2I as an extension
312              will always be written without an x00 header and without
313              any additional PRG file extension.
314
315   - XE+/XE-  Enable/disable extension hiding. If enabled, files in FAT with
316              a PRG/SEQ/USR/REL extension will have their extension removed
317              and the file type changed to the type specified by the file
318              extension - e.g. APPLICATION.PRG will become a PRG file named
319              "APPLICATION", "README.SEQ" will become a SEQ file named "README".
320              This flag can be saved in the EEPROM using XW, the default
321              value is disabled (-).
322
323   - XInum    Switches the display mode for mountables files (i.e. disk images
324              and M2I). num can be 0, in which case the file will be shown
325              with its normal type in the directory or 1 which will show all
326              mountable files as DIRectory entries (but they can still be
327              accessed as files too) or 2 in which case they will show up
328              twice - once with its normal type and once as directory.
329              The default value is 0 and this setting can be stored
330              permanently using XW.
331
332              It may be useful to set it to 1 or 2 when using software that
333              was originally written for CMD devices and which wouldn't
334              recognize disk images/M2I files as mountable on its own.
335              However, due to limitations of the current implementation of
336              the CD command such software may still fail to mount a disk
337              image with this option enabled.
338
339   - X*+/X*-  Enable/disable 1581-style * matching. If enabled, characters
340              after a * will be matched against the end of the file name.
341              If disabled, any characters after a * will be ignored.
342              This flag can be saved in the EEPROM using XW, the default value
343              is enabled (+).
344
345   - XDdrv=val Configure drives.  On ATA-based units or units with multiple
346              drive types, this command can be used to enable or reorder
347              the drives.  drv is the drive slot (0-7), while val is one
348              of:
349                 0: Master ATA device
350                 1: Slave ATA device
351                 4: Primary SD/MMC device
352                 5: Secondary SD/MMC device
353                 6: (reserved)
354                15: no device
355
356              Note that only devices supported by the specific hardware
357              can be selected.  Unsupported device types will return an
358              error if requested.  Also, note that you cannot select a device
359              in multiple drive slots.  Finally, while it is possible to
360              re-order ATA devices using this functionality, it is strongly
361              discouraged.  Use the master/slave jumpers on the ATA devices
362              instead.  To reset the drive configuration, set all drive slots
363              to "no device".  This value can be permanently saved in the
364              EEPROM using XW.
365
366     XD?      View the current drive configuration.  Example result:
367              "03,D:00=04:01=00:02=01,10,01".  The track indicates the
368              current device address, while the sector indicates extended
369              drive configuration status information.
370
371   - X        X without any following characters reports the current state
372              of all extended parameters via the error channel, similiar
373              to DolphinDOS. Example result: "03,J-:C152:E01+:B+:*+,08,00"
374              The track indicates the current device address.
375
376   - XS:name  Set up a swap list - see "Changing Disk Images" below.
377     XS       Disable swap list
378
379   - XR:name  Set the file used for file-based M-R emulation.
380     XR       Disable file-based M-R emulation.
381              See "M-R, M-W, M-E" below. This setting can be
382              permanently saved in the EEPROM using XW.
383
384   - XW       Store configuration to EEPROM
385              This commands stores the current configuration in the EEPROM.
386              It will automatically be read when the AVR is reset, so
387              any changes you made will persist even after turning off
388              the hardware.
389
390              The stored configuration include the extension mode,
391              drive configuration and the current device address.
392              If you have changed the device address by software,
393              sd2iec will power up with that address unless
394              you have changed the device address jumpers (if available) to
395              a different setting than the one active at the time the
396              configuration was saved. You can think of this feature as
397              changing the meaning of one specific setting of the jumpers
398              to a different address if this sounds logical enough to you.
399
400              The "hardware overrides software overrides hardware" priority
401              was chosen to allow accessing sd2iec even when it is soft-
402              configured for a device number that is already taken by
403              another device on the bus without having to remove that
404              device to reconfigure sd2iec (e.g. when using a C128D).
405
406   - X?       Extended version query
407              This commands returns the extended version string which
408              consists of the version, the processor type set at build time
409              and the suffix of the configuration file (usually corresponds
410              to the short name of the hardware sd2iec was compiled for).
411
412 - M-R, M-W, M-E
413   When no file is set up using XR, M-R will check a small internal
414   table of common drive-detection addresses and return data that
415   forces most of the supported fast loaders into a compatible mode
416   (e.g. 1541 mode for Dreamload and ULoad Model 3, disabled fastloader
417   for Action Replay 6). If the address is not recognized, more-or-less
418   random data will be returned.
419
420   Unfortunately GEOS reads rather large parts of the drive rom using
421   M-R to detect the drive, which cannot be reasonably added into the
422   internal table. To enable the GEOS drive detection to work properly
423   with sd2iec and to allow switching between 1541/71/81 modes,
424   file-based M-R emulation has been implemented. If a file has been
425   set up as M-R data source using the XR command, its contents will be
426   returned for M-R commands that try to read an address in the range
427   of $8000-$ffff. The rom file should be a copy of the rom contents of
428   a 1541/71/81 drive (any headers will be skipped automatically), its
429   name must be 16 characters or less. When an M-R command is received,
430   the file will be searched in three locations on the storage medium:
431     1) in the current directory of the current partition
432     2) in the root directory of the current partition
433     3) in the root directory of the first partition
434
435   The internal emulation table will be used if the file wasn't found
436   in any of those locations or an error occured while reading
437   it. Please be aware that the rom file is ONLY used for M-R
438   commands. Except for some very specific situations where drive
439   detection fails (e.g. GEOS) it will probably decrease compatibility
440   of sd2iec because most of the implemented fast loaders will only
441   recognize the 1541 variation of the loader.
442
443   Memory writing knows about the address used for changing the device
444   address on a 1541 and will change the address of sd2iec to the
445   requested value. It will also check if the transmitted data
446   corresponds to any of the known software fastloaders so the correct
447   emulation code can be used when M-E is called.
448
449 Large buffers:
450 ==============
451 To support commands which directly access the storage devices support
452 for larger buffers was added. A large buffer can be allocated by
453 opening a file named "##<d>" (exactly three characters" with <d> replaced
454 by a single digit specifying the number of 256-byte buffers to be
455 chained into one large buffer - e.g. "##2" for a 512 byte buffer,
456 "##4" for 1024 bytes etc. Unlike a standard buffer where the read/write
457 pointer is set to byte 1, a large buffer will start with the r/w pointer
458 pointing to byte 0 because that seems to be more sensible to the author.
459
460 If there aren't enough free buffers to support the size you requested
461 a 70,NO CHANNEL message is set in the error channel and no file is
462 opened. If the file name isn't exactly three bytes long a standard
463 buffer ("#") will be allocated instead for compatibility.
464
465 The B-P command supports a third parameter that holds the high byte
466 of the buffer position, For example, "B-P 9 4 1" positions to byte
467 260 (1*256+4) of the buffer on secondary address 9.
468
469 Long File Names:
470 ================
471 Long file names (i.e names not within the 8.3 limits) are supported on
472 FAT, but for compatibility reasons the 8.3 name is used if the long
473 name exceeds 16 characters. If you use anything but ASCII characters
474 on the PC or their PETSCII equivalents on the Commodore you may
475 get strange characters on the other system because the LFN use
476 unicode characters on disk, but sd2iec parses only the low byte
477 of each character in the name.
478
479 EEPROM file system
480 ==================
481 *WARNING*: The EEPROM file system is a newly-implemented file system
482 that may still contain bugs. Do not store data on it that you cannot
483 affort to lose. Always make sure that you have a backup. Also, the
484 format may change in later releases, so please expect that the
485 partition may need to be erased in the future.
486
487 Devices running sd2iec always have an EEPROM to store the system
488 configuration, but on some devices this EEPROM is much larger than
489 required. To utilize the empty space on these devices (currently any
490 microcontroller with at least 128K of flash), a special EEPROM file
491 system has been implemented. This can for example be used to store a
492 small file browser or fast loader so it can be used independent of the
493 storage medium that is currently inserted.
494
495 The EEPROM file system will always register itself on the last
496 partition number (see "Partitions" below). You can check the list of
497 partitions ("$=P") to find the current partition number of the EEPROM
498 file system or use the alias function (see below) to access it.
499
500 To simplify calculations, block numbers on the EEPROMFS are calculated
501 using 256 bytes per block instead of the usual 254 bytes as used by
502 Commodore drives. Internally, the allocation is even more fine-grained
503 (using 64 byte sectors), which means that the number of free blocks
504 shown on an empty file system may be less than the sum of the number
505 of blocks of all files on a full file system.
506
507 The EEPROM file system does not support subdirectories. It can be
508 formatted using the N: command as usual, but the disk name and ID are
509 ignored. The capacity of the EEPROM file system varies between
510 devices: On AVR devices it is 3.25 KBytes and at most 8 files can be
511 stored on it. On a2iec, the file system can hold 7 KBytes and at most
512 16 files can be stored on it. The actual number of files that can be
513 stored depends on the length of the files, longer files need more than
514 one directory entry.
515
516
517 Partitions:
518 ===========
519 sd2iec features a multi-partition support similiar to that of the CMD
520 drives. The partitions (which may be on separate drives for some hardware
521 configurations) are accessed using the drive number of the commands
522 sent from the computer and are numbered starting with 1. Partition 0
523 is a special case: Because most software doesn't support drive numbers
524 or always sends drive number 0, this partition points to the currently
525 selected partition. By default, accesses to partition 0 will access
526 partition 1, this can be changed by sending "CP<num>" over the command
527 channel with <num> being an ASCII number from 1 to 255. "C<Shift-P"
528 (0x42 0xd0) works the same, but expects a binary partition number as the
529 third character of the command.
530
531 To allow a "stable" access to the EEPROM file system no matter how
532 many partitions are currently available, a special character has been
533 introduced that will always access the EEPROM file system (if
534 available). When sd2iec sees a "!" character where it expects a
535 partition number and the "!" character is directly followed by a colon
536 (i.e. "!:"), it will access the EEPROMFS if available. Direct access
537 using the assigned partition number is of course still
538 available. Additionally "$!" will always load the directory of the
539 EEPROM file system partition (if available), similar to "$1" to "$9"
540 for partitions 1 to 9.
541
542 Software fastloaders:
543 =====================
544 Note: Using sd2iec without an external crystal or similiar precise
545       clock source is not a supported configuration.
546       If you try that anyway, be prepared to suffer from random
547       data corruption. You have been warned.
548       Some fastloader implementations will actively refuse to work
549       if you use an unsuitable clock source.
550
551   Turbodisk
552   ---------
553   Turbodisk is detected by the CRC of its 493 byte long floppy code and
554   the M-E address 0x0303. The same code seems to be used under various names,
555   among them "Turbodisk" (both 2.1 and 2.2) and "Fast-Load".
556   It is not known if there is an NTSC-compatible version of this fastloader.
557
558   Final Cartridge III
559   -------------------
560   Both the fast loader and the fast saver of Final Cartridge III are supported.
561   The FC3 is both PAL and NTSC compatible.
562
563   The slightly different fastloader used for files freezed with the FC3
564   is also supported.
565
566   EXOS V3 and The Beast System
567   ----------------------------
568   Both supported, the loader used by these kernals is very similiar to
569   the FC3 fast loader.
570
571   Action Replay 6
572   ---------------
573   The AR6 reads a byte from the drive rom to check which fastloader it should
574   use. When file-based M-R emulation is disabled sd2iec returns a value that
575   should force the cartridge to use the standard kernal loader instead of its
576   many fastloaders/-savers. This means that accessind sd2iec with
577   file-based rom emulation enabled will fail because the cartridge
578   will enable fastloader that will probably not be recognized.
579
580   Currently the only recognized AR6 fastloader and fastsaver are the
581   ones for the 1581.
582
583   Dreamload
584   ---------
585   Dreamload uses direct track/sector access, so it is only supported
586   on D64 or similiar disk image formats. As sd2iec has to wait for commands
587   from the C64 constantly the disk change buttons may become unresponsive,
588   try multiple times if you need to. Dreamload is a "captive" fastloader,
589   sd2iec stay in Dreamload mode until it receives a "quit loader" command
590   from the C64. To force sd2iec to resume normal operation, hold the disk
591   change button until the red LED turns on (just like sleep mode).
592
593   Please note that Dreamload does not work with more than one device on the
594   serial bus due to the way it uses the ATN line.
595
596   ULoad Model 3
597   -------------
598   ULoad Model 3 uses direct track/sector access, so it is only supported
599   on D64 or similiar disk image formats. Currently there is exactly one
600   supported variant of ULoad Model 3, which is the one used by
601   Ultima 3 Gold. There are no other known variants at this time, but
602   this may change.
603
604   If you are a coder and want to use ULoad Model 3 in your own program,
605   either configure it to produce the same drive code as U3Gold or
606   contact me so we can work out a way to trigger ULoad M3 support
607   without uploading any drive code at all.
608
609   G.I. Joe Loader
610   ---------------
611   Said to be the most-ripped IRQ loader. Unfortunately this is a
612   "captive" fastloader similiar to dreamload (but not restricted
613   to disk images because it is file name-based) and there is no
614   reliable way to detect if the computer has been reset to switch
615   back to the standard protocol. To exit this loader, hold down
616   the disk change button until the red LED turns on, just like
617   sleep mode.
618
619   Epyx FastLoad Cartridge
620   -----------------------
621   ONLY the fast loader from this cartridge is supported, no
622   disk editor/copier/whatever functions.
623
624   GEOS
625   ----
626   GEOS 2.0 can be booted from D64 images made from original disks
627   as well as D41/71/81 images created using geoMakeBoot (make sure to
628   Configure the system for a 1541/1571/1581 before using geoMakeBoot).
629   When file-based M-R emulation is disabled, GEOS may detect sd2iec as
630   a 1541 or 1581, depending on the version of Configure used. This may
631   cause the system to fail to boot, e.g. if sd2iec is detected as a 1581
632   while booting from a D64 disk image. It is recommended to set up file-
633   based M-R emulation when using GEOS to avoid these problems.
634
635   GEOS 1.3 may or may not work - it boots, but wasn't tested in-depth.
636   Gateway seems to work but was not tested beyond booting it from a D64
637   image.
638
639   Using the buttons for changing the current disk image is supported,
640   but do make sure that you only access disk images that the drive
641   type that is selected in GEOS would support (i.e. D64 for a 1541,
642   D64/D71 for a 1571 and D81 for a 1581).
643
644   Wheels
645   ------
646   Wheels can be booted from any disk image type it supports. The correct
647   rom emulation file (XR) MUST be set, especially for CMD HD emulation.
648
649   Do not use the disk change feature to change disk images when HD emulation
650   is in use - Wheels does not check for disk changes on that drive!
651   For other drive types the restrictions on disk image type of GEOS also
652   apply to Wheels.
653
654   ELoad Version 1
655   ---------------
656   This loader was made for EasyProg but may also be used in other programs.
657   It detects and supports the sd2iec natively.
658
659   Maniac Mansion
660   --------------
661   Original versions of Maniac Mansion have an additional copy protection
662   check that is not supported by sd2iec. Please use a cracked version
663   instead - the ones from Gamebase 64 seem to work. Please remember to
664   add an empty D64 for the save/load disk to your swaplist if you want
665   to save your game.
666
667   The game uses a captive loader that unfortunately cannot detect if it
668   should exit automatically - to resume normal operation, you need to
669   hold down the NEXT button until the red LED turns on.
670
671   Zak McKracken
672   -------------
673   Same as Maniac Mansion, but this game only has a code list protection,
674   so images of original disks should work fine.
675
676 JiffyDOS:
677 =========
678 The JiffyDOS protocol has very relaxed timing constraints compared to
679 Turbodisk, but still not as relaxed as the standard Commodore IEC protocol.
680
681 x00 files:
682 ==========
683 P00/S00/U00/R00 files are transparently supported, that means they show
684 up in the directory listing with their internal file name instead of the
685 FAT file name. Renaming them only changes the internal name. The XE
686 command defines if x00 extensions are used when writing files, by
687 default sd2iec uses them for SEQ/USR/REL files but not for PRG.
688 Parsing of x00 files is always enabled even when writing them is not.
689
690 x00 files are recognized by checking both the extension of the file
691 (P/S/U/R with a two-digit suffix) and the header signature.
692
693 Disk Images:
694 ============
695 Disk images are recognized by their file extension (.D64, .D41, .D71, .D81,
696 .DNP) and their file size (must be one of 174848, 175531, 349696, 351062,
697 819200 or a multiple of 65536 for DNP). If the image has an error info block
698 appended it will be used to simulate read errors. Writing to a sector with
699 an error will always work, but it will not clear the indicated error.
700 D81 images with error info blocks are not supported.
701
702 Warning: There is at least one program out there (DirMaster v2.1/Style by
703 THE WIZ) which generates broken DNP files. The usual symptom is that
704 moving from a subdirectory that was created with this program back to
705 its parent directory using CD:_ (left arrow) sets the current directory
706 not to the parent directory, but to an incorrect sector instead. A
707 workaround for this problem in sd2iec would require an unreasonable
708 amount of system resources, so it is recommended to avoid creating
709 subdirectories with this version of DirMaster. It is possible to fix
710 this problem using a hex editor, but the exact process is beyond the scope
711 of this document.
712
713 M2I files:
714 ==========
715 NOTICE: Support for M2I files will be removed in the next release, see
716         the deprecation notices at the top of this file for advice.
717
718 M2I files are fully supported. sd2iec supports SEQ and USR files in this
719 format in addition to PRG and DEL which were already implemented in MMC2IEC.
720 For compatibility reasons the file type is not checked when opening files.
721 Inside an M2I file the files are always shown as 0 (DEL) or 1 blocks
722 because calling stat for every file was slowing down the directory listing
723 too much. For compatibility with existing M2I files the data files do not
724 use P00 headers even when the file type is SEQ or USR.
725
726 REL files:
727 ==========
728 Partial REL file support is implemented. It should work fine for existing
729 files, but creating new files and/or adding records to existing files
730 may fail. REL files in disk images are not supported yet, only as files
731 on a FAT medium. When x00 support is disabled the first byte of a REL
732 file is assumed to be the record length.
733
734 Changing Disk Images
735 ====================
736 Because some programs require more than one disk side there is support
737 for changing the currently mounted disk image with two buttons called
738 NEXT and PREV connected to the AVR.
739
740 If your circuit doesn't have disk change pins/buttons you might be able to
741 add it yourself. In all cases the buttons need to connect the given
742 pins of the chip to ground.
743
744 - For the original MMC2IEC ("larsp"):
745   The NEXT button is in input PA4, the PREV button is on PA5.
746   PA4 is pin 36 on the DIL version of the controller or pin 33 on the
747   surface-mount version. PA5 is pin 35 on DIL, pin 32 on SMD.
748
749 - For Shadowolf's MMC2IEC 1.x PCBs ("sw1"):
750   The NExT button is on input PC4, the PREV button is on PC3.
751   PC4 is pin 26 on the DIL version of the controller or pin 23 on the
752   surface-mount version. PC3 is pin 25 on DIL, pin 22 on SMD.
753
754 - For Shadowolf's sd2iec 1.x PCBs ("sw2"):
755   The two required pins are available on the pin header which runs
756   parallel to the long side of the board. In the documentation of the
757   board, the NEXT button is named "DISKSWITCH", the PREV button is
758   named "RESERVE".
759
760 - Any other circuit without disk change pin on a convenient connector
761   somewhere and no button dedicated to that function: Please check
762   with the supplier of the board and read config.h in the sources
763   to find out how to connect it.
764
765 To use this functionality, you can either create a swap list file
766 yourself or let sd2iec create one for you.
767
768 Creating a swap list
769 --------------------
770 A swap list is a text file with one line per disk image or directory
771 you want to be able to change into. You are not limited to using disk
772 images, a swap list file may also refer to standard directories on the
773 SD card or anything else the CD command of sd2iec will accept.
774
775 The swap list file is relatively tolerant against multiple styles of
776 line-endings, sd2iec should be able to parse the file no matter if you
777 create it on a Windows system, Unix or even the C64 itself - as a side
778 effect, empty lines are also ignored. By default sd2iec assumes that
779 the file is encoded in ASCII (for files created on a PC or similar),
780 but if the first line of the file exactly reads "#PETSCII" (in hex: 23
781 50 45 54 53 43 49 49), file names are assumed to be encoded in PETSCII
782 instead and this marker line is skipped.
783
784 An example swap list file could look like this:
785 === example 1 ===
786 FOO.D64
787 BAR.D64
788 BAZ.D64
789 === end of example 1 ===
790
791 === example 2 ===
792 //NEATGAME/:DISK1A.D64
793 //NEATGAME/:DISK1B.D64
794 //NEATGAME/:DISK2A.D64
795 //NEATGAME/:DISK2B.D64
796 === end of example 2 ===
797
798 The swap list is enabled by sending "XS:filename" over the command
799 channel with filename being the name of the swap list. A list
800 activated in this way stays active until you explicitly disable it
801 again by sending "XS" on the command channel or you manually activate
802 another swap list with "XS:otherfilename".
803
804 Since the manual activation of swap lists is still a bit of a hassle,
805 sd2iec will automatically try to activate a swap list named
806 "AUTOSWAP.LST" in the current directory if you use the disk change
807 buttons while no swap list is active. A swap list enabled in this way
808 behaves almost exactly as a swap list enabled with XS, but it
809 auto-deactivates when a CD (change directory) command is received by
810 sd2iec. This way a different AUTOSWAP.LST file is always correctly
811 recognized after you have changed into a different directory.
812
813 sd2iec can even auto-generate a swap list for you that contains all
814 disk images (e.g. D64/D71/D81/DNP) in the current directory if no
815 AUTOSWAP.LST is present in this directory. To do so, change into the
816 directory that you want scanned and use the HOME function (see below).
817 sd2iec will then create a file called AUTOSWAP.GEN and activate it as
818 if it was the standard AUTOSWAP.LST, including its auto-deactivation
819 features. The AUTOSWAP.GEN file will never be recognized the same way
820 as AUTOSWAP.LST, so you will need to either rename the file
821 (R:AUTOSWAP.LST=AUTOSWAP.GEN) or ask sd2iec to generate it again by
822 using the HOME function in the same directory if you want to use it
823 again. This mode of operation was chosen to avoid the accidental
824 destruction of pre-existing AUTOSWAP.LST files and to allow sd2iec to
825 recognize newly-added disk images in the directory without manually
826 removing the generated swap list.
827
828 Please note that using the swap-list auto generation feature will
829 currently leave an empty AUTOSWAP.GEN file on the card if no disk
830 images were found. This may be fixed in the future.
831
832 Using a swap list
833 -----------------
834 Navigation in a swap list is really simple: Press the NEXT button to
835 activate the next line of the file or the PREV button to activate the
836 previous line of the file. Both of these buttons wrap to the other end
837 of the file if they hit the beginning/end of the list. You can also
838 hit both buttons together to trigger the HOME function which jumps to
839 the first entry of the swap list.
840
841 sd2iec will confirm each of these three actions with a specific
842 flashing pattern on the device's LEDs. The pattern first flashed both
843 the red and green LEDs on for a short moment, then it flashes either
844 one or both of them. For the NEXT function, the green LED flashes; for
845 the PREV function the red LED flashes and for HOME both LEDs flash.
846
847 If any of these three functions is activated without an active swap
848 list and sd2iec finds an AUTOSWAP.LST file, they will all be treated
849 as the HOME function: The first line of the file is active and the
850 red and green LEDs both flash twice. The same happens when an
851 AUTOSWAP.GEN file is created, although the flashing pattern may not be
852 very discernible because of the preceding card activity.
853
854
855 Sleep Mode:
856 ===========
857 If you hold the disk change button down for two seconds, sd2iec will
858 enter "sleep mode". In this mode it doesn't listen to the bus at all
859 until you hold down the disk change button for two seconds again
860 which resumes normal operation. Sleep mode allows you to keep
861 sd2iec connected to the serial bus even when you load something
862 from a different drive that uses a fast loader that doesn't
863 work with more than one device on the bus.
864
865 While sleep mode is active, the red LED will be on and the green LED
866 will be off.
867
868 Card detection test:
869 ====================
870 Because some SD slots seem to suffer from bad/unreliable card detect
871 switches a test mode for this has been implemented on the units that
872 have SD card support. If you hold down the PREV button during powerup,
873 the red (dirty) LED will reflect the card detect status - if the LED
874 is on the card detect switch is closed. Please note that this does not
875 indicate successful communication with the card but merely that the
876 mechanical switch in the SD card slot is closed.
877
878 On units with two sd2iec-controlled LEDs, the green (busy) LED will
879 indicate the state of the write protect switch - if the LED is lit,
880 the write protection is on. Due to the way the write protect notch
881 works on SD cards, the indication is only valid when the card is fully
882 inserted into the slot.
883
884 To exit from the diagnostic mode, power-cycle the device or push the
885 NEXT button once.
886
887 Other important notes:
888 ======================
889 - When you hold down the disk change (forward) button during power
890   on the software will use default values instead of those stored
891   in the EEPROM.
892 - File overwrite (@foo) is implemented by deleting the file first.
893 - File sizes in the directory are in blocks (of 254 bytes), but
894   the blocks free message actually reports free clusters. It is
895   a compromise of compatibility, accuracy and code size.
896 - If known, the low byte of the next line link pointer of the directory
897   listing will be set to (filesize MOD 254)+2, so you can calculate the
898   true size of the file if required. The 2 is added so it can never be
899   mistaken for an end marker (0) or for the default value (1, used by at
900   least the 1541 and 1571 disk drives).
901 - If your hardware supports more than one SD card, changing either one
902   will reset the current partition to 1 and the current directory of
903   all partitions to the root drive. Doing this just for the card that
904   was changed would cause lots of problems if the number of partitions
905   on the previous and the newly inserted cards are different.
906
907 Compilation notes:
908 ==================
909 sd2iec requires avr-libc version 1.6.x.
910
911 sd2iec is set up to be compiled in multiple configurations, controlled by
912 configuration files. By default the Makefile looks for a file named
913 'config', but you can override it by providing the name on the make
914 command line with "make CONFIG=filename[,filename...]".
915
916 An example configuration file named "config-example" is provided with
917 the source code, as well as abridged files corresponding to the
918 release binaries. If you want to compile sd2iec for a custom hardware
919 you may have to edit config.h too to change the port definitions.