Documentation for Replacement CLtd SCSI Driver ---------------------------------------------- 5-Jan-1998 ================================================================ scsicltd.device V1.2 02-Nov-1997 Copyright (C) 1991, 1997 Frederick H. G. Wright II ================================================================ License ======= This software is freeware, and may be used or distributed free of charge for any noncommercial purpose. No registration is required, but email is requested from anyone using it. Disclaimer ========== This program and its documentation are provided "as is". No warranties are made with respect to the accuracy, reliability, performance or operation of this software and information. You are using this program at your own risk. The author is not liable for any damages that may have been caused by using this software. Introduction ============ This is a replacement for the factory driver for the CLtd SCSI controller. It was originally written for the A1000 controller with the "SCSI-DOS 2.01 upgrade" PAL. It should work with this controller or any other compatible version. The included configlist program can be used to check the controller version before installation. NOTE: All references to the behavior of the factory driver are based on the SCSI-DOS 2.01 version. I've been informed that a version 3.01 exists, although I have not seen it myself. If you have a later version, there may be differences between aspects of the factory driver described here and the one on your system. System requirements =================== Amiga equipped with one or more compatible CLtd SCSI controllers. CPU: Written for 000/010 <=16MHz or 020/030 <=50MHz. Tested on 68010 @ 7.16MHz. OS: Written for OS 1.2 through at least OS 3.1. Tested under 1.3 & 2.04. Software Installation ===================== 1) scsicltd.device ------------------ Installing the driver (not including configuration) is simply a matter of copying the file scsicltd.device to an appropriate DEVS: directory. The name of the driver is not the same as that of the factory driver, so there is no conflict in having both present in the system. The driver must be loadable from some device which is accessible without the use of the CLtd controller, to avoid the obvious "chicken and egg" problem. Typically this means having the driver on a floppy or RAD:, unless the system has an additional hard drive accessible through another controller. It may be convenient to *also* keep the driver on a CLtd-accessed hard disk, but it cannot be loaded from there. NOTE: The factory driver comes in two parts: SCSI.device basic SCSI handler ACB-4000.driver add-on for SCSI disks The replacement driver is a single component. 2) configlist ------------- The included configlist program may be installed in a suitable command path directory (e.g. C:) if desired, but it is not required for operation. Workbench 2.0 and later has a ShowConfig utility in the Tools drawer, which performs roughly the same function. Hardware Check ============== The configlist program lists all autoconfig devices and memory. This can be used (CLI only) to verify that the CLtd controller is present, accessible, and the proper version. Here is a sample of its output: ------------------------------------------------------------------------------ Address Size Type Flags Manf Prod Serial Driver 200000 200000 E6 80 1010 0 1 0 E90000 10000 C1 0 1010 2 1 0 EA0000 10000 C1 40 1004 12 0 0 ------------------------------------------------------------------------------ The important thing is that there is a device present with manufacturer code 1004 and product code 12, which is the CLtd controller with the proper PAL for use with this driver. Early versions of the controller had a product code 14. The driver does NOT currently work with this controller version. If you have one of these, contact me and I'll *consider* supporting it, but it would be substantially slower and quite a bit of work to figure out the hardware differences. If someone has reverse-engineered the upgrade PAL and made it available, that would be a much better solution. Other expansion lister utilities can also be used to check the configuration if you prefer; just look for the manufacturer and product codes. If the controller appears with the correct version, you can proceed to the configuration section. If it appears with the incorrect version, this driver is not usable until either the driver or the hardware is fixed. If it fails to appear at all, there is a hardware problem requiring investigation. Configuration ============= General Considerations ---------------------- This is the most complex step, although it's relatively simple to convert an existing configuration from the factory driver to scsicltd. There are two different methods of mounting disk devices under AmigaDOS. One is the Mount command, which obtains configuration information from DEVS:MountList (or optionally from a specified file in OS1.3 and later). The other is the Rigid Disk Block (RDB) mechanism, which is used automatically by autoboot controllers and can be used manually by some PD utilities such as SCSIMounter. Since the CLtd controller is non-autoboot, and since the RDB utilities didn't appear until later, it's almost certain that any existing CLtd setup is using Mount. A later section will discuss the RDB approach. A complete description of MountList is beyond the scope of this document, and is in the appropriate AmigaDOS manual for your system. There are a number of parameters supplied by the MountList file, but there are three that are of special interest here because of the differences between the factory driver and scsicltd. These are: Parameter Name Factory Setting scsicltd Setting -------------- --------------- ---------------- Device SCSI.device scsicltd.device Unit +1 Flags The change in the "Device" parameter should be obvious since it's simply the driver name. The change in the "Unit" parameter is the important non-obvious change. The factory driver applies an offset between the driver unit number and the actual hardware SCSI ID, for no particularly good reason. Since scsicltd tries to be more compatible with other Amiga SCSI drivers, which don't do this, it is incompatible with the factory driver in this regard. NOTE: The complete unit number is actually: + * 10 + * 100 which is compatible with other Amiga SCSI controllers. Since the LUN and controller # are usually 0, it typically reduces to just unit=ID. WARNING: If you have multiple drives with adjacent SCSI IDs, failure to observe the unit numbering change could cause data loss. Since the "Flags" parameter is completely ignored by scsicltd, it can keep the same value as with the factory driver or be set to 0. The latter is desirable in the long run, in case future driver extensions make use of the flags. There is certainly no reason to use the HDCalc program with this driver. It is possible to have both old and new MountList entries present at the same time, either by using alternate MountLists or by using alternate names for the partitions in the standard MountList (I prefer the latter). It is NOT possible to use both old and new drivers simultaneously, so all partitions must be mounted with the same driver. Sample MountList Entries ------------------------ Here is a sample of a dual MountList entry for the original CLtd 20 meg drive, as one big partition: DH0: Device = SCSI.device Unit = 1 Flags = 17424386 Surfaces = 4 BlocksPerTrack = 17 Reserved = 2 Interleave = 0 LowCyl = 0 ; HighCyl = 592 Buffers = 9 BufMemType = 0 GlobVec = 1 FileSystem = L:FastFileSystem DosType = 0x444F5301 # DX0: Device = scsicltd.device Unit = 0 Flags = 0 Surfaces = 4 BlocksPerTrack = 17 Reserved = 2 Interleave = 0 LowCyl = 0 ; HighCyl = 592 Buffers = 9 BufMemType = 0 GlobVec = 1 FileSystem = L:FastFileSystem DosType = 0x444F5301 # Note that the last three lines of each entry pertain to FFS, and must be removed or commented out under OS 1.2. With these entries, "Mount DH0" will mount the drive using the factory driver, and "Mount DX0" will mount it using the new driver. The Controller's SCSI ID ------------------------ Since the CLtd controller fails to provide any switches or jumpers for the controller's SCSI ID, the latter must be supplied by the driver. The method used to do this in the factory driver is inconvenient and error-prone, so it was not duplicated here. Currently there is no means to set the controller's SCSI ID other than by patching the driver. The built-in ID is supplied as -1, which is a kind of phantom ninth value which should work with just about any device without conflict. However, if an overly fussy device refuses this selection method, patching the driver for a "normal" ID is possible - contact me. Converting an Existing Mount-Based Setup ---------------------------------------- Since configurations vary widely, no pure cookbook instructions can be given here, so you will have to determine how your system fits into this framework and make the appropriate changes. The following assumptions are made here: 1) The machine boots from a non-CLtd disk device, most likely floppy but possibly RAD: or a non-CLtd HD. 2) Within the S:Startup-Sequence or other scripts called from it, there are one or mode Mount commands referring to partitions on the CLtd drive(s). 3) If the initial boot is from floppy or ramdrive, most likely there is just one Mount early in S:Startup-Sequence, with control transferred as soon as possible to a second-level startup script on the CLtd HD, which reassigns all the standard logical names to the new SYS: partition. Additional Mount commands occur after this. The MountList on the floppy or ramdrive need only contain information for the one partition, but it's usually less confusing to keep it identical to the "real" MountList on the HD. The reason all this matters is that it's important to locate all MountList entries for the existing CLtd partitions, which may involve more than one MountList file. If the existing partition names are kept, only the relevant MountList file(s) need be modified. If new partition names are to be used with the new driver, the Mount commands will need to be changed as well. BEFORE YOU START: Make sure you have good backups of everything. This is always a good idea when changing any system hardware or software, but especially so when changing disk-related things. If your initial boot device is a floppy, use a copy for testing and keep the original. The Go-for-Broke Approach ------------------------- Having located the relevant MountList files, modify them by changing the Device from SCSI.device to scsicltd.device, and making the Unit match the SCSI ID of the drive, repeating for every SCSI.device entry. Make sure the MountList on the new boot medium is up-to-date. Reboot. If everything works, you're all set. If it doesn't, then you can reboot with your old boot medium, but beware that Mounts for additional partitions may fail until the old MountList is restored on the HD. The Cautious Approach --------------------- 1) Set up a bootable disk which does not rely on any files from the CLtd drive, and which has enough tools to investigate and correct problems (including some kind of text editor). 2) Verify that you can boot with this disk, manually mount a CLtd partition (with your existing MountList), and access files on it. Note that Mount does not actually access the device - this is deferred until the first real access. 2.5) Optionally - try some SCSI utilities (see the section on SCSI utilities) to verify that you can access the disk(s) with the new driver. You must reboot before doing this if you have used the old driver since the last reboot. 3) For each CLtd partition entry in your MountList, create a duplicate with a different partition name and the Device and Unit adjustments noted above. Update the MountList copy on the bootable test disk. 4) Repeat step 2, using the new partition names. Be sure to test each partition to catch typos in the MountList. 5) Switch partition names between the old and new entries, so that the alternate names refer to the old entries, and the original names refer to the new entries. 6) Repeat step 4, using the original partition names. 7) Install the updated MountList on your standard boot disk or copy thereof, or create a new boot disk with whatever procedure is normally used. 8) Reboot. Creating a New Mount-Based Setup -------------------------------- This gets highly dependent on system particulars and personal preferences, but here's the general idea. If you have the software and documentation with your controller, you may find it helpful to follow the instructions in the CLtd documentation. You can either: 1) Completely install and configure the factory software (but don't start using it for a real system disk yet), then follow the instructions above for converting an existing installation. or 2) Mostly follow the factory instructions, but use the scsicltd versions of the Device/Unit/Flags parameters in the MountList. Before actually configuring disk partitions, you may wish to try some SCSI utilities (see the section on SCSI Utilities) to check basic access to the device(s). If you don't have any software or documentation, then the basic idea is to add MounList entries similar to the DX0 sample above, with the appropriate values for Unit, Sufaces, BlockPerTrack, LowCyl, and HighCyl. You can create as many separate partitions as you like, by using different NON-OVERLAPPING ranges of LowCyl to HighCyl. Unlike the above example, I strongly recommend reserving the first two cylinders for possible RDB usage later, so the lowest LowCyl value should be 2, rather than 0. Note that HighCyl is the highest cylinder used by the partition, not the first unused, so two adjacent partitions should have the LowCyl of one equal to HighCyl+1 of the previous. WARNING: Great care should be taken in setting up these values to insure that partitions do not overlap, or file corruption will result. Provided that the Surfaces and BlocksPerTrack parameters are the same for all partitions on the drive, then merely insuring non-overlapping cylinder ranges is sufficient. With non-uniform settings of the Surfaces or BlocksPerTrack parameters (see "Fake Geometries"), the rules are more complicated. Determining the proper geometry parameters for an arbitrary drive may present a bit of a problem. You may try some utilities from Aminet to get the information from the drive, but beware that many of them require OS 2.0 or later. HDToolBox is not included with 1.3, but the 2.04 version (2.22) can sometimes be run under 1.3 (seems better with CLI startup). The actual RDBs created by HDToolBox may not be usable, but the "Read Configuration" function of the "Change Drive Type" screen should give you the correct geometry numbers, and you can even go through the motions of partitioning and then note the numbers for MountList. Note that you MUST use scsicltd.device with almost any of these utilities, as they will not work with the factory driver. Once the proper MountList entries have been created, the Mount command can be used to activate a given partition. Access is deferred until the first use of the partition, so the lack of error from Mount doesn't necessarily mean success. With a drive that has already been partitioned and used on another Amiga or another controller, then if the MountList entries are exactly correct you should be able to access the files. With a fresh drive, the Format command should be used to initialize the partition. Always use the QUICK option, since otherwise it will go through the motions of low-level formatting which won't truly low-level format but will waste a lot of time. Low-level formatting is rarely needed (except perhaps for certain parameter changes) and sometimes impossible on SCSI devices. Once the new partitions are working, the boot procedure can be reworked if desired to transfer almost all SYS: functions to a hard disk partition after booting from floppy or ramdrive and Mounting at least one HD partition using the driver and MountList on the original SYS:. With earlier OS versions, it's important not to Execute a second-level startup until after RAM: has been created and T: has been assigned to a RAM: area, since older Execute versions unconditionally copied the script to a temp file, and any disk writes during startup have the potential for ugly collisions with LoadWB. Creating a New RDB-Based Setup ------------------------------ If you are running OS 2.0 or later, you can use HDToolBox to partion drives and SCSIMounter to mount from RDBs. See the sections on RDBs and on SCSI Utilities. The last two paragraphs of the "New Mount-Based" section are also relevant. Using the Driver ================ Features -------- This driver supports the "SCSI direct" feature and has unit numbering consistent with most other Amiga SCSI drivers, so most SCSI utilities should work with it. It does not currently support autosense (which postdates the information I had at the time I wrote it), but it's not alone in that regard, and utilities are suppose to be prepared for that possibility. So far it hasn't seemed to be a problem. The biggest obstacle to SCSI utilities is that many of them require OS 2.0 or later, and many of the machines using this controller may still be running 1.3. Unit numbers in decimal take the form XYZ, where X is the controller number (0 for the first one), Y is the LUN (logical unit number) and Z is the SCSI ID. The driver supports arbitration, so sharing a SCSI bus with another computer is possible. There will be a separate document on SCSI sharing. WARNING: THIS DOES *NOT* BY ITSELF PROVIDE A SHARED FILE SYSTEM - BEWARE!!! Generally speaking, you must insure that a given partition is never mounted by more than one computer simultaneously, or you will destroy your files. The factory driver incorporated an internal buffer to improve performance. In the days of OFS and drives with very little buffering of their own this was helpful, but with FFS and highly buffered drives the driver buffering actually hurts performance, not only by requiring extra data copying, but also by spending significant time (due to the slow PIO interface) transferring data which may never be needed at all, and by limiting the maximum transfer to the size of the internal buffer. This driver does all transfers directly, for better performance in most modern configurations. OFS on old drives may be slower - tough. The speed of this controller can never compete with a decent DMA version, but it tries very hard to be as fast as it can given the limitations of the hardware design. This driver tries hard to avoid waiting for any long periods of time with test loops, making it more multitasking-friendly than the factory driver (which loops at a high priority level while waiting for seek and rotational delays). Things to Watch Out For ----------------------- Unlike some SCSI drivers, scsicltd does not perform gratuitous SCSI operations when a unit is opened. This means that successfully opening a scsicltd unit does not guarantee that the device is present. Some SCSI utilities may assume that it does and generate bogus errors on attempted accesses to nonexistent units. If some device doesn't like the "anonymous initiator" selection method, it may be necessary to patch the driver to use a real SCSI ID. For those who are knowledgeable about driver internals, the ID is currently the very first byte following the RomTag structure. If you don't know what that means and think you need to change the ID, contact me for help. With the default -1 SCSI pseudo-ID, or with any real SCSI ID other than 7, it is possible to access another device at ID 7. However, many SCSI utilities assume that 7 is the controller's ID and won't consider it in a scan. There is currently a 30-second hung timeout on transfers. This should be generous for disk drives, but may be too short for some devices (e.g. DAT drives). This may be fixed in a future version. Be careful getting filesystems from newer systems. There is a 2.04 filesystem which will run under 1.3, and there is a 3.1 filesystem which will run under 2.04, but the 3.1 filesystem will crash under 1.3. Be careful when setting up partitions not to use filesystem features unavailable on another system (due to an earlier filesystem version) which might need to read the same disk. There is one aspect of the driver which unavoidably depends on some knowledge of OS internals, and has to be concerned with such apparently unrelated issues as whether the system has an FPU. I've tried to check the code fairly carefully, but have no way to test most of the configurations. If erratic behavior is observed, be sure to give complete information about your configuration. Also, any OS later than 3.1 will need to be inspected to determine whether the driver is compatible in this way. SCSI Utilities ============== Utilities Tested ---------------- HDToolBox 2.22 (from 2.04 release) Disk partitioning tool HDToolBox 40.4 (from 3.1 release) NOTE: Remaining utilities are all from Aminet SCSIdevs Lists SCSI devices SCSIUtil Tool for miscellaneous SCSI ops SCSIMounter Mounts/dismounts SCSI partitions ReadRDB Saves/restores/prints RDBs RDB-Informer Lists RDB contents MountInfo Lists partition parameters (not strictly a SCSI utility but handy) Problems with SCSI Utilities under OS <2.0 ------------------------------------------ Since OS 1.3 is considered obsolete, many newer programs won't run under it. Of the above utilities, *only* the following are usable under 1.3: HDToolBox 2.22: Sometimes crashes, but usable. CLI usage seems to be more stable. Help gadgets sometimes cause crashes. SCSIdevs: No apparent problem with 1.3. MountInfo: No apparent problem with 1.3. Description and Usage --------------------- Notes: 1) Consult documentation for each program for more details. 2) Except as noted, 2.0 dependencies are only for Kickstart. Workbench 1.3 can still be used. HDToolBox --------- From CLI: HDToolBox scsicltd.device From Workbench: (Needs Tooltype SCSI_DEVICE_NAME=scsicltd.device) This tool allows one to set up RDB partitioning and file system selections. Even if RDB mounting is not available, it can be used to obtain geometry information for MountList entries. The device scan is quite slow when starting, I expect due to a combination of inappropriate retries on selection timeouts, and inappropriate scans of all LUNs of nonexistent IDs. Be patient (it does display its progress). Version 40.4 from release 3.1 is not usable under 1.3 Kickstart. SCSIdevs -------- From CLI: SCSIdevs or: SCSIdevs -dscsicltd.device This utility only recognizes drivers which are already resident, so some other program (including a file system) needs to access scsicltd.device first. If this is done, scsicltd.device will be discovered automatically by virtue of containing the substring "scsi" in its name. Otherwise, it won't be accessed even if the -d option is given. This program expects OpenDevice to report an error for nonexistent devices. Since scsicltd does not do this, there are a number of bogus error messages related to nonexistent units. These are recognizable by the error code 44 in the first part of the scan. SCSIUtil -------- From CLI: SCSIUtil -dscsicltd.device This fails on my system with an AllocMem failure, mentioning CDDA. I suspect that since it was originally written as a CD-ROM tool, it always allocates audio buffers even when not using CDDA-related commands. My 2.5Mb A1000 isn't up to it. If you want to try it, "-i" is a good start for . SCSIMounter ----------- From CLI: SCSIMounter DEVICE scsicltd.device or: SCSIMounter DEVICE scsicltd.device GUI From Workbench: (Needs Tooltype DEVICE=scsicltd.device) This can be used to mount all partitions on a specified drive (based on RDBs), or bring up a GUI for selective options. The GUI option requires 2.0 libraries; the CLI non-GUI mode can run with 1.3 Workbench. All OS version problems are reported by requester rather than by crashing. ReadRDB ------- From CLI: ReadRDB or: ReadRDB DEVICE scsicltd.device UNIT This is primarily a tool for saving and restoring RDBs to/from a file for backup purposes, but also prints some useful information. With no arguments it accesses the drive with the SYS: partition. RDB-Informer ------------ From CLI: RDB-Informer scsicltd.device This lists all RDB information on the specified unit. MountInfo --------- From CLI: MountInfo or: MountInfo This lists available DOS devices (first form), or the parameters of the specified DOS device (second form). This information comes entirely from system data structures, not from the device, but can be used to check results of mounting. Partitioning with RDBs ====================== Although originally intended primarily for autobooting and automounting, Rigid Disk Blocks (RDBs) provide a more convenient way of managing partitions than MountLists, both by keeping the partition description right on the disk itself, and by having friendlier tools than MountList plus a text editor. However, many of the RDB-related programs require OS 2.0 or later to run, so they may not be an option. HDToolBox nominally requires 2.0, but empirically the 2.04 version (2.22) seems to be mostly usable under 1.3. This is of limited value without a 1.3-compatible RDB-based mounter however. One mounting utility is SCSIMounter (on Aminet), which requires 2.0. With RDBs configured, a single SCSIMounter command can be used to mount all partitions. Fake Geometries =============== WARNING: Be sure you know what you're doing if you play these games. Although the intent is for the geometry parameters to correspond to the actual drive layout, and operation may be more efficient in this case, it is possible in principle to lie about the geometry. The actual communication to the SCSI device treats the disk as a uniform array of logical blocks, and any partition arrangement which avoids overlapping ranges of logical block numbers is legal. Be warned, however, that some RDB-based partitioning tools (e.g. HDToolBox) don't allow fake geometry, so that kind of partitioning arrangement may not be transferable to RDBs easily. The range of logical blocks used by a partition is: LowBlock = LowCyl * Surfaces * BlocksPerTrack HighBlock = (HighCyl + 1) * Surfaces * BlocksPerTrack - 1 As long as there is no overlap between these ranges across all partitions, the partitions should operate correctly. It is often necessary to waste some blocks between partitions of differing pseudo-geometries to insure this. There are a couple of uses for fake geometries, primarily because AmigaDOS is able to DiskCopy between any two devices and/or partitions with identical sizes: 1) Pseudo-floppies. If you do a lot of software installation from floppy, you may find it useful to create a few floppy-sized partitions on your HD. Then to install, DiskCopy each floppy to a different partition, and run the install from the pseudo-floppies. 2) Fast backups. DiskCopying one partition to another is a fairly fast way to do backups. Across dissimilar devices this might require faking the geometry on at least one to get the sizes to match exactly. Known Bugs and Deficiencies =========================== No way to set the controller's SCSI ID without patching. No way to adjust the hung timeout, nor to make it longer than 65.535 sec. Autosense not implemented. Latest driver features (TD_GETGEOMETRY, 64-bit addressing, etc.) not implemented. Disconnect/reselect not implemented. Pseudo-autoboot would be useful, with driver installed in RAM as warm-boot-survivable module. Epilogue ======== Good luck with this. Disk drivers are never the easiest things to fiddle with, because they're so basic to the system operation. Email me about any problems, or just to say it works. Fred Wright fw@well.com