Documentation/scsi/advansys.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =====================
   4 AdvanSys Driver Notes
   5 =====================
   6
   7 AdvanSys (Advanced System Products, Inc.) manufactures the following
   8 RISC-based, Bus-Mastering, Fast (10 Mhz) and Ultra (20 Mhz) Narrow
   9 (8-bit transfer) SCSI Host Adapters for the ISA, EISA, VL, and PCI
  10 buses and RISC-based, Bus-Mastering, Ultra (20 Mhz) Wide (16-bit
  11 transfer) SCSI Host Adapters for the PCI bus.
  12
  13 The CDB counts below indicate the number of SCSI CDB (Command
  14 Descriptor Block) requests that can be stored in the RISC chip
  15 cache and board LRAM. A CDB is a single SCSI command. The driver
  16 detect routine will display the number of CDBs available for each
  17 adapter detected. The number of CDBs used by the driver can be
  18 lowered in the BIOS by changing the 'Host Queue Size' adapter setting.
  19
  20 Laptop Products:
  21   - ABP-480 - Bus-Master CardBus (16 CDB)
  22
  23 Connectivity Products:
  24    - ABP510/5150 - Bus-Master ISA (240 CDB)
  25    - ABP5140 - Bus-Master ISA PnP (16 CDB)
  26    - ABP5142 - Bus-Master ISA PnP with floppy (16 CDB)
  27    - ABP902/3902 - Bus-Master PCI (16 CDB)
  28    - ABP3905 - Bus-Master PCI (16 CDB)
  29    - ABP915 - Bus-Master PCI (16 CDB)
  30    - ABP920 - Bus-Master PCI (16 CDB)
  31    - ABP3922 - Bus-Master PCI (16 CDB)
  32    - ABP3925 - Bus-Master PCI (16 CDB)
  33    - ABP930 - Bus-Master PCI (16 CDB)
  34    - ABP930U - Bus-Master PCI Ultra (16 CDB)
  35    - ABP930UA - Bus-Master PCI Ultra (16 CDB)
  36    - ABP960 - Bus-Master PCI MAC/PC (16 CDB)
  37    - ABP960U - Bus-Master PCI MAC/PC Ultra (16 CDB)
  38
  39 Single Channel Products:
  40    - ABP542 - Bus-Master ISA with floppy (240 CDB)
  41    - ABP742 - Bus-Master EISA (240 CDB)
  42    - ABP842 - Bus-Master VL (240 CDB)
  43    - ABP940 - Bus-Master PCI (240 CDB)
  44    - ABP940U - Bus-Master PCI Ultra (240 CDB)
  45    - ABP940UA/3940UA - Bus-Master PCI Ultra (240 CDB)
  46    - ABP970 - Bus-Master PCI MAC/PC (240 CDB)
  47    - ABP970U - Bus-Master PCI MAC/PC Ultra (240 CDB)
  48    - ABP3960UA - Bus-Master PCI MAC/PC Ultra (240 CDB)
  49    - ABP940UW/3940UW - Bus-Master PCI Ultra-Wide (253 CDB)
  50    - ABP970UW - Bus-Master PCI MAC/PC Ultra-Wide (253 CDB)
  51    - ABP3940U2W - Bus-Master PCI LVD/Ultra2-Wide (253 CDB)
  52
  53 Multi-Channel Products:
  54    - ABP752 - Dual Channel Bus-Master EISA (240 CDB Per Channel)
  55    - ABP852 - Dual Channel Bus-Master VL (240 CDB Per Channel)
  56    - ABP950 - Dual Channel Bus-Master PCI (240 CDB Per Channel)
  57    - ABP950UW - Dual Channel Bus-Master PCI Ultra-Wide (253 CDB Per Channel)
  58    - ABP980 - Four Channel Bus-Master PCI (240 CDB Per Channel)
  59    - ABP980U - Four Channel Bus-Master PCI Ultra (240 CDB Per Channel)
  60    - ABP980UA/3980UA - Four Channel Bus-Master PCI Ultra (16 CDB Per Chan.)
  61    - ABP3950U2W - Bus-Master PCI LVD/Ultra2-Wide and Ultra-Wide (253 CDB)
  62    - ABP3950U3W - Bus-Master PCI Dual LVD2/Ultra3-Wide (253 CDB)
  63
  64 Driver Compile Time Options and Debugging
  65 =========================================
  66
  67 The following constants can be defined in the source file.
  68
  69 1. ADVANSYS_ASSERT - Enable driver assertions (Def: Enabled)
  70
  71    Enabling this option adds assertion logic statements to the
  72    driver. If an assertion fails a message will be displayed to
  73    the console, but the system will continue to operate. Any
  74    assertions encountered should be reported to the person
  75    responsible for the driver. Assertion statements may proactively
  76    detect problems with the driver and facilitate fixing these
  77    problems. Enabling assertions will add a small overhead to the
  78    execution of the driver.
  79
  80 2. ADVANSYS_DEBUG - Enable driver debugging (Def: Disabled)
  81
  82    Enabling this option adds tracing functions to the driver and the
  83    ability to set a driver tracing level at boot time.  This option is
  84    very useful for debugging the driver, but it will add to the size
  85    of the driver execution image and add overhead to the execution of
  86    the driver.
  87
  88    The amount of debugging output can be controlled with the global
  89    variable 'asc_dbglvl'. The higher the number the more output. By
  90    default the debug level is 0.
  91
  92    If the driver is loaded at boot time and the LILO Driver Option
  93    is included in the system, the debug level can be changed by
  94    specifying a 5th (ASC_NUM_IOPORT_PROBE + 1) I/O Port. The
  95    first three hex digits of the pseudo I/O Port must be set to
  96    'deb' and the fourth hex digit specifies the debug level: 0 - F.
  97    The following command line will look for an adapter at 0x330
  98    and set the debug level to 2::
  99
 100       linux advansys=0x330,0,0,0,0xdeb2
 101
 102    If the driver is built as a loadable module this variable can be
 103    defined when the driver is loaded. The following insmod command
 104    will set the debug level to one::
 105
 106       insmod advansys.o asc_dbglvl=1
 107
 108    Debugging Message Levels:
 109
 110
 111       ==== ==================
 112       0    Errors Only
 113       1    High-Level Tracing
 114       2-N  Verbose Tracing
 115       ==== ==================
 116
 117    To enable debug output to console, please make sure that:
 118
 119    a. System and kernel logging is enabled (syslogd, klogd running).
 120    b. Kernel messages are routed to console output. Check
 121       /etc/syslog.conf for an entry similar to this::
 122
 123            kern.*                  /dev/console
 124
 125    c. klogd is started with the appropriate -c parameter
 126       (e.g. klogd -c 8)
 127
 128    This will cause printk() messages to be be displayed on the
 129    current console. Refer to the klogd(8) and syslogd(8) man pages
 130    for details.
 131
 132    Alternatively you can enable printk() to console with this
 133    program. However, this is not the 'official' way to do this.
 134
 135    Debug output is logged in /var/log/messages.
 136
 137    ::
 138
 139      main()
 140      {
 141              syscall(103, 7, 0, 0);
 142      }
 143
 144    Increasing LOG_BUF_LEN in kernel/printk.c to something like
 145    40960 allows more debug messages to be buffered in the kernel
 146    and written to the console or log file.
 147
 148 3. ADVANSYS_STATS - Enable statistics (Def: Enabled)
 149
 150    Enabling this option adds statistics collection and display
 151    through /proc to the driver. The information is useful for
 152    monitoring driver and device performance. It will add to the
 153    size of the driver execution image and add minor overhead to
 154    the execution of the driver.
 155
 156    Statistics are maintained on a per adapter basis. Driver entry
 157    point call counts and transfer size counts are maintained.
 158    Statistics are only available for kernels greater than or equal
 159    to v1.3.0 with the CONFIG_PROC_FS (/proc) file system configured.
 160
 161    AdvanSys SCSI adapter files have the following path name format::
 162
 163       /proc/scsi/advansys/{0,1,2,3,...}
 164
 165    This information can be displayed with cat. For example::
 166
 167       cat /proc/scsi/advansys/0
 168
 169    When ADVANSYS_STATS is not defined the AdvanSys /proc files only
 170    contain adapter and device configuration information.
 171
 172 Driver LILO Option
 173 ==================
 174
 175 If init/main.c is modified as described in the 'Directions for Adding
 176 the AdvanSys Driver to Linux' section (B.4.) above, the driver will
 177 recognize the 'advansys' LILO command line and /etc/lilo.conf option.
 178 This option can be used to either disable I/O port scanning or to limit
 179 scanning to 1 - 4 I/O ports. Regardless of the option setting EISA and
 180 PCI boards will still be searched for and detected. This option only
 181 affects searching for ISA and VL boards.
 182
 183 Examples:
 184   1. Eliminate I/O port scanning:
 185
 186      boot::
 187
 188         linux advansys=
 189
 190      or::
 191
 192         boot: linux advansys=0x0
 193
 194   2. Limit I/O port scanning to one I/O port:
 195
 196      boot::
 197
 198         linux advansys=0x110
 199
 200   3. Limit I/O port scanning to four I/O ports:
 201
 202      boot::
 203
 204         linux advansys=0x110,0x210,0x230,0x330
 205
 206 For a loadable module the same effect can be achieved by setting
 207 the 'asc_iopflag' variable and 'asc_ioport' array when loading
 208 the driver, e.g.::
 209
 210       insmod advansys.o asc_iopflag=1 asc_ioport=0x110,0x330
 211
 212 If ADVANSYS_DEBUG is defined a 5th (ASC_NUM_IOPORT_PROBE + 1)
 213 I/O Port may be added to specify the driver debug level. Refer to
 214 the 'Driver Compile Time Options and Debugging' section above for
 215 more information.
 216
 217 Credits (Chronological Order)
 218 =============================
 219
 220 Bob Frey <bfrey@turbolinux.com.cn> wrote the AdvanSys SCSI driver
 221 and maintained it up to 3.3F. He continues to answer questions
 222 and help maintain the driver.
 223
 224 Nathan Hartwell <mage@cdc3.cdc.net> provided the directions and
 225 basis for the Linux v1.3.X changes which were included in the
 226 1.2 release.
 227
 228 Thomas E Zerucha <zerucha@shell.portal.com> pointed out a bug
 229 in advansys_biosparam() which was fixed in the 1.3 release.
 230
 231 Erik Ratcliffe <erik@caldera.com> has done testing of the
 232 AdvanSys driver in the Caldera releases.
 233
 234 Rik van Riel <H.H.vanRiel@fys.ruu.nl> provided a patch to
 235 AscWaitTixISRDone() which he found necessary to make the
 236 driver work with a SCSI-1 disk.
 237
 238 Mark Moran <mmoran@mmoran.com> has helped test Ultra-Wide
 239 support in the 3.1A driver.
 240
 241 Doug Gilbert <dgilbert@interlog.com> has made changes and
 242 suggestions to improve the driver and done a lot of testing.
 243
 244 Ken Mort <ken@mort.net> reported a DEBUG compile bug fixed
 245 in 3.2K.
 246
 247 Tom Rini <trini@kernel.crashing.org> provided the CONFIG_ISA
 248 patch and helped with PowerPC wide and narrow board support.
 249
 250 Philip Blundell <philb@gnu.org> provided an
 251 advansys_interrupts_enabled patch.
 252
 253 Dave Jones <dave@denial.force9.co.uk> reported the compiler
 254 warnings generated when CONFIG_PROC_FS was not defined in
 255 the 3.2M driver.
 256
 257 Jerry Quinn <jlquinn@us.ibm.com> fixed PowerPC support (endian
 258 problems) for wide cards.
 259
 260 Bryan Henderson <bryanh@giraffe-data.com> helped debug narrow
 261 card error handling.
 262
 263 Manuel Veloso <veloso@pobox.com> worked hard on PowerPC narrow
 264 board support and fixed a bug in AscGetEEPConfig().
 265
 266 Arnaldo Carvalho de Melo <acme@conectiva.com.br> made
 267 save_flags/restore_flags changes.
 268
 269 Andy Kellner <AKellner@connectcom.net> continued the Advansys SCSI
 270 driver development for ConnectCom (Version > 3.3F).
 271
 272 Ken Witherow for extensive testing during the development of version 3.4.