SPIN.TXT                     Device drivers                     SPIN.TXT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NAME
     SPIN! - MiNT- and MagiC-XFS for CD-ROM file-systems, 
             MetaDOS-BOS driver

VERSION
     Release 0.34

DESCRIPTION
     Warning: This program package is NOT `Public-Domain' or `Freeware'.
     More about this under `COPYRIGHT'!!!!

     SPIN! is a driver package for CD-ROMs, at present consisting of the
     MiNT-XFS SPIN.XFS (eXtended File-System), the MagiC-XFS SPINMAGX.XFS
     and the MetaDOS-BOS driver SPIN_SD.BOS, the latter linking into 
     the SCSIDRV-interface from Steffen Engel.

     All components can also be used individually: For instance an XFS 
     based on an third party BOS driver (say for IDE CD-ROMs), and also
     the BOS driver as a base for a third party DOS driver (for example 
     as a substitute for Atari's CDARGEN.BOS as a base for ISO9660F.DOS).


     A little driver theory
     ~~~~~~~~~~~~~~~~~~~~~~
     Behind SPIN! lies the idea of defining, implementing and 
     documenting clearly defined driver interfaces. This should make it 
     possible for anyone to assemble their own customised CD-ROM 
     interconnection suited to their operating system and hardware.

     To understand which and how parts fit together, it is necessary to 
     clarify a few concepts:

     Level 5 - User programs
     -----------------------
          This could be any desired program with file-system access  
          (e.g. GEM-View), but also a tool for controlling the audio 
          functions (e.g. CDDA.APP from the CD-Tool package).

     Level 4 - The operating system
     ------------------------------
          At present this can be TOS, MagiC or MiNT.

     Level 3 - The file-system driver
     --------------------------------
          Depending on the operating system used the possibilities here 
          are a MetaDOS-DOS driver (for TOS and in a limited way also 
          for MagiC), a MagiC-XFS (for MagiC) or a MiNT-XFS (for MiNT).

     Level 2 - The device driver
     ---------------------------
          The device driver "abstracts" the concept of a CD-ROM. In 
          plain English, this means that it implements functions for 
          reading data off the disk, for providing some information and 
          for audio control. It is implemented as an XBIOS extension 
          and is loaded as a BOS driver by MetaDOS/XBS.

     Level 1 - The interface driver
     ------------------------------
          An interface driver serves for communication with the 
          hardware, i.e. SCSI, ACSI, IDE or whatever.

     Level 0 - The interface
     -----------------------
          The physical hardware for connecting the device (SCSI-chips 
          etc.)

     
     As a rule, Level 0 and Level 4 are predefined: One wishes to address 
     an existing CD-ROM that is attached to a given interface of the  
     computer running under a given operating system. For this one needs 
     driver software for Levels 3, 2 and 1. 
     In the following I will explain which areas SPIN! tries to cover,
     and what other drivers are available.


SPIN.XFS - a Level 3 driver for MiNT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     This is a MiNT file-system driver for CD-ROMs, which is based on 
     MetaDOS-BOS drivers. It can thus be used under `Plain-MiNT', 
     MultiTOS, N.AES or other MiNT-compatible AES-versions.

     The XFS supports various file-system types:

     -    ISO9660 Level 1 (the "normal" format)

     -    ISO9660 with "long" names (used with Amiga-CDs, for instance)

     -    ISO9660 with Rockridge extensions (however only a portion of  
          these extensions will be evaluated)

     -    ISO9660 with Apple extensions (Resource-fork, Type and Creator)

     -    ISO9660/Joliet: The Windows-95 format (however the conversion 
     	  of Unicode characters in file names has not been tested yet)

     -    Macintosh-HFS

     -    Audio-CDs (requires an audio-capable Level 2 driver (BOS 
     	  driver))

     SPIN! itself contains no routines for accessing the device. Instead 
     a prerequisite for its use is the presence of a Level 2 driver 
     (MetaDOS-BOS driver). This strict division makes it possible to 
     combine SPIN! with any available Level 2 driver.


     SPECIAL FEATURES WITH AUDIO-CDS

     If the Level 2 driver supports the audio commands correctly, then 
     so-called `track-files' will appear when an audio CD directory is 
     read. By double-clicking `TRACK01.PRG', for instance, the CD 
     will be played out starting from the first `song' (CD track).

     If the Level 2 driver is also capable of reading digitally from  
     audio CDs (`DDS': Direct Digital Sampling), then additional files 
     will appear with the extension `WAV'. These files can be read
     directly by various sound-tools and contain the 16-bit 44.1kHz 
     sound data of the tracks.

     Tracks that do not contain audio data appear with the extension 
     `DAT' (this can occur with mixed-mode CDs, for instance). This 
     makes it possible to access the data via GEMDOS even when one is 
     dealing with an unsupported file-system type (e.g. a Unix-CD). 


     SPECIAL FEATURES WITH MAC-CDS

     Two variants of Macintosh-CDs are supported: ISO9660 format with
     Apple extensions and CD-ROMs in Macintosh-HFS format. In both 
     cases the MacMiNT- or MagiCMac-extensions resp. are supported 
     for accessing the data:

     -    Type and Creator can be queried per Dcntl/Fcntl FMACGETTYCR 

     -    The Resource-fork can be accessed per Fcntl FMACOPENRES

     For CDs in HFS format, SPIN! does its best to convert any Mac 
     characters in file names to sensible TOS equivalents. But naturally 
     this is not always possible unambiguously.


     SPECIAL FEATURES WITH MIXED-MODE-CDS

     If a CD contains both an ISO9660 as well as a Mac-HFS directory 
     structure, SPIN! will normally "prefer" the format that was used 
     last. This means that if an ISO-only CD was read last then only 
     the ISO-portion will be used (and vice versa).

     This preference may be toggled by a "Forced Media Change". This can 
     be triggered in Gemini, for instance, by pressing Shift-ESC with 
     the directory window open. If the desktop in use does not offer 
     this function, then one can can make use of `FORCEMED.APP' (in the 
     BIN folder).

     The same applies if a CD contains a mixture of audio and data 
     tracks. In that case one can switch back and forth with Shift-ESC 
     between displaying "Computer data" and "Audio tracks".


     MULTISESSION-CDS

     SPIN! supports multisession CDs (Photo-CD, CD-Extra, etc.), but 
     for this the BOS driver being used must support the Metaioctl call 
     CDROMREADOFFSET (which is not the case with CDARGEN.BOS, but is 
     with SCSI_SD.BOS and HS-CDROM.BOS from CD-Tool).


     CD-ROM DEVICE

     The XFS generates entries in u:\dev, to make it easier to port 
     Unix sources. For this the file name is:

     u:\dev\cCtTdDsS.dsk

     where the four capital letters represent: `C' the controller 
     number (ACSI: 0, SCSI: 1, IDE: 2), `T' the target device number 
     (0..7), `D' the device LUN (0..7) and `S' the partition number 
     (always 0). Warning: SPIN! can establish this information only for 
     its own drivers, otherwise the following appears:

     u:\dev\cmtD.dsk

     (where `m' represents MetaDOS, and the last character gives the
     MetaDOS-XBIOS device number).

     The "first" CD-ROM found is given the additional entry:
     u:\dev\cdrom.


SPINMAGC.XFS - a Level 3 driver for MagiC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     If you have skipped the section about the MiNT-XFS, you should now 
     go back and read it, because SPINMAGC.XFS offers exactly the same 
     range of functions, only under MagiC (tested under MagiC 5.x).


SPIN_SD.BOS - a Level 2 driver for ACSI/SCSI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     This is the BOS driver belonging to the SPIN! package. It supports 
     all the commonly available SCSI CD-ROMs and CD-writers (and in 
     addition the Apple CD 150 as well as the Atari CDAR 504), and 
     requires the presence of Steffen Engels's "SCSI-Treiber" (Level 1) 
     or a driver compatible to it (not included in the package).

     Assuming that the drive is capable of it, multisession CDs, audio 
     commands as well as digital copying of audio data are supported.

     "SCSI-Treiber" (or CBHD or HDDRIVER 7.x) should be loaded before
     MetaDOS. If SPIN_SD.BOS does not find an installed SCSI driver, 
     it attempts to execute the following programs in the AUTO folder 
     in turn:

     \auto\scsidrv.prx   \auto\scsidrv.prg
     \auto\mm_scsi.prx   \auto\mm_scsi.prg

     So if one requires SCSI-Treiber exclusively for CD-ROMs, one can 
     store it in the AUTO folder with a PRX extension. SPIN_SD.BOS will 
     then activate it automatically when it needs it.

     ...and for which devices does SPIN_SD.BOS support DDS (`Direct 
     Digital Sampling')? A total of three different procedures are used 
     at present:

     1.   For TOSHIBA drives, a Toshiba-specific SCSI command is used.

     2.   For SONY and for PLEXTOR drives, the corresponding Sony 
          command is used.

     3.   Otherwise the standardised command from the SCSI-3 multimedia
          command set is attempted. That works for drives from PIONEER, 
          for instance, and for several CD-writers.

     ...and which drives can be recommended for DDS? The German 
     magazine `c't' recommends PLEXTOR and also PIONEER, the author 
     could only test a PIONEER device to date and achieved good results 
     with it (see ddstest.txt).


INSTALLATION
     Since there is no automatic installation program (as yet), one 
     has to give this a little throught. We start with the:

     1. Installation of BOS/DOS driver under plain TOS
     -------------------------------------------------
     In this step we will ignore MiNT and MagiC for the time being, and
     address the CD-ROM under plain TOS. If your system is not running 
     under plain TOS (MagiCMac? MagiCPC?), then just look at this as a 
     dry run.

     If you already have a setup of this kind, you can jump directly to 
     Step 2.

     What is required is MetaDOS 2.70 (contained in the archive), a BOS 
     driver suitable for the hardware (see description above and 
     below), as well as a DOS driver for ISO9660 CDs (for example 
     ISO9660F.DOS from Atari's MetaDOS distribution).

     Create a text file named CONFIG.SYS in the AUTO folder. This 
     should look somewhat as follows:

     *BOS, C:\AUTO\SPIN_SD.BOS, A:14
     *DOS, C:\AUTO\ISO9660F, Z:A

     The first line describes the BOS driver used. It contains the path 
     and name of the driver file, the XBIOS-ID (here `A') and the 
     device address.

     For the XBIOS-ID it is safe normally to choose 'A' -- it has 
     nothing to do with the letter under which the CD-ROM will appear 
     on the desktop. You will need further letters only if you want to 
     control several devices via MetaDOS.

     The device address specifies where the CD-ROM is connected. As a 
     rule the following applies (further details should be contained in 
     the BOS driver documentation!):

     0: ACSI 0       8: SCSI 0     16: IDE Master
     1: ACSI 1       9: SCSI 1     17: IDE Slave
     2: ACSI 2      10: SCSI 2
     3: ACSI 3      11: SCSI 3
     4: ACSI 4      12: SCSI 4
     5: ACSI 5      13: SCSI 5
     6: ACSI 6      14: SCSI 6
     7: ACSI 7      15: SCSI 7

                    (8 to 17 of course apply only to computers having 
                    the corresponding ports, e.g. TT, Falcon etc.)

     In addition, for SPIN_SD.BOS one can add the LUN (logical unit 
     number) as a multiple of 8192 to the basic aaddress. So LUN 1 
     on SCSI 4 would give an ID of 8204. This feature is only likely to 
     be useful in connection with phase-change and autochanger drives, 
     and has not yet been tested extensively.

     In the CONFIG.SYS example above, a CD-ROM connected to the SCSI 
     port and set to an ID of 6 will be addressed.

     If you do not know exactly at which address the device is 
     connected, you can query this with a suitable test-tool such as 
     ID-TEST.APP from SCSI-Tool/CD-Tool (or HDPARTS.TOS or IDCHECK.PRG 
     from one of the ICD packages -- Translator). Otherwise it's a 
     question of trial and error.

     The second line describes the DOS driver being used. This too 
     contains the path and name of the driver file, followed by the 
     allocation of the desktop drive letter to the XBIOS-ID. In the 
     above example therefore the drive letter `Z' is assigned to the 
     XBIOS-ID `A'.

     Incidentally, one line can also allocate the same driver for two 
     devices:

     *BOS, C:\AUTO\SPIN_SD.BOS, A:14, B:13
     *DOS, C:\AUTO\ISO9660F, Z:A, Y:B

     This would register SCSI devices 5 and 6 as GEMDOS drives `Y' and 
     `Z'. 

     Warning: Many programs can only handle a maximum of 16 drives. In 
     such cases select a drive ID of `O', say, or even `B'.

     When you have modified the file to suit your circumstances, and 
     also copied METADOS.PRG as well as the BOS and the DOS drivers
     into your AUTO folder, then the CD-ROM should be addressable as a 
     GEMDOS drive. Try it out, preferably with a "simple" data-CD.

     
     2. Replacement of an existing BOS driver by SPIN_SD.BOS
     -------------------------------------------------------
     You already have a BOS driver, but would like to try out 
     SPIN_SD.BOS in its place?

     No problem: Alter the BOS file name correspondingly in the 
     CONFIG.SYS file, copy SPIN_SD.BOS to the AUTO folder and reboot.


     3. Installation of the MiNT-XFS SPIN.XFS
     -----------------------------------------
     Remove METADOS.PRG from the AUTO folder (or rename it to something 
     else, say .PRX). Copy METAXBS.PRG to the AUTO folder. Ensure that 
     METAXBS.PRG runs before MINT.PRG! Copy SPIN.XFS into the MiNT or 
     MultiTOS folder (normally C:\MINT or C:\MULTITOS).

     After a reboot it should be possible to access the CD drive in the 
     same way as under normal TOS.


     4. Installation of the MagiC-XFS SPINMAGC.XFS
     ---------------------------------------------
     Copy METAXBS.PRG to the AUTO folder (the position in this case is 
     immaterial; it may even be called METAXBS.PRX). Copy SPINMAGC.XFS 
     into the \GEMSYS\MAGIC\XTENSION folder.

     After a reboot it should be possible to access the CD drive in the 
     same way as under normal TOS.


HOW IT WORKS
     METAXBS.PRG is a slimmed-down version of METADOS.PRG, from which 
     all functions for loading and linking in DOS drivers have been 
     removed. This not only saves space, but also prevents the 
     installation of the DOS drivers, which are no longer needed under 
     MiNT and MagiC. At start-up MetaXBS links in the BOS drivers as 
     usual. After this, all MetaDOS-XBIOS functions are available as 
     under MetaDOS.

     The XFSs also read the MetaDOS configuration file (from 
     \AUTO\CONFIG.SYS). They look for the line for installing the DOS 
     driver (now no longer used) and evaluate it themselves.
     For example:

     *BOS, c:\auto\cdargen.bos, A:11

     This line will be evaluated by MetaXBS, and, as with a normal 
     MetaDOS installation, lead to the driver CDARGEN.BOS being loaded 
     and SCSI drive 3 (8 + 3) being initialised as MetaDOS-XBIOS device 
     `A'.

     *DOS, c:\auto\hs-iso.dos -c128, S:A

     This part will now be evaluated by SPIN!. SPIN! simply looks for 
     the instruction to install a DOS driver and undertakes this 
     function automatically. For this it will recognise the file names 
     "ISO9660F.DOS" (Atari-MetaDOS) and "HS-ISO.DOS" (CD-Tool). A 
     cache-size specification as for CD-Tool (-cXXX) will be recognised 
     and evaluated. So in the above example SPIN! would install the 
     GEMDOS drive S:, access it via MetaDOS-XBIOS as device `A' and 
     reserve a 128 KB sector cache for it.


OTHER DRIVERS
     And here a few more pieces of the "driver jigsaw puzzle":

     CBHD, SCSIDRV.PRG and MM_SCSI.PRG
          These drivers by Steffen Engel are, or contain, Level 1 
          drivers for ACSI, Falcon-SCSI, TT-SCSI and MagiCMac. See: 

          http://members.aol.com/steffene/

     HDDRIVER
          From version 7.0 onwards, Uwe Seimet's hard disk driver also 
          contains the SCSIDRV interface, thus making Level 1 
          interfaces for ACSI, Falcon-SCSI and TT-SCSI available.
          Demo version available from:

          http://acp5.chemie.uni-kl.de/seimet/hddriver_german.html

     CDARGEN.BOS
          This driver encompasses Levels 2 and 1, supports the TT-
          SCSI hardware as well as the ACSI interface, but here only 
          the antiquated Atari CDAR504 drive. Only rudimentary audio
          commands are implemented, and multisession support is 
          missing.
          Part of the (free) Atari MetaDOS distribution. See:
          
          http://www.muenster.de/~reschke/soft.html#metados

          or METADOS27.ZIP in Maus MS2, as well as other PD sources.

     HS-CDROM.BOS
          Level 1 and 2 driver for ACSI, TT-SCSI, Falcon-SCSI and 
          IDE. Part of the (commercial) CD-Tool package. See:

          http://www.muenster.de/~reschke/soft.html#cdtool

     ISO9660F.DOS
          This is a Level 3 driver for MetaDOS that implements the most 
          important commands at least for quite normal ISO9660 CDs. 
          Also a part of the (free) Atari MetaDOS distribution. See:

          http://www.muenster.de/~reschke/soft.html#metados

          or METADOS27.ZIP in Maus MS2, as well as other PD sources.

     HS-ISO.DOS
          A further Level 3 driver for MetaDOS. Part of the 
          (commercial) CD-Tool package. See:

          http://www.muenster.de/~reschke/soft.html#cdtool


KNOWN PROBLEMS
     SPIN.XFS, SPINMAGC.XFS
          For CDs with defective directory entries one may find that 
          some files and directories cannot be opened. It is quite 
          possible that such CDs appear to function correctly with 
          other drivers, but this problem is really due to errors on 
          the CD.

     SPIN_SD.BOS
          Will not be recognised at present by CDDA.APP as a CD-ROM 
          driver (actually an error in CDDA in versions before 3.00).

          Does not appear to work with the Atari CDAR504 device when 
          using SCSI_DRV.PRG (other SCSI drivers not yet tested).

ERROR REPORTS
     Anyone encountering problems should always include the following 
     information (use the Report function in SCSI-Tool or CD-Tool if 
     applicable):

     - Exact description of the hardware used
     - Operating system version
     - Driver versions, MetaDOS version
     - Configuration (CONFIG.SYS)

AUTHOR
     Julian F. Reschke
     Hensenstrae 142
     D-48161 Mnster

     Maus MS, Telephone 0(0 49)251/77261, User name "Julian Reschke"

     mailto:jr@ms.maus.de
     http://www.muenster.de/~reschke
     
ENGLISH DOCUMENTATION
     Translation of the documentation provided by Peter West of 
     TransAction, the PD and Shareware translation crew.
     
     email: xlator@cix.co.uk  or PWest@fortress.org.uk

IMPORTANT NOTICE
     I, Julian F. Reschke, accept no liability for any kind of direct 
     or indirect damage -- including but not restricted to material or 
     financial -- arising from the use of these programs or the 
     unsuitabillity of these programs for a given purpose.

COPYRIGHT
     For all programs and texts, unless quoted elsewhere in greater 
     detail or otherwise specified:

     Copyright (c) 1997 Julian F. Reschke
     All Rights Reserved

     "MetaDOS" and "MetaXBS" are Copyright of Atari Corp.

     "SCSI-Treiber" and "CBHD" are Copyright of Steffen Engel and Claus 
     Brod.

     "HDDRIVER" is Copyright of Uwe Seimet.

     SPINMAGC.XFS contains file-system interface code by Andreas Kromke.

     These programs are NOT Public Domain, though they may be freely 
     distributed (but only without charge). For this the original 
     archive MUST be passed on in an unaltered form.

     I reserve the right to withdraw this premission at any time and 
     without specifying any reasons.

     Distribution on PD combination diks or similar media (fee-charging
     mailbox systems, `Channel Videodat', etc.) is only permitted with 
     my specific written approval. The following applies to CD-ROMs:

     -    The original archive MUST be distributed in its original 
          form. In addition the archive may also be distributed in an 
          extracted format.

     -    There must be a reference in a suitable place (packaging, 
          cover, README file etc...) that the purchase of the CD is in 
          no way connected to any payments to the individual program 
          authors.

     -    Before the publication of the CD it must be established for 
          certain that the newest version of SPIN! is to hand.

     -    Immediately after publication a free sample copy of the CD is 
          to be sent to me.

     The installation and distribution of the programs or parts of the 
     programs constitutes an acceptance of these conditions.

     Further developments of these programs will definitively only take 
     place if adequate motivation is provided by appropriate voluntary 
     contributions. So everyone who makes use of this program 
     collection and wishes that it be maintained and developed further, 
     please send a donation to the following bank account:

          Konto Nr. (Account No.) 2542 39-465
          Postgiroamt Dortmund (BLZ 440 100 46)

     It is quite possible that future versions will no longer be 
     available free of charge. Hence it is important that, besides the 
     name, you also specify your address and email-address (if 
     applicable) on the bank transfer slip. And since the bank 
     statement normally does not include all the information from the 
     transfer slip, it's a good idea to notify me by email about the 
     transfer as well...

     Those who have already used older versions and have not yet sent 
     a contribution should immediately delete this version or force 
     themselves to send a contribution at last. I consider anything 
     else as sponging.

     In case of any problems, or suggestions for improvements etc., 
     please contact me at the above email address.
         

SEE ALSO
     cdtoc.txt, ddstest.txt

This document is also available in MAN format, which is ready to print 
out with emphasised headings etc. on any printer.