xref: /linux/Documentation/scsi/advansys.rst (revision 26fbb4c8c7c3ee9a4c3b4de555a8587b5a19154e)
1.. SPDX-License-Identifier: GPL-2.0
2
3=====================
4AdvanSys Driver Notes
5=====================
6
7AdvanSys (Advanced System Products, Inc.) manufactures the following
8RISC-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
10buses and RISC-based, Bus-Mastering, Ultra (20 Mhz) Wide (16-bit
11transfer) SCSI Host Adapters for the PCI bus.
12
13The CDB counts below indicate the number of SCSI CDB (Command
14Descriptor Block) requests that can be stored in the RISC chip
15cache and board LRAM. A CDB is a single SCSI command. The driver
16detect routine will display the number of CDBs available for each
17adapter detected. The number of CDBs used by the driver can be
18lowered in the BIOS by changing the 'Host Queue Size' adapter setting.
19
20Laptop Products:
21  - ABP-480 - Bus-Master CardBus (16 CDB)
22
23Connectivity 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
39Single 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
53Multi-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
64Driver Compile Time Options and Debugging
65=========================================
66
67The following constants can be defined in the source file.
68
691. 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
802. 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 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
1483. 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
172Driver LILO Option
173==================
174
175If init/main.c is modified as described in the 'Directions for Adding
176the AdvanSys Driver to Linux' section (B.4.) above, the driver will
177recognize the 'advansys' LILO command line and /etc/lilo.conf option.
178This option can be used to either disable I/O port scanning or to limit
179scanning to 1 - 4 I/O ports. Regardless of the option setting EISA and
180PCI boards will still be searched for and detected. This option only
181affects searching for ISA and VL boards.
182
183Examples:
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
206For a loadable module the same effect can be achieved by setting
207the 'asc_iopflag' variable and 'asc_ioport' array when loading
208the driver, e.g.::
209
210      insmod advansys.o asc_iopflag=1 asc_ioport=0x110,0x330
211
212If ADVANSYS_DEBUG is defined a 5th (ASC_NUM_IOPORT_PROBE + 1)
213I/O Port may be added to specify the driver debug level. Refer to
214the 'Driver Compile Time Options and Debugging' section above for
215more information.
216
217Credits (Chronological Order)
218=============================
219
220Bob Frey <bfrey@turbolinux.com.cn> wrote the AdvanSys SCSI driver
221and maintained it up to 3.3F. He continues to answer questions
222and help maintain the driver.
223
224Nathan Hartwell <mage@cdc3.cdc.net> provided the directions and
225basis for the Linux v1.3.X changes which were included in the
2261.2 release.
227
228Thomas E Zerucha <zerucha@shell.portal.com> pointed out a bug
229in advansys_biosparam() which was fixed in the 1.3 release.
230
231Erik Ratcliffe <erik@caldera.com> has done testing of the
232AdvanSys driver in the Caldera releases.
233
234Rik van Riel <H.H.vanRiel@fys.ruu.nl> provided a patch to
235AscWaitTixISRDone() which he found necessary to make the
236driver work with a SCSI-1 disk.
237
238Mark Moran <mmoran@mmoran.com> has helped test Ultra-Wide
239support in the 3.1A driver.
240
241Doug Gilbert <dgilbert@interlog.com> has made changes and
242suggestions to improve the driver and done a lot of testing.
243
244Ken Mort <ken@mort.net> reported a DEBUG compile bug fixed
245in 3.2K.
246
247Tom Rini <trini@kernel.crashing.org> provided the CONFIG_ISA
248patch and helped with PowerPC wide and narrow board support.
249
250Philip Blundell <philb@gnu.org> provided an
251advansys_interrupts_enabled patch.
252
253Dave Jones <dave@denial.force9.co.uk> reported the compiler
254warnings generated when CONFIG_PROC_FS was not defined in
255the 3.2M driver.
256
257Jerry Quinn <jlquinn@us.ibm.com> fixed PowerPC support (endian
258problems) for wide cards.
259
260Bryan Henderson <bryanh@giraffe-data.com> helped debug narrow
261card error handling.
262
263Manuel Veloso <veloso@pobox.com> worked hard on PowerPC narrow
264board support and fixed a bug in AscGetEEPConfig().
265
266Arnaldo Carvalho de Melo <acme@conectiva.com.br> made
267save_flags/restore_flags changes.
268
269Andy Kellner <AKellner@connectcom.net> continued the Advansys SCSI
270driver development for ConnectCom (Version > 3.3F).
271
272Ken Witherow for extensive testing during the development of version 3.4.
273