revert between 56095 -> 55830 in arch
[AROS.git] / rom / filesys / CDVDFS / CDVDFS.guide
blob62b7691aaac5b0d57d33ab635291c6075d14a9ec
1 @database "CDVDFS.guide"
3 @node main "CDVDFS Table Of Contents"
5 CDVDFS - a CD/DVD filesystem for Amiga family of operaing systems
6 -----------------------------------------------------------------
8 Version 1.4    16-Jun-08   (C) 2007-2008 Pavel Fedin
9                            (sonic_amiga@rambler.ru)
11 Based on AmiCDROM 1.15     (C) 1993,1994 by Frank Munkert
12                            (ln_fmu@pki-nbg.philips.de)
14 * IMPORTANT NOTICE FOR USERS OF AMICDROM:
16 * The format of the Mountlist has been changed.
17 * Please consult the section "USAGE" for further information.
19 Table of Contents:
21         @{"INTRODUCTION" link "INTRODUCTION"}     -  Introduction to CDVDFS
22         @{"DISCLAIMER" link "DISCLAIMER"}         -  Standard Disclaimer
23         @{"LEGAL" link "LEGAL"}           -  Copyrights and distribution
24         @{"REQUIREMENTS" link "REQUIREMENTS"}     -  CDVDFS Requirements
25         @{"INSTALLATION" link "INSTALLATION"}     -  Installing CDVDFS
26         @{"USAGE" link "USAGE"}           -  Using CDVDFS
27         @{"FILENAMES" link "FILENAMES"}   -  CDROM Filenames (ISO-9660, RockRidge and Joliet)
28         @{"SYMLINKS" link "SYMLINKS"}     -  Symbolic links on Rockridge disks
29         @{"DISKCHANGE" link "DISKCHANGE"}         -  Diskchange recognition
30         @{"MACHFS" link "MACHFS"}                 -  Macintosh HFS format
31         @{"AUDIO" link "AUDIO"}           -  Audio disks (CD-DA)
32         @{"MULTISESSION" link "MULTISESSION"}     -  Multisession Support
33         @{"CDCONTROL" link "CDCONTROL"}   -  The 'CDCONTROL' Program
34         @{"CDROM" link "CDROM"}           -  The 'CDROM' Program
35         @{"CHECKCD" link "CHECKCD"}               -  The 'CHECKCD' Program
36         @{"KILLDEVICE" link "KILLDEVICE"}         -  The 'KILLDEVICE' Program (MorphOS only)
37         @{"TROUBLESHOOTING" link "TROUBLESHOOTING"}       -  Troubleshooting
38         @{"UTILITIES" link "UTILITIES"}   -  Other utilities of interest
39         @{"THANKS" link "THANKS"}                 -  Thanks must go to..
40         @{"BUGS" link "BUGS"}             -  Bugs and not supported features
41         @{"TODO" link "TODO"}             -  Things still to do
42         @{"HISTORY" link "HISTORY"}               -  History of CDVDFS
44 @endnode
46 @node INTRODUCTION "Introduction to CDVDFS"
48   CDVDFS is a CD/DVD disk filing system for the Amiga family of operating
49   systems (AmigaOS, MorphOS and AROS). It supports the ISO-9660 standard
50   (single and multiple sessions), the Rock Ridge Interchange Protocol, the
51   Joliet extension and the Macintosh HFS format.
53   The CDROM drive is mounted as a DOS device (e.g. CD0:). You
54   can access files and directories on a CDROM disk by the usual
55   syntax, e.g. "type cd0:foo/readme.txt".
57 @endnode
59 @node DISCLAIMER "Standard Disclaimer"
61   This software is provided as-is, without warranty of any kind,
62   either expressed or implied. In no event will the author be liable
63   for direct, indirect, incidental or consequential damages or data
64   loss resulting from the use or application of this software. The
65   entire risk as to the results and performance of this software is
66   assumed by the user.
68 @endnode
70 @node LEGAL "Copyrights and distribution"
72   CDVDFS author is Pavel Fedin (sonic_amiga@rambler.ru).
73   CDVDFS is a forked project based on AmiCDROM v1.15.
75   AmiCDROM 1.15 is (C) Copyright 1993,1994 by Frank Munkert.
76   All rights reserved.
77   This software may be freely distributed and redistributed for
78   non-commercial purposes, provided this notice is included.
80   There are no objections to anyone using or enhancing this code.
82 @endnode
84 @node REQUIREMENTS "CDVDFS Requirements"
86   CDVDFS should work with:
87   
88   1) Any "SCSI-direct" compatible SCSI bus adapter.
89   2) Any IDE adapter whose driver supports "SCSI-direct" (this means passing
90      through special commands for CD-ROM drives whose protocol is similar to
91      SCSI).
92   3) It might also work with old SCSI drivers that have no SCSI-direct feature;
93      see 'T' option.)
95   The running handler requires about 60K of memory (with default parameter
96   settings).
98   If you are using a GVP controller, you probably will have to disable
99   the "disconnect/reconnect" feature; see your SCSI controller manual.
101   Users of the Pioneer drives DRM600 and DRM602 possibly have to add
102   the option SI=0 to the Control field.
104   CDVDFS and its precedessor AmiCDROM have been tested on the following
105   hardware and software configurations:
107    * Amiga 500 + GVP A500-HD+ + NEC 3Xp (CDR-400) + AmiCDROM 1.11
108    * Amiga 500 + Trumpcard + NEC CDR-25 + AmiCDROM 1.7
109    * Amiga 500 + Blizzard w Supra 500XP contr + Apple CD300 +
110          AmiCDROM 1.6
111    * Amiga 500 + GVP Series II + Toshiba 4101 + AmiCDROM 1.8
112    * Amiga 500 + cdtv.device + A570 + AmiCDROM 1.7
113    * Amiga 2000 + GForce030 + Apple PowerCD + AmiCDROM 1.8 and 1.9
114    * Amiga 2000 + GVP Series II V4.13 + NEC CDR-55JD + AmiCDROM 1.4
115    * Amiga 2000 + GVP Series II + Apple CD-300 + AmiCDROM 1.4
116    * Amiga 2000 + GVP Series I + Toshiba 3401 + AmiCDROM 1.8
117    * Amiga 2000 + GVP 030 & internal SCSI II host adapter + Sony CDU-561 +
118          AmiCDROM 1.7
119    * Amiga 2000 + Masoboshi MasterCard + Toshiba 3401 + AmiCDROM 1.6
120    * Amiga 2000 + ICD Advantage 2000 + Apple CD150 + AmiCDROM 1.4
121    * Amiga 2000 + A2091 SCSI Controller + NEC CDR-37 + AmiCDROM 1.12
122    * Amiga 2000 + A2091 SCSI controller + NEC CDR-55JD-1 + AmiCDROM 1.4
123    * Amiga 2000 + GVP Series II (v4.13) + NEC CDR-55JD-1 + AmiCDROM 1.7
124    * Amiga 2000 + GVP Series II + Apple CD300 + AmiCDROM 1.9
125    * Amiga 2000 + A2091 SCSI controller + Toshiba 3301 + AmiCDROM 1.6
126    * Amiga 2000 + A2091 SCSI controller + Sony CDU-561 + AmiCDROM 1.7
127    * Amiga 2000 + Evolution-Controller (V3.x) + Toshiba 3401 +
128          AmiCDROM 1.4
129    * Amiga 2500 + A2091 SCSI controller + Apple CD300 + AmiCDROM 1.4
130    * Amiga 3000 + internal SCSI device + Toshiba 3301 + AmiCDROM 1.7
131    * Amiga 3000 + internal SCSI device + Toshiba 3401 + AmiCDROM 1.9
132    * Amiga 3000 + internal SCSI device + Chinon 435 + AmiCDROM 1.4
133    * Amiga 3000 + internal SCSI device + NEC CDR 84-1 + AmiCDROM 1.4
134    * Amiga 3000 (WD-08 Chip) + internal SCSI device + Apple CD150 +
135           AmiCDROM 1.7
136    * Amiga 3000 + internal SCSI device + Apple CD300 + AmiCDROM 1.7
137    * Amiga 3000 (Mercury '040, WD-08 Chip) + internal SCSI device +
138           Apple CD300 + AmiCDROM 1.7
139    * Amiga 3000 + internal SCSI device + Texel DM5028 + AmiCDROM 1.7
140    * Amiga 3000 + internal SCSI + NEC 3Xp + AmiCDROM 1.7
141    * Amiga 3000 + internal SCSI device + Pioneer DRM-604X QuadSpeed Changer +
142           AmiCDROM 1.9
143      [works partly]
144    * Amiga 3000 + Commodore 2091 + Toshiba 2100/3200 + AmiCDROM 1.7
145    * Amiga 3000 + Emplant w SCSI (using empscsi.device) + Apple CD 300 +
146          AmiCDROM 1.7
147    * Amiga 4000 + GVP Series I + Toshiba 3401 + AmiCDROM 1.8
148    * Amiga 4000 + Commodore 2091 SCSI controller + Toshiba 3401 +
149          AmiCDROM 1.7
150    * Amiga 4000 + Fastlane SCSI II + Toshiba 3401 + AmiCDROM 1.2
151    * Amiga 4000 + Fastlane Z3 SCSI Host Adapter + Apple CD-300 +
152          AmiCDROM 1.4-1.7
153    * Amiga 4000 + A4091 + Apple CD300 + AmiCDROM 1.7
154    * Amiga 4000 + Golem SCSI controller + Toshiba 3401 + AmiCDROM 1.7
155    * Amiga 4000/30 + DataFlyer + Apple SC + AmiCDROM 1.7
156    * Amiga 4000 + Commodore A2091 SCSI controller + NEC 3Xp + AmiCDROM 1.7
157    * Amiga 4000/040 + Oktagon 2008 + Toshiba 3401 + AmiCDROM 1.9
158    * Amiga 4000 + WarpEngine40/28 + Toshiba 3401 + AmiCDROM ?.?
159    * Amiga 4000 + A4091 SCSI controller + NEC 3Xi (CDR-500) + AmiCDROM ?.?
160      [ but: audio support does not work + READ TOC command has funny results ]
161    * Amiga ???? + Oktagon 2008 + Teac CD-50 / Pioneer DRM600 / DRM602 +
162         AmiCDROM 1.10
163    * Pegasos-II + Samsung SM-352N CDRW+DVD-R combo drive + MorphOS 1.4.5 +
164         CDVDFS 1.3
166 The following hardware setups have been reported not to work:
168    * Amiga 2000 + GVP Series I + Toshiba 3401 + AmiCDROM 1.6
169    * Amiga 2000 + GVP Series II (v4.13) + NEC CDR-55JD-1 + AmiCDROM 1.8/1.9
170    * Amiga 2000 + GVP combo 68030/gvpscsi 3.12 + Toshiba 3401 + AmiCDROM 1.6
171    * Amiga 2000 + G-Force-030/gvpscsi 4.5 + Toshiba 3401 + AmiCDROM 1.6
172    * Amiga 2000 + ICD Advantage 2000 + Apple CD150 + AmiCDROM 1.6
173    * Amiga 2000 + Amiga 2000 Vector Acc w SCSI port + Nec MultiSpin 3Xp +
174          AmiCDROM 1.7
175    * AmiCDROM <= 1.7 + Digital RDD40  (will be fixed in AmiCDROM 1.8)
176    * Amiga 3000 + EMPLANT with SCSI (using empscsi.device) + 
177          Texel DM5024 drive + AmiCDROM 1.6
178    * Amiga 3000 (with 68040 acc) + internal SCSI device + Texel CDROM +
179          AmiCDROM 1.4
180    * Amiga 3000 + internal SCSI device + Apple CD300 + AmiCDROM 1.6
181      [works partially]
182    * Amiga 3000 + internal SCSI device (WD-08) + Apple CD150 + AmiCDROM 1.8
184 The following hardware setups have been reported to work for some users
185 and not to work for other users:
187    * Amiga 2000 + Evolution-Controller (V3.x) + Toshiba 3401 +
188          AmiCDROM 1.6/1.7
189 @endnode
191 @node INSTALLATION "Installing CDVDFS"
193   On AROS CDVDFS is the part of bootimage and does not need any
194   installation. It works automatically out of the box by default.
196   On other systems you can perform the installation as follows:
198   1. Copy the 'cdrom-handler' file to L:cdrom-handler.
200   2. @{"If you use Workbench 2.0" link "2.0"}
201      @{"If you use Workbench 2.1 or higher or MorphOS" link "2.1"}
204      @{"Control" link "startup"} - The 'Control' field
206 @endnode
209 @node 2.0 "Installation on 2.0 systems"
211      Create an entry in DEVS:MountList like this:
213      CD0:       FileSystem     = L:cdrom-handler
214                 Stacksize      = 10000
215                 Priority       = 5
216                 GlobVec        = -1
217                 Mount          = 1
218                 BufMemType     = 0
219                 Device         = scsi.device
220                 Unit           = 1
221                 LowCyl         = 0
222                 HighCyl        = 0
223                 Surfaces       = 1
224                 BlocksPerTrack = 1
225                 DosType        = 0x43444653
226                 Control        = "ROCKRIDGE LOWERCASE" /* see below */
227      #
229      You can choose any name you like for "CD0".
231      Install the handler in DOS using the CLI command "Mount CD0:".
232      If there is a problem during mounting, CDVDFS will put up a
233      requester with an error message.
234      If you use CDVDFS regularily, you might consider to put
235      "Mount CD0:" in the user startup-sequence.
237 @endnode
239 @node 2.1 "Installation on 2.1 and higher systems and MorphOS"
241      Edit the file CD0. It contains a Mountlist as described in step 2a
242      (with the exception that "CD0:" and "#" are missing).
243      If you don't like the name "CD0", rename this file and the file
244      CD0.info. Use the Workbench to move the icon CD0 into the drawer
245      sys:Storage/DOSDrivers. Now enter the command "Mount CD0:" to
246      install the handler.
247      If you use CDVDFS regularily, you might consider to put
248      the icon in the drawer WBStartup or Devs:DOSDrivers; all files in these
249      drawers will be mounted at startup. If the icon is in the WBStartup
250      drawer, the Workbench will not wait until "CD0:" is mounted; if the
251      icon is in Devs:DOSDrivers, the Workbench will wait. The first
252      method is recommendable if you want your system to come up as fast
253      as possible. The second method has to be used if you want to refer
254      to "CD0:" in your s:user-startup sequence.
255      
256   IMPORTANT:
257      Make sure, that all assigned volume names (such as "L:") are known
258      at the time of mounting. Otherwise, the handler will not be
259      mounted, and no error message will be issued.
260      
261      If you have put CD0 into DEVS:DosDrivers and the handler does not
262      auto-mount, then you probably have a wrong filename in the 'Handler'
263      or 'Device' field.
265   IMPORTANT FOR MORPHOS:
266      If you wish to completely replace MorphOS internal CD-ROM handler
267      with CDVDFS you need to use "KillDevice" utility to remove built-in
268      handler before installing this one. In order to do this you'll have
269      to insert "KillDevice" command into MOSSYS:S/Startup-Sequence file
270      before the line:
272      Mount >NIL: MOSSYS:Devs/DOSDrivers/~(#?.info) DEVS:DOSDrivers/~(#?.info)
274      So that this would look like:
276      KillDevice CD0:
277      Mount >NIL: MOSSYS:Devs/DOSDrivers/~(#?.info) DEVS:DOSDrivers/~(#?.info)
279      This assumes that you put CD0 into DEVS:DOSDrivers directory.
281      Also, be sure that Mountlist for CDVDFS contains "ForceLoad = 1"
282      parameter, otherwise builtin MorphOS CD-ROM handler will be used for the
283      device instead of CDVDFS.
285      If you don't wish to remove MorphOS builtin handler you'll need to
286      choose another name for CDVDFS, for example ACD0.
288 @endnode
290 @node startup "The 'Control' field"
292   The 'Control' field in the MountList is a string with the following
293   template:
295     RETRY/S,L=LOWERCASE/S,ML=MAYBELOWERCASE/S,
296     R=ROCKRIDGE/S,J=JOLIET/S,MI=MACTOISO/S,CS=CONVERTSPACES/S,
297     SV=SHOWVERSION/S,HF=HFSFIRST/S,FB=FILEBUFFERS/K/N,
298     DE=DATAEXT/K,RE=RESOURCEEXT/K,SI=SCANINTERVAL/K/N,PC=PLAYCDDA/K,
299     X=XPOS/K/N,Y=YPOS/K/N,UT=UNICODETABLE/K
301   The following options may be used:
302   
303   L            Map ISO-9660 names to lower case
304   LOWERCASE
305   
306   ML           Do not convert the filenames if the CDROM is a 
307   MAYBE-       CDTV or CD32 disk, or a disk created by Mkisofs.
308   LOWERCASE    Otherwise, map the filenames to lower case.
309                (LOWERCASE and MAYBELOWERCASE are mutually exclusive.)
311   R            Use Rock Ridge file names, if possible.
312   ROCKRIDGE
314   J            Use Joliet file names, if possible.
315   JOLIET
317   MI           Convert Mac characters into ISO-Latin-1 (Amiga) characters.
318   MACTOISO     (The conversion applies only to the filenames, not to
319                the contents of the files.) Additionally, the character
320                ':' will be converted into a '.', and '/' will be
321                converted into '-'; this is necessary because AmigaDOS cannot
322                handle filenames containing those characters.
324   CS           Convert spaces in MacHFS filenames into underscores ('_').
325   CONVERTSPACES
326   
327   SV           Show version numbers.
328   SHOWVERSION
329   
330   HF           If a new disk is mounted, CDVDFS normally tests first
331   HFSFIRST     if the new disk is a ISO-9660 disk. If the option "HF"
332                is given, then the disk is first examined for a HFS
333                partition.
334                This option is useful if you have a "multi-platform"
335                disk with both a ISO-9660 and a HFS partition. Without
336                the option you get the ISO partition; with the option
337                you get the HFS partition.
339   FB           Number of 2048 byte buffers for file access with the
340   FILEBUFFERS  AmigaDOS Read() call. Default = the same as specified in
341                "Buffers" keyword of the mountlist.
343   DE           Extension for the data fork of a file on MacHFS disks.
344   DATAEXT
346   RE           Extension for the resource fork of a file on MacHFS disks.
347   RESOURCEEXT  (If neither DE nor RE are given, DE is set to the empty
348                string and RE is set to ".rsrc".)
350   SI           Time between two successive diskchange checks.
351   SCANINTERVAL Default = 3 seconds.
352                If the value of this option is 0, then no diskchange
353                checks will be performed; in this case, you have to use
354                the DISKCHANGE command in order to inform CDVDFS that
355                a disk has been changed.
357   PC           Name of the command to be executed if the user double-
358   PLAYCDDA     clicks at the "CD-DA" icon. If you want to execute
359                a command with parameters, you have to create
360                a script file containing the command plus parameters.
361                The name of the script file has to be passed as an
362                argument to the PC option. Don't forget to set the
363                "S" protection bit of the script file.
365   X            X position of CD-DA icon. (Default: WB selects position.)
366   XPOS
368   Y            Y position of CD-DA icon. (Default: WB selects position.)
369   YPOS
371   UT           Specify file name of Unicode translation table used
372   UNICODETABLE to translate national characters on Joliet disks.
373                These tables are standard Unicode mappings, the same as,
374                for example, supplied with codesets.library. You can
375                find more of them at http://www.unicode.org.
376   
377   RETRY        Report no error if the CDROM drive is switched off while
378                mounting the filesystem. The "mount" program will hang until
379                the CDROM drive is switched on.
381   I recommend to specify at least MAYBELOWERCASE, ROCKRIDGE and JOLIET , for
382   better readability.
384   Examples:
385   
386          Control = "ROCKRIDGE FB=10 DE=.1 RE=.2"
388     Use Rock Ridge if possible and use 10 buffers for file access (FB=10).
389     In HFS filenames, mark the data fork with the extension ".1" (DE=.1)
390     and the resource fork with the extension ".2" (RE=.2).
392          Control = "ROCKRIDGE JOLIET UT=LIBS:Charsets/windows-1251.txt"
394     Use RockRidge or Joliet if possible and use windows-1251 Unicode conversion
395     table (this table defines russian character set).
397   Older Mount commands (e.g. those distributed with Workbench 2.0)
398   cannot handle space characters and "=" signs within startup
399   parameters. In CDVDFS, the following workaround has been made
400   available: every '+' sign will be replaced internally by a space
401   character. This means that
402   
403          Control = "ROCKRIDGE+FB+10+DE+.1+RE+.2"
405   is equivalent to the example above.
407   If you really need a '+' character in the control field (e.g. if
408   yoy want to append ".+res" and ".+data" to HFS file names), then you have
409   to write '++' instead of '+', e.g.
410   
411          Control = "DE+.++data+RE+.++res"
413 @endnode
415 @node USAGE "Using CDVDFS"
417   You may use "CD0:" as if it were an ordinary volume, i.e. you may
418   execute commands such as:
419   
420          dir cd0:
421          cd cd0:
422          type cd0:readme.txt
423   
425 @endnode
427 @node FILENAMES "CDROM Filenames (ISO-9660, RockRidge and Joliet)"
429   A standard CDROM disk ("volume") contains a ISO-9660 directory tree.
430   ISO file names have the following format:
432                 FILENAME.EXTENSION;VERSION
434   e.g.  README.TXT;1
436   The filenames may contain upper-case letters, digits and underscores.
438   CDVDFS normally ignores the version number of a file. If you
439   specify the option "SV", however, the version numbers will be
440   displayed. If you have to supply a file name, you may or may not
441   specify a version number. E.g. in order to type the contents of the file
442   README.TXT;1 you might use one of the following commands:
443   
444                 type readme.txt
445                 type "readme.txt;1"
447   (don't forget the quotation marks!)
448   If a directory contains more than one file with the same name (and
449   different version numbers), then you have to supply the version number
450   in order to be able to choose the version you want.
452   Filenames may be mapped to lower-case by specifying the control option "L".
453   Lower-case names are generally easier to read than upper-case names.
455   ISO filenames have a limited length and format. To overcome this
456   restriction, the Rock Ridge Group has devised the Rock Ridge Interchange
457   Protocol which allows arbitrary filenames. Rock Ridge filenames
458   are stored in so-called "system use areas" within the ISO-9660
459   filesystem.
460   
461   By specifying the control option "R", CDVDFS recognizes Rock Ridge
462   filenames on a Rock Ridge CDROM disk.
464 @endnode
466 @node SYMLINKS "Symbolic links on Rockridge disks"
468   The Rock Ridge protocol standard also defines so-called symbolic links.
469   A symbolic link is a file A which contains the filename of another
470   file B. Whenever the name of file A is used, file B will be accessed.
471   
472   CDVDFS maps symbolic links to AmigaDOS soft links. The soft links as
473   specified and implemented in AmigaDOS 2.1/3.0, however, do not work
474   very well. Actually, soft links are not officially supported by Commodore.
475   You most probably will encounter problems, if you use path names which
476   contain soft links in their middle. Therefore, you should always ensure that
477   the soft link part of the path name is the last part, i.e.
478   use "cd cd0:foo/soft" and "cd bar" instead of "cd cd0:foo/soft/bar", if
479   "soft" is a soft link.
481   The AmigaDOS comment field for symbolic links will be set to "Symbolic Link".
482   Therefore, you may use the "list" command in order to identify symbolic
483   links. If you want to know what the target file of a symbolic link is,
484   then you might use the command "cdrom o <symlink-name>".
486 @endnode
488 @node DISKCHANGE "Diskchange recognition"
490   In order to recognize a "disk changed" condition, the CDROM drive is
491   periodically (each 3 seconds) queried by the filesystem handler.
492   
493   On some Amigas this may cause the "Hard Disk" LED to flash every
494   3 seconds. Obviously, the "Hard Disk" LED isn't actually connected to
495   a hard disk drive; it is simply an indicator for SCSI bus activity.
497   The time between two successive diskchange checks can be modified
498   with the SCANINTERVAL option. If this option is set to 0, no diskchange
499   checks will be performed. This might especially be useful for BBS
500   systems, where disks aren't changed very often.
502   You may force a diskchange check with the AmigaDOS DISKCHANGE
503   command, e.g. "DISKCHANGE CD0:".
505 @endnode
507 @node MACHFS "Macintosh HFS format"
509   Each MacHFS file consists of two parts: a "data fork" and a "resource
510   fork". Each fork may be regarded as an individual file. Both the
511   data fork and the resource fork may be empty.
513   CDVDFS treats each fork as an individual file. While other CDROM
514   filesystems may require you to switch between the modes "show only
515   data forks" and "show only resource forks", CDVDFS displays both
516   data and resource forks in one directory. If either of the two forks
517   is empty, it will not be displayed.
519   By default, the resource fork is marked with the extension ".rsrc".
520   You may change the extensions with the options DATAEXT and RESOURCEEXT.
522   MacHFS file names tend to contain lots of space characters. If you
523   don't like this, you may use the switch CONVERTSPACES to convert
524   all space characters into underscores.
525   
526   The Macintosh uses a slightly different character set than the
527   Amiga. The upper 128 characters in the Amiga character set
528   correspond to the ISO-Latin-1 standard. The upper 128 characters in
529   the Macintosh character set, however, are specific to the Mac.
530   If you want to convert Mac characters in filenames into ISO-Latin-1
531   characters, you should use the MACTOISO option.
533 @endnode
535 @node AUDIO "Audio disks (CD-DA)"
537   If a disk that contains one or more audio tracks is inserted into the
538   drive, CDVDFS will display an icon with the name "CD-DA". If you
539   double-click on this icon, the CDROM drive will start to play the
540   first track on the disk. If you double-click on this icon again, the
541   CDROM drive stops playing.
543   If you want to use a more sophisticated way to handle audio disks,
544   you may provide the name of a CD-DA player program as an argument
545   to the PLAYCDDA option. Recommendable programs are "JukeBox" by
546   F-J. Reichert, which uses a CD-player like user-interface,
547   "CDDA" by Olaf Barthel (for an Apple CD-300) and "PlayCDDA" by
548   Frank Munkert and Heiko Rath. PlayCDDA V1.1 is suitable only
549   for Toshiba 3401 and Apple CD-300 drives; these drives can send CD-DA
550   data over the SCSI bus. PlayCDDA reproduces the sound which is recorded
551   on the disk on the Amiga's audio.device.
553   The position of the CD-DA icon on the Workbench can be modified with
554   the options XPOS and YPOS.
556   If you do not like the default CD-DA icon, then you might create an
557   icon in the file "ENV:cdda.info". Then this icon will be used by
558   CDVDFS. The tooltype argument "ICONNAME" will be used as a replacement
559   for the default icon name ("CD-DA"). An example icon can be found in the
560   drawer "icons" in the CDVDFS distribution.
562   You can use this feature only if your CDROM drive supports audio commands.
563   If you only have a SCSI-1 CDROM drive, you probably also won't be able to
564   use this feature (use "cdrom a" to test whether or not you have a SCSI-1
565   drive).
567 @endnode
569 @node MULTISESSION "Multisession Support"
571   Some CD-ROMs, such as PhotoCDs, can be recorded in multiple sessions.
572   If your CD-ROM drive supports extended architecture (XA) disks and
573   can read multiple sessions, then CDVDFS will show you always the
574   latest session.
576   If you only have a SCSI-1 CDROM drive, you probably won't be able
577   to use this feature (use "cdrom a" to test whether or not you have a SCSI-1
578   drive).
580 @endnode
582 @node CDCONTROL "The 'CDCONTROL' Program"
583   
584   The 'cdcontrol' lets the user change parameters of the CDROM handler
585   while the handler is running. These changes are only temporary, and
586   persist only as long as the handler is running.
587   
588   'cdcontrol' is invoked as
589   
590        cdcontrol device: command
591   
592   where 'command' may be one of the following commands:
593   
594     lowercase on        Convert ISO filenames to lowercase
595     
596     lowercase off       Don't convert ISO filenames
598     mactoiso on         Convert Mac to Amiga characters
599     
600     mactoiso off        Don't convert Mac filenames
601     
602     convertspaces on    Convert HFS spaces into underscores
603     
604     convertspaces off   Don't convert spaces in HFS filenames
605     
606     hfsfirst on         Look for a HFS partition first
607     
608     hfsfirst off        Look for an ISO partition first
609     
610     dataext <name>      Set extension for HFS data forks
611     
612     resourceext <name>  Set extension for HFS resource forks
614     unicodetable <name> Load Joliet character set conversion table
615                         (use special name "none" in order to use
616                         defauit built-in Latin-1 table)
618   Examples:
619   
620     cdcontrol CD0: dataext ".data"
621     cdcontrol CD0: unicodetable "L:FileSystem_Trans/windows-1251.txt"
623   All command names may be abbreviated to the one- or two-letter
624   abbreviations shown in the section "The 'Control' field".
627 @endnode
629 @node CDROM "THE 'CDROM' PROGRAM"
631   The 'cdrom' program is mainly for developers of CDVDFS.
632   However, there are some features which might be useful to
633   everyone.
634   
635   In order to use 'cdrom' you have to set the following
636   environment variables:
637   
638      CDROM_DEVICE       Name of your SCSI device, e.g. "scsi.device"
639      
640      CDROM_UNIT         SCSI-ID of your CDROM drive, e.g. "2"
642      CDROM_FASTMEM      Has to be set to any value if you want to use
643                         fast memory instead of chip memory for buffers.
645      CDROM_UNICODETABLE Name of character conversion table for Joliet disks.
647   Here are some useful commands:
648   
649      cdrom a          Show information on the CDROM drive.
650   
651      cdrom d[rl] dir  Show directory 'dir'.
652                       Option r: also show subdirectories.
653                       Option l: show additional information.
655      cdrom e[rlL] dir Show directory 'dir' using Rock Ridge names.
656                       Option r: also show subdirectories.
657                       Option l: show names of system use fields.
658                       Option L: show names and contents of system use fields.
660      cdrom i          Show the format (ISO, RR, J or HFS) of the current disk.
661      
662      cdrom s num      Read the contents of sector 'num'.
664      cdrom v          Show the primary volume descriptor of the CDROM disk.
665      
666      cdrom z          Test if the CDROM drive is ready.
668 @endnode
670 @node CHECKCD "The 'CHECKCD' Program"
672   Checkcd performs some consistency checks on an ISO 9660 disk.
673   Set the options CDROM_DEVICE, CDROM_FASTMEM and CDROM_UNICODETABLE as
674   described in the previous section and invoke "checkcd" without arguments.
675   The test may take up to 20 minutes, depending on the complexity of
676   your CD.
678 @endnode
680 @node KILLDEVICE "The 'KILLDEVICE' Program"
682   Unfortunately MorphOS operating system has a problem - it can't dismount
683   handlers correctly. KillDevice is a hack which allows you to remove
684   existing CD-ROM handler in order to replace it with CDVDFS.
686   Note that it is REALLY A HACK! It actually rips off the device from
687   the system, and not shuts it down in somehow friendly manner. I hope
688   some day this problem will be fixed and this tool will not be needed any
689   more.
691   The only argument for KillDevice is physical device name:
693      killdevice cd0:
695   This program exists only in MorphOS version of the package. It is simply
696   not useful on other systems due to its weird nature.
698 @endnode
700 @node TROUBLESHOOTING "Troubleshooting"
702   Q: My Amiga crashes if I mount the CD0 device.
703   A: Possibly your SCSI driver does not support the selected
704      access method. Play around with the options "CHIP", "FAST", "DMA" and
705      "ANY"; there should be a setting which also works for you.
707   Q: If I use many screens or many colors, my Amiga runs slower
708      and slower.
709   A: Probably you are running out of chip memory. Use the "FAST"
710      option, if your SCSI driver supports this. Otherwise, decrease
711      the size of the CDVDFS buffers with the options FB and SB.
713   Q: My system does not boot if no disk is inserted in the CDROM drive.
714   A: L. Scott Emmons (csusac.csus.edu!cdsac!scotte) suggests this:
715      If the CDROM drive is at a SCSI address lower than the last
716      hard drive device, the system will not boot unless either the
717      drive is powered off, or a data CD is in the drive. To fix,
718      I changed my hard drive to SCSI device 0, put the CDROM drive
719      as device 5, and then rebooted with the CDROM drive powered OFF.
720      I ran HDTOOLBOX, which complained that "something had changed",
721      did a "SAVE", and exited. Now, I can reboot with the CDROM drive
722      either on or off, and everything is fine. Apparently this has to
723      do with setting the "last drive" bit on the hard drive, or some
724      such. This will be a problem with any factory-installed hard
725      drives, since CBM insists on installing them as SCSI device 6.
727 @endnode
729 @node UTILITIES "Other utilities of interest"
731   "SCSIUtil" by Gary Duncan and Heiko Rath:
732   Provides low level access to your CDROM drive. Useful for debugging.
734   "ForceIcon" by Kai Iske:
735   A commodity which places icons for volumes and devices at user-definable
736   locations. Useful if you don't like the icon locations and images on
737   your CDROM.
739   "cdromemu.device" (can be found in m68k AmiCDROM v1.15 archive):
740   Emulates a trackdisk device which reads a CDROM image from an AmigaDOS
741   file. Can be used by CDROM manufacturers to verify the output of
742   their pre-mastering program. It is removed from MorphOS distribution
743   because it comes without source code and can't be recompiled.
745 @endnode
747 @node THANKS "Thanks must go to.."
749   My promary thanks go to original author, Frank Munkert, for releasing
750   source code of AmiCDROM version 1.15.
752   Also the following people were involved into development and beta testing
753   of previous versions of AmiCDROM:
755     Thomas Baetzler
756     Olaf Barthel
757     Stefan Becker
758     Johanna Berewinkel
759     J. M. Bezeau
760     Stefan Le Breton
761     Dirk-Michael Brosig
762     James Cooper
763     Gary Duncan
764     Richard L. Dyson
765     Brent Earl
766     Phillip Eastham
767     L. Scott Emmons
768     Stephan Feinen
769     Manuel Fischer
770     Fred Fish
771     Jos Fries
772     Thorsten Frueauf
773     Humberto L. Gomez
774     Oliver Graf
775     Christoph Guelicher
776     Carsten Hammer
777     Joe Hanson
778     Thorsten Herrmann
779     Rainer Hess
780     Martin Jahner
781     Tom Kennedy
782     Thomas Kessler
783     Stephan Kohler
784     Thomas Kroener
785     Roy S. Laufer
786     W. R. Leach
787     Martin Loos
788     Dylan McNamee
789     Thomas J. Moore
790     Gunther Nikl
791     Bo Najdrovsky
792     Ottmar Roehrig
793     Nicola Salmoria
794     Matthias Scheler
795     Henning Schmiedehausen
796     Martin Schulze
797     Bill Seymour
798     Ignatios Souvatzis
799     Ken Sowinski
800     Luca Spada
801     Erkki Tapola
802     Joergen Thomsen
803     Mark Tomlinson
804     Olivier Tonino
805     Roy Trevino
806     Frank Wuerkner
807     Jim Zepeda
809 @endnode
811 @node BUGS "Bugs and not supported features"
813   Bugs: If you find any bugs, please send an e-mail message to:
814            sonic_amiga@rambler.ru
816     If you want to report an error, please describe your system
817     configuration (computer model, operating system name and version,
818     SCSI device name, CDROM drive model) and include your MountList
819     entry for the "CD0:" device. Include in your bug report the output
820     of the commands "cdrom a" and "cdrom v".
822   Not supported features:
823   
824     - Interleaved mode (ISO)
825     - Multi-disk volumes (ISO)
826     - Multi-volume disks (ISO)
828 @endnode
830 @node TODO "TO DO"
832 Things to do:
833 -------------
835   My current plans for this project are:
837 - Implement UDF filesystem support.
838 - Create MUI-based preferences editor instead of old "cdcontrol" program.
839 - Implement reading CDDA tracks as files (like in AsimCDFS).
841   The project can be supported for all existing branches of Amiga operating
842   systems. Current source code supports three flavours:
844 - AmigaOS/m68k (until v3.9)
845 - MorphOS
846 - AROS
848   MorphOS and AROS flavours are maintained by me. Maintainers for m68k build and
849   possible AmigaOS4 build are wanted. Support for unmaintained architectures can
850   not be guaranteed.
852   If you wish to become a maintainer please mail me at sonic_amiga@rambler.ru.
854 Original to-do from Frank Murket:
855 ---------------------------------
857 - Support trackdisk disk change interrupt:
858   Neither trackdisk interrupts nor trackdisk changenums are supported
859   by the V40 scsi.device for A3000(T). Therefore the trackdisk disk change
860   recognition feature currently cannot be supported by CDVDFS.
862 @endnode
864 @node HISTORY "History of CDVDFS"
866 Changes in V1.4:
868 * Fixed reading multisession discs, previously it worked not on all drives.
869 * Supports "Hidden" flag on ISO9660/Joliet volumes, used by for example MacOS.
870 * Hides files with "Associated" flag set, this helps to read discs created
871   under MacOS.
873 Changes in V1.3:
875 * Now reports correct DOS type for volumes.
876 * Fixed losing a volume under MorphOS if a disk has been removed with some
877   files or directories open.
878 * Fixed some problems with RockRidge volumes on some machines.
879 * Fixed disappearing volume upon disc read failure.
880 * Fixed broken CDDA handling.
882 Changes in V1.2:
884 * Added support for protection bits and file comments
885 * Fixed crash with too long file names (longer than 106 characters).
886 * Fixed Mountlist format, now correct and compatible with all systems.
888 Changes in V1.1:
890 * Removed redundant TRACKDISK option, standard trackdisk commands are used
891   for reading data and SCSI-2 commands for other operations.
892 * Added support for trackdisk64 standard, now will really work with DVD disks,
893   even double-layered.
895 Changes in V1.0:
897 * First release under new name.
898 * Rewritten startup procedure, now uses new format of mountlist.
899 * Added Joliet support.
901 Original AmiCDROM changelog follows.
903 Changes for MorphOS port:
905 * Rewritten CDDA play routine, now it should work with all IDE drives.
907 Changes in V1.15:
909 * Mount command returns now even if the SCSI device cannot be opened
910   (with RETRY option only!)
911 * Fixed bug in HFS driver which caused slow or even incorrect file access.
912 * Truncate file names to 30 characters.
913 * Included installer script.
915 Changes in V1.14:
917 * Fixed bug in volume handling routines.
918 * Start sector of files is now returned in the fl_Key field of
919   FileLock structures, for compatibility with the Commodore CDROM file
920   system.
922 Changes in V1.13:
924 * Offset of last session is determined with a vendor specific command
925   on Toshiba drives.
926 * Added a workaround for the bad NEC 3X READ TOC command, which sometimes
927   contains a wrong track number for the lead-out track.
928 * Added support for packet ACTION_EXAMINE_FH; this fixes the problems with
929   some implementations of the C library routine fstat().
930 * Added support for packet ACTION_PARENT_FH.
931 * Better error message for ACTION_MAKE_LINK.
932 * A volume node will be removed if the last lock from the volume node has
933   been freed.
934 * READ TOC command disabled for Apple CD 150, because this command caused
935   some CD 150 drives to block the SCSI bus.
936 * AmiCDROM sources can now be compiled with the GNU C compiler gcc.
937 * Aztec C and DICE C are no longer supported.
939 Changes in V1.12:
941 * Tries to cope with CDROMs which have an incorrect table of contents.
942 * New default CD-DA icon.
943 * User-definable CD-DA icon.
944 * New option RETRY.
946 Changes in V1.11:
948 * New option MAYBELOWERCASE.
949 * Audio support for Apple CD-150 (= Sony 8002) und CD-300 (= Sony 8003).
950 * Sense length 20 instead of 18 (needed by ALF driver).
951 * Fixed bug in ACTION_DISK_INFO.
952 * Performance improvement for lock+filehandle processing.
954 Changes in V1.10:
956 * Larger buffer for startup strings.
957 * Improved handling of volumes: locks and file handles will not be
958   discarded if a CDROM is removed from the drive.
959 * Adapted ACTION_CURRENT_VOLUME to new volume handling.
960 * CDROM emulator now also supports TD_CHANGESTATE and TD_CHANGENUM,
961   and the virtual CDROMs can be inserted into and removed from the
962   emulated drive.
963 * Fixed bug concerning TRACKDISK disk change recognition.
964 * Improved implementation of ACTION_INHIBIT.
965 * Minor improvements and bug fixes in the HFS driver.
966 * The extended attribute record length has to be considered when
967   reading file sections.
969 Changes in V1.9:
971 * Added support for Rock Ridge relocated directories.
972   AmiCDROM now conforms fully to the Rock Ridge Interchange Protocol Rev 1.09.
973 * Added CDROM emulator cdromemu.device.
974 * Included "checkcd" tool.
975 * Full support for ACTION_INHIBIT.
976 * Better trackdisk disk change recognition.
977 * Toshiba 4101 support.
979 Changes in V1.8:
981 * Support for symbolic links on RockRidge disks.
982 * Support for multisession disks (such as PhotoCDs).
983 * New memory options CHIP, DMA and ANY.
984 * Removed the assembly stubs for the debug process (Aztec and SAS/C).
985 * Support for the ACTION_FLUSH packet.
986 * Changed the packet number for cdcontrol from 666 to 2050.
987 * The option LOWERCASE now also applies to ISO volume names.
988 * Double-clicking at the CD-DA icon (without PLAYCDDA option) now plays
989   the whole CD.
990 * Support for CDROM drives with block lengths of 512, 1024 and 2048 bytes.
991 * Better method for finding HFS master directory blocks.
992 * User may define the location of the CD-DA icon.
993 * If the CD-DA icon cannot be displayed because the WB is not open, then
994   the display function will be retried periodically (all SCANINTERVAL seconds).
995 * The AmiCDROM device node now also contains a pointer a FileSysStartupMsg,
996   in order to live peacefully together with SysInfo and similar tools.
997 * Support for drives which do not support the SCSI-2 READ TOC command.
999 Changes in V1.7:
1001 * Some packets are now handled even if no disk is inserted (e.g. the
1002   ACTION_INHIBIT packet). Otherwise WB would bring up the requester "No Disk
1003   in drive CD0:" when the system is booted without a CD in the drive.
1004 * Improved "cdrom d" and "cdrom e" commands.
1005 * Removed call to GetDefDiskObject(). This call sometimes caused a crash,
1006   because GetDefDiskObject sends/receives DOS packets. A DOS handler isn't
1007   allowed to do this.
1008 * Added custom CD-DA icon.
1009 * Support for logical block sizes of 512, 1024 and 2048 bytes.
1010 * Fixed bug in HFS module.
1011 * Option MACTOISO now also converts ':' and '/' characters.
1012 * Options MACTOISO and CONVERTSPACES now also apply to volume names.
1014 Changes in V1.6:
1016 * CD-DA support; new option: PLAYCDDA.
1017 * New option: SCANINTERVAL (user-programmable diskchange check interval).
1018 * Better support for ACTION_INHIBIT packet.
1019 * Allows ISO filenames with ';' characters.
1020 * Can now be compiled with DICE 2.07.56R.
1022 Changes in V1.5:
1024 * Make Toshiba-3401 drives switch between XA and normal mode, depending
1025   on the inserted disk. (Useful for PhotoCDs.)
1026 * New option: SHOWVERSION.
1027 * New option: HFSFIRST.
1028 * Fixed a bug which caused an enforcer hit with the "cdrom" program.
1029 * "cdcontrol" control program.
1031 Changes in V1.4:
1033 * Added Mac HFS support.
1034 * The path table of ISO disks is no longer examined. This results in a
1035   little speed increase. Furthermore, the FishMarket V2.0 disk by AsimWare
1036   (which has a corrupted path table) can now be read with AmiCDROM.
1037 * Bug fix: if a there is a disk change immediatedly before mounting AmiCDROM,
1038   the new disk will now be recognized.
1039 * SAS/C support for debug process (dbproc.a).
1041 Changes in V1.3:
1043 * Improved caching algorithm.
1044 * New buffering options 'STDBUFFERS' and 'FILEBUFFERS'.
1045 * Fixed bug with locks containing wrong fl_Volume entry. Now the AmigaDOS
1046   shell should show the correct volume prompt.
1047 * New format for the Mountlist 'Startup' field.
1048 * Compiled with small memory model.
1049 * Uses utility.library in order to reduce the size of the executable.
1050 * Recognizes if a non-ISO disk is in the CDROM drive and creates a
1051   'no DOS disk' volume node. This solves some problems with Audio-CDs.
1052 * The volume node now contains the volume creation date.
1053 * Can now be compiled with SAS/C and DICE in addition to Aztec C.
1055 Changes in V1.2:
1057 * Support for new packets: ACTION_SAME_LOCK, ACTION_IS_FILESYSTEM,
1058   ACTION_CURRENT_VOLUME.
1059 * Send 'disk inserted' or 'disk removed' event, so that the Workbench
1060   detects disk changes faster.
1061 * Added fast memory option 'F'.
1062 * Writing ACTIONs now return a 'write protected' error status.
1063 * Unload handler after ACTION_DIE.
1064 * Immediately terminate program if called from CLI.
1065 * Set volume label to "Unnamed" for disks without name.
1066 * Added support for LUNs other than 0.
1067 * Included an icon for the Mountlist.
1068 * DOS list changes now bracketed by Forbid() and Permit().
1069 * Corrected another ACTION_SEEK bug.
1070 * Handler cannot be killed if locks or filehandles are in use.
1072 Changes in V1.1:
1074 * Bug in ACTION_SEEK handling fixed.
1075 * Bug with top-level ACTION_EXAMINE_OBJECT for Rock Ridge disks fixed.
1076 * Added code to detect whether a lock stems from the current volume
1077   or from another volume which has been removed from the drive.
1078   (In this case the error 'object not found' (205) is reported.)
1079 * Added support for trackdisk calls. (Startup option 'T')
1081 @endnode