advansys.c

GNU Mach 微内核源代码, 基于美国卡内基美隆大学的 Mach 研究项目

/* $Id: advansys.c,v 1.1 1999/04/26 05:54:04 tb Exp $ */
#define ASC_VERSION "3.1E"    /* AdvanSys Driver Version */

/*
 * advansys.c - Linux Host Driver for AdvanSys SCSI Adapters
 * 
 * Copyright (c) 1995-1998 Advanced System Products, Inc.
 * All Rights Reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that redistributions of source
 * code retain the above copyright notice and this comment without
 * modification.
 *
 * There is an AdvanSys Linux WWW page at:
 *  http://www.advansys.com/linux.html
 *
 * The latest version of the AdvanSys driver is available at:
 *  ftp://ftp.advansys.com/pub/linux/linux.tgz
 *
 * Please send questions, comments, bug reports to:
 *  [e-mail] (Bob Frey)
 */

/*

  Documentation for the AdvanSys Driver

  A. Linux Kernel Testing
  B. Adapters Supported by this Driver
  C. Linux v1.2.X - Directions for Adding the AdvanSys Driver
  D. Linux v1.3.1 - v1.3.57 - Directions for Adding the AdvanSys Driver
  E. Linux v1.3.58 and Newer - Upgrading the AdvanSys Driver
  F. Source Comments
  G. Driver Compile Time Options and Debugging
  H. Driver LILO Option
  I. Release History
  J. Known Problems or Issues
  K. Credits
  L. AdvanSys Contact Information

  A. Linux Kernel Testing

     This driver has been tested in the following Linux kernels: v1.2.13,
     v1.3.57, v2.0.33, v2.1.77. These kernel versions are major releases
     of Linux or the latest Linux kernel versions available when this version
     of the driver was released. The driver should also work in earlier
     versions of the Linux kernel. Beginning with v1.3.58 the AdvanSys driver
     is included with all Linux kernels. Please refer to sections C, D, and
     E for instructions on adding or upgrading the AdvanSys driver.

  B. Adapters Supported by this Driver
 
     AdvanSys (Advanced System Products, Inc.) manufactures the following
     RISC-based, Bus-Mastering, Fast (10 Mhz) and Ultra (20 Mhz) Narrow
     (8-bit transfer) SCSI Host Adapters for the ISA, EISA, VL, and PCI
     buses and RISC-based, Bus-Mastering, Ultra (20 Mhz) Wide (16-bit
     transfer) SCSI Host Adapters for the PCI bus.
     
     The CDB counts below indicate the number of SCSI CDB (Command
     Descriptor Block) requests that can be stored in the RISC chip
     cache and board LRAM. A CDB is a single SCSI command. The driver
     detect routine will display the number of CDBs available for each
     adapter detected. The number of CDBs used by the driver can be
     lowered in the BIOS by changing the 'Host Queue Size' adapter setting.

     Connectivity Products:
        ABP510/5150 - Bus-Master ISA (240 CDB) (Footnote 1)
        ABP5140 - Bus-Master ISA PnP (16 CDB) (Footnote 1, 3)
        ABP5142 - Bus-Master ISA PnP with floppy (16 CDB) (Footnote 4)
        ABP920 - Bus-Master PCI (16 CDB)
        ABP930 - Bus-Master PCI (16 CDB) (Footnote 5)
        ABP930U - Bus-Master PCI Ultra (16 CDB)
        ABP930UA - Bus-Master PCI Ultra (16 CDB)
        ABP960 - Bus-Master PCI MAC/PC (16 CDB) (Footnote 2)
        ABP960U - Bus-Master PCI MAC/PC Ultra (16 CDB) (Footnote 2)
     
     Single Channel Products:
        ABP542 - Bus-Master ISA with floppy (240 CDB)
        ABP742 - Bus-Master EISA (240 CDB)
        ABP842 - Bus-Master VL (240 CDB)
        ABP940 - Bus-Master PCI (240 CDB)
        ABP940U - Bus-Master PCI Ultra (240 CDB)
        ABP970 - Bus-Master PCI MAC/PC (240 CDB)
        ABP970U - Bus-Master PCI MAC/PC Ultra (240 CDB)
        ABP940UW - Bus-Master PCI Ultra-Wide (240 CDB)
     
     Multi Channel Products:
        ABP752 - Dual Channel Bus-Master EISA (240 CDB Per Channel)
        ABP852 - Dual Channel Bus-Master VL (240 CDB Per Channel)
        ABP950 - Dual Channel Bus-Master PCI (240 CDB Per Channel)
        ABP980 - Four Channel Bus-Master PCI (240 CDB Per Channel)
        ABP980U - Four Channel Bus-Master PCI Ultra (240 CDB Per Channel)
     
     Footnotes:
       1. This board has been shipped by HP with the 4020i CD-R drive.
          The board has no BIOS so it cannot control a boot device, but
          it can control any secondary SCSI device.
       2. This board has been sold by Iomega as a Jaz Jet PCI adapter.
       3. This board has been sold by SIIG as the i540 SpeedMaster.
       4. This board has been sold by SIIG as the i542 SpeedMaster.
       5. This board has been sold by SIIG as the Fast SCSI Pro PCI.

  C. Linux v1.2.X - Directions for Adding the AdvanSys Driver

     These directions apply to v1.2.13. For versions that follow v1.2.13.
     but precede v1.3.57 some of the changes for Linux v1.3.X listed
     below may need to be modified or included. A patch is available
     for v1.2.13 from the AdvanSys WWW and FTP sites.
 
     There are two source files: advansys.h and advansys.c. Copy
     both of these files to the directory /usr/src/linux/drivers/scsi.
    
     1. Add the following line to /usr/src/linux/arch/i386/config.in
        after "comment 'SCSI low-level drivers'":
    
          bool 'AdvanSys SCSI support' CONFIG_SCSI_ADVANSYS y
    
     2. Add the following lines to /usr/src/linux/drivers/scsi/hosts.c
        after "#include "hosts.h"":
    
          #ifdef CONFIG_SCSI_ADVANSYS
          #include "advansys.h"
          #endif
    
        and after "static Scsi_Host_Template builtin_scsi_hosts[] =":
    
          #ifdef CONFIG_SCSI_ADVANSYS
          ADVANSYS,
          #endif
    
     3. Add the following lines to /usr/src/linux/drivers/scsi/Makefile:
    
          ifdef CONFIG_SCSI_ADVANSYS
          SCSI_SRCS := $(SCSI_SRCS) advansys.c
          SCSI_OBJS := $(SCSI_OBJS) advansys.o
          else
          SCSI_MODULE_OBJS := $(SCSI_MODULE_OBJS) advansys.o
          endif

     4. (Optional) If you would like to enable the LILO command line
        and /etc/lilo.conf 'advansys' option, make the following changes.
        This option can be used to disable I/O port scanning or to limit
        I/O port scanning to specific addresses. Refer to the 'Driver
        LILO Option' section below. Add the following lines to
        /usr/src/linux/init/main.c in the prototype section:

          extern void advansys_setup(char *str, int *ints);

        and add the following lines to the bootsetups[] array.

          #ifdef CONFIG_SCSI_ADVANSYS
             { "advansys=", advansys_setup },
          #endif

     5. If you have the HP 4020i CD-R driver and Linux v1.2.X you should
        add a fix to the CD-ROM target driver. This fix will allow
        you to mount CDs with the iso9660 file system. Linux v1.3.X
        already has this fix. In the file /usr/src/linux/drivers/scsi/sr.c
        and function get_sectorsize() after the line:

        if(scsi_CDs[i].sector_size == 0) scsi_CDs[i].sector_size = 2048;

        add the following line:

        if(scsi_CDs[i].sector_size == 2340) scsi_CDs[i].sector_size = 2048;

     6. In the directory /usr/src/linux run 'make config' to configure
        the AdvanSys driver, then run 'make vmlinux' or 'make zlilo' to
        make the kernel. If the AdvanSys driver is not configured, then
        a loadable module can be built by running 'make modules' and
        'make modules_install'. Use 'insmod' and 'rmmod' to install
        and remove advansys.o.
 
  D. Linux v1.3.1 - v1.3.57 - Directions for Adding the AdvanSys Driver

     These directions apply to v1.3.57. For versions that precede v1.3.57
     some of these changes may need to be modified or eliminated. A patch
     is available for v1.3.57 from the AdvanSys WWW and FTP sites.
     Beginning with v1.3.58 this driver is included with the Linux
     distribution eliminating the need for making any changes.

     There are two source files: advansys.h and advansys.c. Copy
     both of these files to the directory /usr/src/linux/drivers/scsi.
   
     1. Add the following line to /usr/src/linux/drivers/scsi/Config.in
        after "comment 'SCSI low-level drivers'":
   
          dep_tristate 'AdvanSys SCSI support' CONFIG_SCSI_ADVANSYS $CONFIG_SCSI
   
     2. Add the following lines to /usr/src/linux/drivers/scsi/hosts.c
        after "#include "hosts.h"":
   
          #ifdef CONFIG_SCSI_ADVANSYS
          #include "advansys.h"
          #endif
   
        and after "static Scsi_Host_Template builtin_scsi_hosts[] =":
   
          #ifdef CONFIG_SCSI_ADVANSYS
          ADVANSYS,
          #endif
   
     3. Add the following lines to /usr/src/linux/drivers/scsi/Makefile:
   
          ifeq ($(CONFIG_SCSI_ADVANSYS),y)
          L_OBJS += advansys.o
          else
            ifeq ($(CONFIG_SCSI_ADVANSYS),m)
            M_OBJS += advansys.o
            endif
          endif
   
     4. Add the following line to /usr/src/linux/include/linux/proc_fs.h
        in the enum scsi_directory_inos array:
   
          PROC_SCSI_ADVANSYS,
   
     5. (Optional) If you would like to enable the LILO command line
        and /etc/lilo.conf 'advansys' option, make the following changes.
        This option can be used to disable I/O port scanning or to limit
        I/O port scanning to specific addresses. Refer to the 'Driver
        LILO Option' section below. Add the following lines to
        /usr/src/linux/init/main.c in the prototype section:
   
          extern void advansys_setup(char *str, int *ints);
   
        and add the following lines to the bootsetups[] array.
   
          #ifdef CONFIG_SCSI_ADVANSYS
             { "advansys=", advansys_setup },
          #endif
   
     6. In the directory /usr/src/linux run 'make config' to configure
        the AdvanSys driver, then run 'make vmlinux' or 'make zlilo' to
        make the kernel. If the AdvanSys driver is not configured, then
        a loadable module can be built by running 'make modules' and
        'make modules_install'. Use 'insmod' and 'rmmod' to install
        and remove advansys.o.

  E. Linux v1.3.58 and Newer - Upgrading the AdvanSys Driver

     To upgrade the AdvanSys driver in a Linux v1.3.58 and newer
     kernel, first check the version of the current driver. The
     version is defined by the manifest constant ASC_VERSION at
     the beginning of advansys.c. The new driver should have a
     ASC_VERSION value greater than the current version. To install
     the new driver rename advansys.c and advansys.h in the Linux
     kernel source tree drivers/scsi directory to different names
     or save them to a different directory in case you want to revert
     to the old version of the driver. After the old driver is saved
     copy the new advansys.c and advansys.h to drivers/scsi, rebuild
     the kernel, and install the new kernel. No other changes are needed.

  F. Source Comments
 
     1. Use tab stops set to 4 for the source files. For vi use 'se tabstops=4'.
 
     2. This driver should be maintained in multiple files. But to make
        it easier to include with Linux and to follow Linux conventions,
        the whole driver is maintained in the source files advansys.h and
        advansys.c. In this file logical sections of the driver begin with
        a comment that contains '---'. The following are the logical sections
        of the driver below.
 
           --- Linux Version
           --- Linux Include Files 
           --- Driver Options
           --- Debugging Header
           --- Asc Library Constants and Macros
           --- Adv Library Constants and Macros
           --- Driver Constants and Macros
           --- Driver Structures
           --- Driver Data
           --- Driver Function Prototypes
           --- Linux 'Scsi_Host_Template' and advansys_setup() Functions
           --- Loadable Driver Support
           --- Miscellaneous Driver Functions
           --- Functions Required by the Asc Library
           --- Functions Required by the Adv Library
           --- Tracing and Debugging Functions
           --- Asc Library Functions
           --- Adv Library Functions
 
     3. The string 'XXX' is used to flag code that needs to be re-written
        or that contains a problem that needs to be addressed.
 
     4. I have stripped comments from and reformatted the source for the
        Asc Library and Adv Library to reduce the size of this file. This
        source can be found under the following headings. The Asc Library
        is used to support Narrow Boards. The Adv Library is used to
        support Wide Boards.
 
           --- Asc Library Constants and Macros
           --- Adv Library Constants and Macros
           --- Asc Library Functions
           --- Adv Library Functions
 
  G. Driver Compile Time Options and Debugging
 
     In this source file the following constants can be defined. They are
     defined in the source below. Both of these options are enabled by
     default.
 
     1. ADVANSYS_ASSERT - Enable driver assertions (Def: Enabled)

        Enabling this option adds assertion logic statements to the
        driver. If an assertion fails a message will be displayed to
        the console, but the system will continue to operate. Any
        assertions encountered should be reported to the person
        responsible for the driver. Assertion statements may proactively
        detect problems with the driver and facilitate fixing these
        problems. Enabling assertions will add a small overhead to the
        execution of the driver.

     2. ADVANSYS_DEBUG - Enable driver debugging (Def: Disabled)

        Enabling this option adds tracing functions to the driver and
        the ability to set a driver tracing level at boot time. This
        option will also export symbols not required outside the driver to
        the kernel name space. This option is very useful for debugging
        the driver, but it will add to the size of the driver execution
        image and add overhead to the execution of the driver.
 
        The amount of debugging output can be controlled with the global
        variable 'asc_dbglvl'. The higher the number the more output. By
        default the debug level is 0.
        
        If the driver is loaded at boot time and the LILO Driver Option
        is included in the system, the debug level can be changed by
        specifying a 5th (ASC_NUM_IOPORT_PROBE + 1) I/O Port. The
        first three hex digits of the pseudo I/O Port must be set to
        'deb' and the fourth hex digit specifies the debug level: 0 - F.
        The following command line will look for an adapter at 0x330
        and set the debug level to 2.

           linux advansys=0x330,0,0,0,0xdeb2

        If the driver is built as a loadable module this variable can be
        defined when the driver is loaded. The following insmod command
        will set the debug level to one.
  
           insmod advansys.o asc_dbglvl=1