2               -=< The IBM Microchannel SCSI-Subsystem >=-
   4                         for the IBM PS/2 series
   6                   Low Level Software-Driver for Linux
   8     Copyright (c) 1995 Strom Systems, Inc. under the terms of the GNU 
   9  General Public License. Originally written by Martin Kolinek, December 1995.
  10   Officially modified and maintained by Michael Lang since January 1999.
  12                               Version 4.0a
  14   Last update: January 3, 2001
  16   Before you Start
  17   ----------------
  18   This is the common README.ibmmca file for all driver releases of the 
  19   IBM MCA SCSI driver for Linux. Please note, that driver releases 4.0
  20   or newer do not work with kernel versions older than 2.4.0, while driver
  21   versions older than 4.0 do not work with kernels 2.4.0 or later! If you
  22   try to compile your kernel with the wrong driver source, the 
  23   compilation is aborted and you get a corresponding error message. This is
  24   no bug in the driver; it prevents you from using the wrong source code
  25   with the wrong kernel version.
  27   Authors of this Driver
  28   ----------------------
  29    - Chris Beauregard (improvement of the SCSI-device mapping by the driver)
  30    - Martin Kolinek (origin, first release of this driver)
  31    - Klaus Kudielka (multiple SCSI-host management/detection, adaption to
  32                      Linux Kernel 2.1.x, module support)
  33    - Michael Lang (assigning original pun/lun mapping, dynamical ldn
  34                    assignment, rewritten adapter detection, this file, 
  35                    patches, official driver maintenance and subsequent 
  36                    debugging, related with the driver)
  38   Table of Contents
  39   -----------------
  40   1 Abstract
  41   2 Driver Description
  42     2.1  IBM SCSI-Subsystem Detection
  43     2.2  Physical Units, Logical Units, and Logical Devices
  44     2.3  SCSI-Device Recognition and dynamical ldn Assignment
  45     2.4  SCSI-Device Order
  46     2.5  Regular SCSI-Command-Processing
  47     2.6  Abort & Reset Commands
  48     2.7  Disk Geometry
  49     2.8  Kernel Boot Option
  50     2.9  Driver Module Support
  51     2.10 Multiple Hostadapter Support
  52     2.11 /proc/scsi-Filesystem Information
  53     2.12 /proc/mca-Filesystem Information
  54     2.13 Supported IBM SCSI-Subsystems
  55     2.14 Linux Kernel Versions
  56   3 Code History
  57   4 To do
  58   5 Users' Manual
  59     5.1 Commandline Parameters
  60     5.2 Troubleshooting
  61     5.3 Bug reports
  62     5.4 Support WWW-page
  63   6 References
  64   7 Credits to
  65     7.1 People
  66     7.2 Sponsors & Supporters
  67   8 Trademarks
  68   9 Disclaimer
  70                              * * *
  72   1 Abstract
  73   ----------
  74   This README-file describes the IBM SCSI-subsystem low level driver for
  75   Linux. The descriptions which were formerly kept in the source code have
  76   been taken out of this file to simplify the codes readability. The driver
  77   description has been updated, as most of the former description was already
  78   quite outdated. The history of the driver development is also kept inside
  79   here. Multiple historical developments have been summarized to shorten the
  80   text size a bit. At the end of this file you can find a small manual for
  81   this driver and hints to get it running on your machine.
  83   2 Driver Description
  84   --------------------
  85   2.1 IBM SCSI-Subsystem Detection
  86   --------------------------------
  87   This is done in the ibmmca_detect() function. It first checks, if the
  88   Microchannel-bus support is enabled, as the IBM SCSI-subsystem needs the
  89   Microchannel. In a next step, a free interrupt is chosen and the main
  90   interrupt handler is connected to it to handle answers of the SCSI-
  91   subsystem(s). If the F/W SCSI-adapter is forced by the BIOS to use IRQ11
  92   instead of IRQ14, IRQ11 is used for the IBM SCSI-2 F/W adapter. In a 
  93   further step it is checked, if the adapter gets detected by force from
  94   the kernel commandline, where the I/O port and the SCSI-subsystem id can 
  95   be specified. The next step checks if there is an integrated SCSI-subsystem
  96   installed. This register area is fixed through all IBM PS/2 MCA-machines 
  97   and appears as something like a virtual slot 10 of the MCA-bus. On most
  98   PS/2 machines, the POS registers of slot 10 are set to 0xff or 0x00 if not
  99   integrated SCSI-controller is available. But on certain PS/2s, like model 
 100   9595, this slot 10 is used to store other information which at earlier
 101   stage confused the driver and resulted in the detection of some ghost-SCSI. 
 102   If POS-register 2 and 3 are not 0x00 and not 0xff, but all other POS
 103   registers are either 0xff or 0x00, there must be an integrated SCSI-
 104   subsystem present and it will be registered as IBM Integrated SCSI-
 105   Subsystem. The next step checks, if there is a slot-adapter installed on 
 106   the MCA-bus. To get this, the first two POS-registers, that represent the 
 107   adapter ID are checked. If they fit to one of the ids, stored in the 
 108   adapter list, a SCSI-subsystem is assumed to be found in a slot and will be 
 109   registered. This check is done through all possible MCA-bus slots to allow 
 110   more than one SCSI-adapter to be present in the PS/2-system and this is 
 111   already the first point of problems. Looking into the technical reference 
 112   manual for the IBM PS/2 common interfaces, the POS2 register must have 
 113   different interpretation of its single bits to avoid overlapping I/O
 114   regions. While one can assume, that the integrated subsystem has a fix 
 115   I/O-address at 0x3540 - 0x3547, further installed IBM SCSI-adapters must 
 116   use a different I/O-address. This is expressed by bit 1 to 3 of POS2 
 117   (multiplied by 8 + 0x3540). Bits 2 and 3 are reserved for the integrated 
 118   subsystem, but not for the adapters! The following list shows, how the 
 119   bits of POS2 and POS3 should be interpreted.
 121   The POS2-register of all PS/2 models' integrated SCSI-subsystems has the 
 122   following interpretation of bits:
 123                           Bit 7 - 4 : Chip Revision ID (Release)
 124                           Bit 3 - 2 : Reserved
 125                           Bit 1     : 8k NVRAM Disabled
 126                           Bit 0     : Chip Enable (EN-Signal)
 127   The POS3-register is interpreted as follows (for most IBM SCSI-subsys.):
 128                           Bit 7 - 5 : SCSI ID
 129                           Bit 4 - 0 : Reserved = 0
 130   The slot-adapters have different interpretation of these bits. The IBM SCSI
 131   adapter (w/Cache) and the IBM SCSI-2 F/W adapter use the following
 132   interpretation of the POS2 register:
 133                           Bit 7 - 4 : ROM Segment Address Select
 134                           Bit 3 - 1 : Adapter I/O Address Select (*8+0x3540)
 135                           Bit 0     : Adapter Enable (EN-Signal)
 136   and for the POS3 register:
 137                           Bit 7 - 5 : SCSI ID 
 138                           Bit 4     : Fairness Enable (SCSI ID3 f. F/W)
 139                           Bit 3 - 0 : Arbitration Level
 140   The most modern product of the series is the IBM SCSI-2 F/W adapter, it 
 141   allows dual-bus SCSI and SCSI-wide addressing, which means, PUNs may be
 142   between 0 and 15. Here, Bit 4 is the high-order bit of the 4-bit wide
 143   adapter PUN expression. In short words, this means, that IBM PS/2 machines 
 144   can only support 1 single integrated subsystem by default. Additional
 145   slot-adapters get ports assigned by the automatic configuration tool.
 147   One day I found a patch in ibmmca_detect(), forcing the I/O-address to be 
 148   0x3540 for integrated SCSI-subsystems, there was a remark placed, that on 
 149   integrated IBM SCSI-subsystems of model 56, the POS2 register was showing 5.
 150   This means, that really for these models, POS2 has to be interpreted
 151   sticking to the technical reference guide. In this case, the bit 2 (4) is 
 152   a reserved bit and may not be interpreted. These differences between the 
 153   adapters and the integrated controllers are taken into account by the 
 154   detection routine of the driver on from version >3.0g. 
 156   Every time, a SCSI-subsystem is discovered, the ibmmca_register() function
 157   is called. This function checks first, if the requested area for the I/O-
 158   address of this SCSI-subsystem is still available and assigns this I/O-
 159   area to the SCSI-subsystem. There are always 8 sequential I/O-addresses
 160   taken for each individual SCSI-subsystem found, which are:
 162     Offset            Type                  Permissions
 163       0     Command Interface Register 1    Read/Write
 164       1     Command Interface Register 2    Read/Write
 165       2     Command Interface Register 3    Read/Write
 166       3     Command Interface Register 4    Read/Write
 167       4     Attention Register              Read/Write
 168       5     Basic Control Register          Read/Write
 169       6     Interrupt Status Register       Read
 170       7     Basic Status Register           Read
 172   After the I/O-address range is assigned, the host-adapter is assigned
 173   to a local structure which keeps all adapter information needed for the
 174   driver itself and the mid- and higher-level SCSI-drivers. The SCSI pun/lun
 175   and the adapters' ldn tables are initialized and get probed afterwards by
 176   the check_devices() function. If no further adapters are found, 
 177   ibmmca_detect() quits.
 179   2.2 Physical Units, Logical Units, and Logical Devices
 180   ------------------------------------------------------
 181   There can be up to 56 devices on the SCSI bus (besides the adapter):
 182   there are up to 7 "physical units" (each identified by physical unit 
 183   number or pun, also called the scsi id, this is the number you select
 184   with hardware jumpers), and each physical unit can have up to 8 
 185   "logical units" (each identified by logical unit number, or lun, 
 186   between 0 and 7). The IBM SCSI-2 F/W adapter offers this on up to two
 187   busses and provides support for 30 logical devices at the same time, where
 188   in wide-addressing mode you can have 16 puns with 32 luns on each device.
 189   This section describes the handling of devices on non-F/W adapters.
 190   Just imagine, that you can have 16 * 32 = 512 devices on a F/W adapter
 191   which means a lot of possible devices for such a small machine.
 193   Typically the adapter has pun=7, so puns of other physical units
 194   are between 0 and 6(15). On a wide-adapter a pun higher than 7 is
 195   possible, but is normally not used. Almost all physical units have only 
 196   one logical unit, with lun=0. A CD-ROM jukebox would be an example of a 
 197   physical unit with more than one logical unit.
 199   The embedded microprocessor of the IBM SCSI-subsystem hides the complex
 200   two-dimensional (pun,lun) organization from the operating system.
 201   When the machine is powered-up (or rebooted), the embedded microprocessor 
 202   checks, on its own, all 56 possible (pun,lun) combinations, and the first 
 203   15 devices found are assigned into a one-dimensional array of so-called 
 204   "logical devices", identified by "logical device numbers" or ldn. The last 
 205   ldn=15 is reserved for the subsystem itself. Wide adapters may have 
 206   to check up to 15 * 8 = 120 pun/lun combinations.
 208   2.3 SCSI-Device Recognition and Dynamical ldn Assignment
 209   --------------------------------------------------------
 210   One consequence of information hiding is that the real (pun,lun)    
 211   numbers are also hidden. The two possibilities to get around this problem
 212   are to offer fake pun/lun combinations to the operating system or to 
 213   delete the whole mapping of the adapter and to reassign the ldns, using
 214   the immediate assign command of the SCSI-subsystem for probing through
 215   all possible pun/lun combinations.  An ldn is a "logical device number"
 216   which is used by IBM SCSI-subsystems to access some valid SCSI-device.
 217   At the beginning of the development of this driver, the following approach 
 218   was used:
 220   First, the driver checked the ldn's (0 to 6) to find out which ldn's
 221   have devices assigned. This was done by the functions check_devices() and
 222   device_exists(). The interrupt handler has a special paragraph of code
 223   (see local_checking_phase_flag) to assist in the checking. Assume, for
 224   example, that three logical devices were found assigned at ldn 0, 1, 2.
 225   These are presented to the upper layer of Linux SCSI driver
 226   as devices with bogus (pun, lun) equal to (0,0), (1,0), (2,0). 
 227   On the other hand, if the upper layer issues a command to device
 228   say (4,0), this driver returns DID_NO_CONNECT error.
 230   In a second step of the driver development, the following improvement has
 231   been applied: The first approach limited the number of devices to 7, far
 232   fewer than the 15 that it could use, then it just mapped ldn -> 
 233   (ldn/8,ldn%8) for pun,lun.  We ended up with a real mishmash of puns
 234   and luns, but it all seemed to work.
 236   The latest development, which is implemented from the driver version 3.0
 237   and later, realizes the device recognition in the following way:
 238   The physical SCSI-devices on the SCSI-bus are probed via immediate_assign- 
 239   and device_inquiry-commands, that is all implemented in a completely new
 240   made check_devices() subroutine. This delivers an exact map of the physical
 241   SCSI-world that is now stored in the get_scsi[][]-array. This means,
 242   that the once hidden pun,lun assignment is now known to this driver.
 243   It no longer believes in default-settings of the subsystem and maps all
 244   ldns to existing pun,lun "by foot". This assures full control of the ldn
 245   mapping and allows dynamical remapping of ldns to different pun,lun, if
 246   there are more SCSI-devices installed than ldns available (n>15). The
 247   ldns from 0 to 6 get 'hardwired' by this driver to puns 0 to 7 at lun=0,
 248   excluding the pun of the subsystem. This assures, that at least simple 
 249   SCSI-installations have optimum access-speed and are not touched by
 250   dynamical remapping. The ldns 7 to 14 are put to existing devices with 
 251   lun>0 or to non-existing devices, in order to satisfy the subsystem, if 
 252   there are less than 15 SCSI-devices connected. In the case of more than 15 
 253   devices, the dynamical mapping goes active. If the get_scsi[][] reports a 
 254   device to be existent, but it has no ldn assigned, it gets an ldn out of 7
 255   to 14. The numbers are assigned in cyclic order, therefore it takes 8 
 256   dynamical reassignments on the SCSI-devices until a certain device 
 257   loses its ldn again. This assures that dynamical remapping is avoided 
 258   during intense I/O between up to 15 SCSI-devices (means pun,lun 
 259   combinations). A further advantage of this method is that people who
 260   build their kernel without probing on all luns will get what they expect,
 261   because the driver just won't assign everything with lun>0 when 
 262   multiple lun probing is inactive.
 264   2.4 SCSI-Device Order
 265   ---------------------
 266   Because of the now correct recognition of physical pun,lun, and 
 267   their report to mid-level- and higher-level-drivers, the new reported puns
 268   can be different from the old, faked puns. Therefore, Linux will eventually
 269   change /dev/sdXXX assignments and prompt you for corrupted superblock
 270   repair on boottime. In this case DO NOT PANIC, YOUR DISKS ARE STILL OK!!!
 271   You have to reboot (CTRL-D) with an old kernel and set the /etc/fstab-file
 272   entries right. After that, the system should come up as errorfree as before.
 273   If your boot-partition is not coming up, also edit the /etc/lilo.conf-file
 274   in a Linux session booted on old kernel and run lilo before reboot. Check
 275   lilo.conf anyway to get boot on other partitions with foreign OSes right
 276   again. But there exists a feature of this driver that allows you to change
 277   the assignment order of the SCSI-devices by flipping the PUN-assignment.
 278   See the next paragraph for a description.
 280   The problem for this is, that Linux does not assign the SCSI-devices in the
 281   way as described in the ANSI-SCSI-standard. Linux assigns /dev/sda to 
 282   the device with at minimum id 0. But the first drive should be at id 6,
 283   because for historical reasons, drive at id 6 has, by hardware, the highest
 284   priority and a drive at id 0 the lowest. IBM was one of the rare producers,
 285   where the BIOS assigns drives belonging to the ANSI-SCSI-standard. Most 
 286   other producers' BIOS does not (I think even Adaptec-BIOS). The 
 287   IBMMCA_SCSI_ORDER_STANDARD flag, which you set while configuring the
 288   kernel enables to choose the preferred way of SCSI-device-assignment. 
 289   Defining this flag would result in Linux determining the devices in the 
 290   same order as DOS and OS/2 does on your MCA-machine. This is also standard 
 291   on most industrial computers and OSes, like e.g. OS-9. Leaving this flag 
 292   undefined will get your devices ordered in the default way of Linux. See 
 293   also the remarks of Chris Beauregard from Dec 15, 1997 and the followups 
 294   in section 3.
 296   2.5 Regular SCSI-Command-Processing
 297   -----------------------------------
 298   Only three functions get involved: ibmmca_queuecommand(), issue_cmd(),
 299   and interrupt_handler().
 301   The upper layer issues a scsi command by calling function 
 302   ibmmca_queuecommand(). This function fills a "subsystem control block"
 303   (scb) and calls a local function issue_cmd(), which writes a scb 
 304   command into subsystem I/O ports. Once the scb command is carried out, 
 305   the interrupt_handler() is invoked. If a device is determined to be 
 306   existant and it has not assigned any ldn, it gets one dynamically.
 307   For this, the whole stuff is done in ibmmca_queuecommand().
 309   2.6 Abort & Reset Commands
 310   --------------------------
 311   These are implemented with busy waiting for interrupt to arrive.
 312   ibmmca_reset() and ibmmca_abort() do not work sufficiently well
 313   up to now and need still a lot of development work. This seems
 314   to be a problem with other low-level SCSI drivers too, however
 315   this should be no excuse.
 317   2.7 Disk Geometry
 318   -----------------
 319   The ibmmca_biosparams() function should return the same disk geometry 
 320   as the bios. This is needed for fdisk, etc. The returned geometry is 
 321   certainly correct for disks smaller than 1 gigabyte. In the meantime,
 322   it has been proved, that this works fine even with disks larger than
 323   1 gigabyte.
 325   2.8 Kernel Boot Option
 326   ----------------------
 327   The function ibmmca_scsi_setup() is called if option ibmmcascsi=n 
 328   is passed to the kernel. See file linux/init/main.c for details.
 330   2.9 Driver Module Support
 331   -------------------------
 332   Is implemented and tested by K. Kudielka. This could probably not work
 333   on kernels <2.1.0.
 335   2.10 Multiple Hostadapter Support
 336   ---------------------------------
 337   This driver supports up to eight interfaces of type IBM-SCSI-Subsystem. 
 338   Integrated-, and MCA-adapters are automatically recognized. Unrecognizable
 339   IBM-SCSI-Subsystem interfaces can be specified as kernel-parameters.
 341   2.11 /proc/scsi-Filesystem Information
 342   --------------------------------------
 343   Information about the driver condition is given in 
 344   /proc/scsi/ibmmca/<host_no>. ibmmca_proc_info() provides this information.
 346   This table is quite informative for interested users. It shows the load
 347   of commands on the subsystem and whether you are running the bypassed
 348   (software) or integrated (hardware) SCSI-command set (see below). The
 349   amount of accesses is shown. Read, write, modeselect is shown separately
 350   in order to help debugging problems with CD-ROMs or tapedrives.
 352   The following table shows the list of 15 logical device numbers, that are
 353   used by the SCSI-subsystem. The load on each ldn is shown in the table,
 354   again, read and write commands are split. The last column shows the amount
 355   of reassignments, that have been applied to the ldns, if you have more than
 356   15 pun/lun combinations available on the SCSI-bus.
 358   The last two tables show the pun/lun map and the positions of the ldns
 359   on this pun/lun map. This may change during operation, when a ldn is
 360   reassigned to another pun/lun combination. If the necessity for dynamical
 361   assignments is set to 'no', the ldn structure keeps static.
 363   2.12 /proc/mca-Filesystem Information
 364   -------------------------------------
 365   The slot-file contains all default entries and in addition chip and I/O-
 366   address information of the SCSI-subsystem. This information is provided
 367   by ibmmca_getinfo().
 369   2.13 Supported IBM SCSI-Subsystems
 370   ----------------------------------
 371   The following IBM SCSI-subsystems are supported by this driver:
 373     - IBM Fast/Wide SCSI-2 Adapter
 374     - IBM 7568 Industrial Computer SCSI Adapter w/Cache
 375     - IBM Expansion Unit SCSI Controller
 376     - IBM SCSI Adapter w/Cache
 377     - IBM SCSI Adapter
 378     - IBM Integrated SCSI Controller
 379     - All clones, 100% compatible with the chipset and subsystem command
 380       system of IBM SCSI-adapters (forced detection)
 382   2.14 Linux Kernel Versions
 383   --------------------------
 384   The IBM SCSI-subsystem low level driver is prepared to be used with
 385   all versions of Linux between 2.0.x and 2.4.x. The compatibility checks
 386   are fully implemented up from version 3.1e of the driver. This means, that
 387   you just need the latest ibmmca.h and ibmmca.c file and copy it in the
 388   linux/drivers/scsi directory. The code is automatically adapted during 
 389   kernel compilation. This is different from kernel 2.4.0! Here version 
 390   4.0 or later of the driver must be used for kernel 2.4.0 or later. Version
 391   4.0 or later does not work together with older kernels! Driver versions
 392   older than 4.0 do not work together with kernel 2.4.0 or later. They work
 393   on all older kernels.
 395   3 Code History
 396   --------------
 397   Jan 15 1996:  First public release.
 398   - Martin Kolinek
 400   Jan 23 1996:  Scrapped code which reassigned scsi devices to logical
 401   device numbers. Instead, the existing assignment (created
 402   when the machine is powered-up or rebooted) is used. 
 403   A side effect is that the upper layer of Linux SCSI 
 404   device driver gets bogus scsi ids (this is benign), 
 405   and also the hard disks are ordered under Linux the 
 406   same way as they are under dos (i.e., C: disk is sda, 
 407   D: disk is sdb, etc.).
 408   - Martin Kolinek
 410   I think that the CD-ROM is now detected only if a CD is 
 411   inside CD_ROM while Linux boots. This can be fixed later,
 412   once the driver works on all types of PS/2's.
 413   - Martin Kolinek
 415   Feb 7 1996:   Modified biosparam function. Fixed the CD-ROM detection. 
 416   For now, devices other than harddisk and CD_ROM are 
 417   ignored. Temporarily modified abort() function 
 418   to behave like reset().
 419   - Martin Kolinek
 421   Mar 31 1996:  The integrated scsi subsystem is correctly found
 422   in PS/2 models 56,57, but not in model 76. Therefore
 423   the ibmmca_scsi_setup() function has been added today.
 424   This function allows the user to force detection of
 425   scsi subsystem. The kernel option has format
 426   ibmmcascsi=n
 427   where n is the scsi_id (pun) of the subsystem. Most likely, n is 7.
 428   - Martin Kolinek
 430   Aug 21 1996:  Modified the code which maps ldns to (pun,0).  It was
 431   insufficient for those of us with CD-ROM changers.
 432   - Chris Beauregard
 434   Dec 14 1996: More improvements to the ldn mapping.  See check_devices
 435   for details.  Did more fiddling with the integrated SCSI detection,
 436   but I think it's ultimately hopeless without actually testing the
 437   model of the machine.  The 56, 57, 76 and 95 (ultimedia) all have
 438   different integrated SCSI register configurations.  However, the 56
 439   and 57 are the only ones that have problems with forced detection.
 440   - Chris Beauregard
 442   Mar 8-16 1997: Modified driver to run as a module and to support 
 443   multiple adapters. A structure, called ibmmca_hostdata, is now
 444   present, containing all the variables, that were once only
 445   available for one single adapter. The find_subsystem-routine has vanished.
 446   The hardware recognition is now done in ibmmca_detect directly.
 447   This routine checks for presence of MCA-bus, checks the interrupt
 448   level and continues with checking the installed hardware.
 449   Certain PS/2-models do not recognize a SCSI-subsystem automatically.
 450   Hence, the setup defined by command-line-parameters is checked first.
 451   Thereafter, the routine probes for an integrated SCSI-subsystem.
 452   Finally, adapters are checked. This method has the advantage to cover all
 453   possible combinations of multiple SCSI-subsystems on one MCA-board. Up to
 454   eight SCSI-subsystems can be recognized and announced to the upper-level
 455   drivers with this improvement. A set of defines made changes to other
 456   routines as small as possible.
 457   - Klaus Kudielka
 459   May 30 1997: (v1.5b)
 460   1) SCSI-command capability enlarged by the recognition of MODE_SELECT.
 461      This needs the RD-Bit to be disabled on IM_OTHER_SCSI_CMD_CMD which 
 462      allows data to be written from the system to the device. It is a
 463      necessary step to be allowed to set blocksize of SCSI-tape-drives and 
 464      the tape-speed, without confusing the SCSI-Subsystem.
 465   2) The recognition of a tape is included in the check_devices routine.
 466      This is done by checking for TYPE_TAPE, that is already defined in
 467      the kernel-scsi-environment. The markup of a tape is done in the 
 468      global ldn_is_tape[] array. If the entry on index ldn 
 469      is 1, there is a tapedrive connected.
 470   3) The ldn_is_tape[] array is necessary to distinguish between tape- and 
 471      other devices. Fixed blocklength devices should not cause a problem
 472      with the SCB-command for read and write in the ibmmca_queuecommand
 473      subroutine. Therefore, I only derivate the READ_XX, WRITE_XX for
 474      the tape-devices, as recommended by IBM in this Technical Reference,
 475      mentioned below. (IBM recommends to avoid using the read/write of the
 476      subsystem, but the fact was, that read/write causes a command error from
 477      the subsystem and this causes kernel-panic.)
 478   4) In addition, I propose to use the ldn instead of a fix char for the
 479      display of PS2_DISK_LED_ON(). On 95, one can distinguish between the
 480      devices that are accessed. It shows activity and easyfies debugging.   
 481   The tape-support has been tested with a SONY SDT-5200 and a HP DDS-2
 482   (I do not know yet the type). Optimization and CD-ROM audio-support, 
 483   I am working on ...
 484   - Michael Lang
 486   June 19 1997: (v1.6b)
 487   1) Submitting the extra-array ldn_is_tape[] -> to the local ld[]
 488      device-array. 
 489   2) CD-ROM Audio-Play seems to work now.
 490   3) When using DDS-2 (120M) DAT-Tapes, mtst shows still density-code
 491      0x13 for ordinary DDS (61000 BPM) instead 0x24 for DDS-2. This appears 
 492      also on Adaptec 2940 adaptor in a PCI-System. Therefore, I assume that 
 493      the problem is independent of the low-level-driver/bus-architecture.
 494   4) Hexadecimal ldn on PS/2-95 LED-display.
 495   5) Fixing of the PS/2-LED on/off that it works right with tapedrives and
 496      does not confuse the disk_rw_in_progress counter.
 497   - Michael Lang
 499   June 21 1997: (v1.7b)
 500   1) Adding of a proc_info routine to inform in /proc/scsi/ibmmca/<host> the
 501      outer-world about operational load statistics on the different ldns,
 502      seen by the driver. Everybody that has more than one IBM-SCSI should
 503      test this, because I only have one and cannot see what happens with more
 504      than one IBM-SCSI hosts.
 505   2) Definition of a driver version-number to have a better recognition of 
 506      the source when there are existing too much releases that may confuse
 507      the user, when reading about release-specific problems. Up to know,
 508      I calculated the version-number to be 1.7. Because we are in BETA-test
 509      yet, it is today 1.7b.
 510   3) Sorry for the heavy bug I programmed on June 19 1997! After that, the
 511      CD-ROM did not work any more! The C7-command was a fake impression
 512      I got while programming. Now, the READ and WRITE commands for CD-ROM are
 513      no longer running over the subsystem, but just over 
 514      IM_OTHER_SCSI_CMD_CMD. On my observations (PS/2-95), now CD-ROM mounts
 515      much faster(!) and hopefully all fancy multimedia-functions, like direct
 516      digital recording from audio-CDs also work. (I tried it with cdda2wav
 517      from the cdwtools-package and it filled up the harddisk immediately :-).)
 518      To easify boolean logics, a further local device-type in ld[], called
 519      is_cdrom has been included.
 520   4) If one uses a SCSI-device of unsupported type/commands, one
 521      immediately runs into a kernel-panic caused by Command Error. To better
 522      understand which SCSI-command caused the problem, I extended this
 523      specific panic-message slightly.
 524   - Michael Lang
 526   June 25 1997: (v1.8b)
 527   1) Some cosmetic changes for the handling of SCSI-device-types.
 528      Now, also CD-Burners / WORMs and SCSI-scanners should work. For
 529      MO-drives I have no experience, therefore not yet supported.
 530      In logical_devices I changed from different type-variables to one
 531      called 'device_type' where the values, corresponding to scsi.h,
 532      of a SCSI-device are stored.
 533   2) There existed a small bug, that maps a device, coming after a SCSI-tape
 534      wrong. Therefore, e.g. a CD-ROM changer would have been mapped wrong
 535      -> problem removed.
 536   3) Extension of the logical_device structure. Now it contains also device,
 537      vendor and revision-level of a SCSI-device for internal usage.
 538   - Michael Lang
 540   June 26-29 1997: (v2.0b)
 541   1) The release number 2.0b is necessary because of the completely new done
 542      recognition and handling of SCSI-devices with the adapter. As I got
 543      from Chris the hint, that the subsystem can reassign ldns dynamically,
 544      I remembered this immediate_assign-command, I found once in the handbook.
 545      Now, the driver first kills all ldn assignments that are set by default
 546      on the SCSI-subsystem. After that, it probes on all puns and luns for
 547      devices by going through all combinations with immediate_assign and
 548      probing for devices, using device_inquiry. The found physical(!) pun,lun
 549      structure is stored in get_scsi[][] as device types. This is followed
 550      by the assignment of all ldns to existing SCSI-devices. If more ldns
 551      than devices are available, they are assigned to non existing pun,lun
 552      combinations to satisfy the adapter. With this, the dynamical mapping
 553      was possible to implement. (For further info see the text in the 
 554      source code and in the description below. Read the description
 555      below BEFORE installing this driver on your system!)
 557   3) The LED-display shows on PS/2-95 no longer the ldn, but the SCSI-ID
 558      (pun) of the accessed SCSI-device. This is now senseful, because the 
 559      pun known within the driver is exactly the pun of the physical device
 560      and no longer a fake one.
 561   4) The /proc/scsi/ibmmca/<host_no> consists now of the first part, where
 562      hit-statistics of ldns is shown and a second part, where the maps of 
 563      physical and logical SCSI-devices are displayed. This could be very 
 564      interesting, when one is using more than 15 SCSI-devices in order to 
 565      follow the dynamical remapping of ldns.
 566   - Michael Lang
 568   June 26-29 1997: (v2.0b-1)
 569   1) I forgot to switch the local_checking_phase_flag to 1 and back to 0
 570      in the dynamical remapping part in ibmmca_queuecommand for the 
 571      device_exist routine. Sorry.
 572   - Michael Lang
 574   July 1-13 1997: (v3.0b,c)
 575   1) Merging of the driver-developments of Klaus Kudielka and Michael Lang 
 576      in order to get a optimum and unified driver-release for the 
 577      IBM-SCSI-Subsystem-Adapter(s).
 578         For people, using the Kernel-release >=2.1.0, module-support should 
 579      be no problem. For users, running under <2.1.0, module-support may not 
 580      work, because the methods have changed between 2.0.x and 2.1.x.
 581   2) Added some more effective statistics for /proc-output.
 582   3) Change typecasting at necessary points from (unsigned long) to
 583      virt_to_bus().
 584   4) Included #if... at special points to have specific adaption of the
 585      driver to kernel 2.0.x and 2.1.x. It should therefore also run with 
 586      later releases.
 587   5) Magneto-Optical drives and medium-changers are also recognized, now.
 588      Therefore, we have a completely gapfree recognition of all SCSI-
 589      device-types, that are known by Linux up to kernel 2.1.31.
 590   6) The flag SCSI_IBMMCA_DEV_RESET has been inserted. If it is set within
 591      the configuration, each connected SCSI-device will get a reset command
 592      during boottime. This can be necessary for some special SCSI-devices.
 593      This flag should be included in
 594      (See also the new file.)
 595   Probable next improvement: bad disk handler.
 596   - Michael Lang
 598   Sept 14 1997: (v3.0c)
 599   1) Some debugging and speed optimization applied.
 600   - Michael Lang
 602   Dec 15, 1997
 603    -
 604    - made the front panel display thingy optional, specified from the
 605    command-line via ibmmcascsi=display.  Along the lines of the /LED
 606    option for the OS/2 driver.
 607    - fixed small bug in the LED display that would hang some machines.
 608    - reversed ordering of the drives (using the
 609    IBMMCA_SCSI_ORDER_STANDARD define).  This is necessary for two main
 610    reasons:
 611        - users who've already installed Linux won't be screwed.  Keep
 612        in mind that not everyone is a kernel hacker.
 613        - be consistent with the BIOS ordering of the drives.  In the
 614        BIOS, id 6 is C:, id 0 might be D:.  With this scheme, they'd be
 615        backwards.  This confuses the crap out of those heathens who've
 616        got a impure Linux installation (which, <wince>, I'm one of).
 617    This whole problem arises because IBM is actually non-standard with
 618    the id to BIOS mappings.  You'll find, in fdomain.c, a similar
 619    comment about a few FD BIOS revisions.  The Linux (and apparently
 620    industry) standard is that C: maps to scsi id (0,0).  Let's stick
 621    with that standard.
 622    - Since this is technically a branch of my own, I changed the
 623    version number to 3.0e-cpb.
 625   Jan 17, 1998: (v3.0f)
 626   1) Addition of some statistical info for /proc in proc_info.
 627   2) Taking care of the SCSI-assignment problem, dealed by Chris at Dec 15
 628      1997. In fact, IBM is right, concerning the assignment of SCSI-devices 
 629      to driveletters. It is conform to the ANSI-definition of the SCSI-
 630      standard to assign drive C: to SCSI-id 6, because it is the highest
 631      hardware priority after the hostadapter (that has still today by
 632      default everywhere id 7). Also realtime-operating systems that I use, 
 633      like LynxOS and OS9, which are quite industrial systems use top-down
 634      numbering of the harddisks, that is also starting at id 6. Now, one
 635      sits a bit between two chairs. On one hand side, using the define
 636      IBMMCA_SCSI_ORDER_STANDARD makes Linux assigning disks conform to
 637      the IBM- and ANSI-SCSI-standard and keeps this driver downward
 638      compatible to older releases, on the other hand side, people is quite
 639      habituated in believing that C: is assigned to (0,0) and much other
 640      SCSI-BIOS do so. Therefore, I moved the IBMMCA_SCSI_ORDER_STANDARD 
 641      define out of the driver and put it into as subitem of 
 642      'IBM SCSI support'. A help, added to Documentation/ 
 643      explains the differences between saying 'y' or 'n' to the user, when 
 644      IBMMCA_SCSI_ORDER_STANDARD prompts, so the ordinary user is enabled to 
 645      choose the way of assignment, depending on his own situation and gusto.
 646   3) Adapted SCSI_IBMMCA_DEV_RESET to the local naming convention, so it is
 647      now called IBMMCA_SCSI_DEV_RESET.
 648   4) Optimization of proc_info and its subroutines.
 649   5) Added more in-source-comments and extended the driver description by
 650      some explanation about the SCSI-device-assignment problem.
 651   - Michael Lang
 653   Jan 18, 1998: (v3.0g)
 654   1) Correcting names to be absolutely conform to the later 2.1.x releases.
 655      This is necessary for 
 658   - Michael Lang
 660   Jan 18, 1999: (v3.1 MCA-team internal)
 661   1) The multiple hosts structure is accessed from every subroutine, so there
 662      is no longer the address of the device structure passed from function
 663      to function, but only the hostindex. A call by value, nothing more. This
 664      should really be understood by the compiler and the subsystem should get
 665      the right values and addresses.
 666   2) The SCSI-subsystem detection was not complete and quite hugely buggy up
 667      to now, compared to the technical manual. The interpretation of the pos2
 668      register is not as assumed by people before, therefore, I dropped a note
 669      in the ibmmca_detect function to show the registers' interpretation.
 670      The pos-registers of integrated SCSI-subsystems do not contain any 
 671      information concerning the IO-port offset, really. Instead, they contain
 672      some info about the adapter, the chip, the NVRAM .... The I/O-port is
 673      fixed to 0x3540 - 0x3547. There can be more than one adapters in the 
 674      slots and they get an offset for the I/O area in order to get their own
 675      I/O-address area. See chapter 2 for detailed description. At least, the 
 676      detection should now work right, even on models other than 95. The 95ers
 677      came happily around the bug, as their pos2 register contains always 0 
 678      in the critical area. Reserved bits are not allowed to be interpreted, 
 679      therefore, IBM is allowed to set those bits as they like and they may 
 680      really vary between different PS/2 models. So, now, no interpretation 
 681      of reserved bits - hopefully no trouble here anymore.
 682   3) The command error, which you may get on models 55, 56, 57, 70, 77 and
 683      P70 may have been caused by the fact, that adapters of older design do
 684      not like sending commands to non-existing SCSI-devices and will react
 685      with a command error as a sign of protest. While this error is not
 686      present on IBM SCSI Adapter w/cache, it appears on IBM Integrated SCSI
 687      Adapters. Therefore, I implemented a workaround to forgive those 
 688      adapters their protests, but it is marked up in the statistics, so
 689      after a successful boot, you can see in /proc/scsi/ibmmca/<host_number>
 690      how often the command errors have been forgiven to the SCSI-subsystem.
 691      If the number is bigger than 0, you have a SCSI subsystem of older
 692      design, what should no longer matter.
 693   4) ibmmca_getinfo() has been adapted very carefully, so it shows in the 
 694      slotn file really, what is senseful to be presented.
 695   5) ibmmca_register() has been extended in its parameter list in order to
 696      pass the right name of the SCSI-adapter to Linux.
 697   - Michael Lang
 699   Feb 6, 1999: (v3.1)
 700   1) Finally, after some 3.1Beta-releases, the 3.1 release. Sorry, for 
 701      the delayed release, but it was not finished with the release of 
 702      Kernel 2.2.0.
 703   - Michael Lang
 705   Feb 10, 1999 (v3.1)
 706   1) Added a new commandline parameter called 'bypass' in order to bypass
 707      every integrated subsystem SCSI-command consequently in case of
 708      troubles.
 709   2) Concatenated read_capacity requests to the harddisks. It gave a lot
 710      of troubles with some controllers and after I wanted to apply some
 711      extensions, it jumped out in the same situation, on my w/cache, as like 
 712      on D. Weinehalls' Model 56, having integrated SCSI. This gave me the 
 713      decisive hint to move the code-part out and declare it global. Now
 714      it seems to work far better and more stable. Let us see what
 715      the world thinks of it...
 716   3) By the way, only Sony DAT-drives seem to show density code 0x13. A
 717      test with a HP drive gave right results, so the problem is vendor-
 718      specific and not a problem of the OS or the driver.
 719   - Michael Lang
 721   Feb 18, 1999 (v3.1d)
 722   1) The abort command and the reset function have been checked for 
 723      inconsistencies. From the logical point of thinking, they work
 724      at their optimum, now, but as the subsystem does not answer with an
 725      interrupt, abort never finishes, sigh...
 726   2) Everything, that is accessed by a busmaster request from the adapter
 727      is now declared as global variable, even the return-buffer in the
 728      local checking phase. This assures, that no accesses to undefined memory
 729      areas are performed.
 730   3) In ibmmca.h, the line unchecked_isa_dma is added with 1 in order to
 731      avoid memory-pointers for the areas higher than 16MByte in order to
 732      be sure, it also works on 16-Bit Microchannel bus systems.
 733   4) A lot of small things have been found, but nothing that endangered the
 734      driver operations. Just it should be more stable, now.
 735   - Michael Lang
 737   Feb 20, 1999 (v3.1e)
 738   1) I took the warning from the Linux Kernel Hackers Guide serious and 
 739      checked the cmd->result return value to the done-function very carefully.
 740      It is obvious, that the IBM SCSI only delivers the tsb.dev_status, if
 741      some error appeared, else it is undefined. Now, this is fixed. Before
 742      any SCB command gets queued, the tsb.dev_status is set to 0, so the 
 743      cmd->result won't screw up Linux higher level drivers.
 744   2) The reset-function has slightly improved. This is still planed for 
 745      abort. During the abort and the reset function, no interrupts are 
 746      allowed. This is however quite hard to cope with, so the INT-status
 747      register is read. When the interrupt gets queued, one can find its
 748      status immediately on that register and is enabled to continue in the
 749      reset function. I had no chance to test this really, only in a bogus 
 750      situation, I got this function running, but the situation was too much
 751      worse for Linux :-(, so tests will continue.
 752   3) Buffers got now consistent. No open address mapping, as before and
 753      therefore no further troubles with the unassigned memory segmentation
 754      faults that scrambled probes on 95XX series and even on 85XX series,
 755      when the kernel is done in a not so perfectly fitting way.
 756   4) Spontaneous interrupts from the subsystem, appearing without any
 757      command previously queued are answered with a DID_BAD_INTR result.
 758   5) Taken into account ZP Gus' proposals to reverse the SCSI-device
 759      scan order. As it does not work on Kernel 2.1.x or 2.2.x, as proposed
 760      by him, I implemented it in a slightly derived way, which offers in 
 761      addition more flexibility.
 762   - Michael Lang
 764   Apr 23, 2000 (v3.2pre1)
 765   1) During a very long time, I collected a huge amount of bug reports from
 766      various people, trying really quite different things on their SCSI-
 767      PS/2s. Today, all these bug reports are taken into account and should be
 768      mostly solved. The major topics were:
 769      - Driver crashes during boottime by no obvious reason.
 770      - Driver panics while the midlevel-SCSI-driver is trying to inquire
 771        the SCSI-device properties, even though hardware is in perfect state.
 772      - Displayed info for the various slot-cards is interpreted wrong.
 773      The main reasons for the crashes were two:
 774      1) The commands to check for device information like INQUIRY, 
 775         TEST_UNIT_READY, REQUEST_SENSE and MODE_SENSE cause the devices
 776         to deliver information of up to 255 bytes. Midlevel drivers offer
 777         1024 bytes of space for the answer, but the IBM-SCSI-adapters do
 778         not accept this, as they stick quite near to ANSI-SCSI and report
 779         a COMMAND_ERROR message which causes the driver to panic. The main
 780         problem was located around the INQUIRY command. Now, for all the
 781         mentioned commands, the buffersize sent to the adapter is at 
 782         maximum 255 which seems to be a quite reasonable solution. 
 783         TEST_UNIT_READY gets a buffersize of 0 to make sure that no 
 784         data is transferred in order to avoid any possible command failure.
 785      2) On unsuccessful TEST_UNIT_READY, the mid-level driver has to send
 786         a REQUEST_SENSE in order to see where the problem is located. This
 787         REQUEST_SENSE may have various length in its answer-buffer. IBM
 788         SCSI-subsystems report a command failure if the returned buffersize
 789         is different from the sent buffersize, but this can be suppressed by
 790         a special bit, which is now done and problems seem to be solved.
 791   2) Code adaption to all kernel-releases. Now, the 3.2 code compiles on 
 792      2.0.x, 2.1.x, 2.2.x and 2.3.x kernel releases without any code-changes.
 793   3) Commandline-parameters are recognized again, even under Kernel 2.3.x or
 794      higher.
 795   - Michael Lang   
 797   April 27, 2000 (v3.2pre2)
 798   1) Bypassed commands get read by the adapter by one cycle instead of two.
 799      This increases SCSI-performance.
 800   2) Synchronous datatransfer is provided for sure to be 5 MHz on older
 801      SCSI and 10 MHz on internal F/W SCSI-adapter.
 802   3) New commandline parameters allow to force the adapter to slow down while
 803      in synchronous transfer. Could be helpful for very old devices.
 804   - Michael Lang
 806   June 2, 2000 (v3.2pre5)
 807   1) Added Jim Shorney's contribution to make the activity indicator
 808      flashing in addition to the LED-alphanumeric display-panel on
 809      models 95A. To be enabled to choose this feature freely, a new
 810      commandline parameter is added, called 'activity'.
 811   2) Added the READ_CONTROL bit for test_unit_ready SCSI-command.
 812   3) Added some suppress_exception bits to read_device_capacity and
 813      all device_inquiry occurrences in the driver code.
 814   4) Complaints about the various KERNEL_VERSION implementations are
 815      taken into account. Every local_LinuxKernelVersion occurrence is
 816      now replaced by KERNEL_VERSION, defined in linux/version.h. 
 817      Corresponding changes were applied to ibmmca.h, too. This was a
 818      contribution to all kernel-parts by Philipp Hahn.
 819   - Michael Lang
 821   July 17, 2000 (v3.2pre8)
 822   A long period of collecting bug reports from all corners of the world
 823   now lead to the following corrections to the code:
 824   1) SCSI-2 F/W support crashed with a COMMAND ERROR. The reason for this 
 825      was that it is possible to disable Fast-SCSI for the external bus.
 826      The feature-control command, where this crash appeared regularly, tried
 827      to set the maximum speed of 10MHz synchronous transfer speed and that
 828      reports a COMMAND ERROR if external bus Fast-SCSI is disabled. Now,
 829      the feature-command probes down from maximum speed until the adapter 
 830      stops to complain, which is at the same time the maximum possible
 831      speed selected in the reference program. So, F/W external can run at
 832      5 MHz (slow-) or 10 MHz (fast-SCSI). During feature probing, the 
 833      COMMAND ERROR message is used to detect if the adapter does not complain.
 834   2) Up to now, only combined busmode is supported, if you use external
 835      SCSI-devices, attached to the F/W-controller. If dual bus is selected,
 836      only the internal SCSI-devices get accessed by Linux. For most 
 837      applications, this should do fine. 
 838   3) Wide-SCSI-addressing (16-Bit) is now possible for the internal F/W
 839      bus on the F/W adapter. If F/W adapter is detected, the driver
 840      automatically uses the extended PUN/LUN <-> LDN mapping tables, which
 841      are now new from 3.2pre8. This allows PUNs between 0 and 15 and should
 842      provide more fun with the F/W adapter.
 843   4) Several machines use the SCSI: POS registers for internal/undocumented
 844      storage of system relevant info. This confused the driver, mainly on
 845      models 9595, as it expected no onboard SCSI only, if all POS in
 846      the integrated SCSI-area are set to 0x00 or 0xff. Now, the mechanism
 847      to check for integrated SCSI is much more restrictive and these problems
 848      should be history.
 849   - Michael Lang          
 851   July 18, 2000 (v3.2pre9)
 852   This develop rather quickly at the moment. Two major things were still
 853   missing in 3.2pre8:
 854   1) The adapter PUN for F/W adapters has 4-bits, while all other adapters
 855      have 3-bits. This is now taken into account for F/W.
 856   2) When you select CONFIG_IBMMCA_SCSI_ORDER_STANDARD, you should 
 857      normally get the inverse probing order of your devices on the SCSI-bus.
 858      The ANSI device order gets scrambled in version 3.2pre8!! Now, a new
 859      and tested algorithm inverts the device-order on the SCSI-bus and
 860      automatically avoids accidental access to whatever SCSI PUN the adapter 
 861      is set and works with SCSI- and Wide-SCSI-addressing.
 862   - Michael Lang
 864   July 23, 2000 (v3.2pre10 unpublished) 
 865   1) LED panel display supports wide-addressing in ibmmca=display mode.
 866   2) Adapter-information and autoadaption to address-space is done.
 867   3) Auto-probing for maximum synchronous SCSI transfer rate is working.
 868   4) Optimization to some embedded function calls is applied.
 869   5) Added some comment for the user to wait for SCSI-devices being probed.
 870   6) Finished version 3.2 for Kernel 2.4.0. It least, I thought it is but...
 871   - Michael Lang
 873   July 26, 2000 (v3.2pre11)
 874   1) I passed a horrible weekend getting mad with NMIs on kernel 2.2.14 and
 875      a model 9595. Asking around in the community, nobody except of me has
 876      seen such errors. Weird, but I am trying to recompile everything on
 877      the model 9595. Maybe, as I use a specially modified gcc, that could
 878      cause problems. But, it was not the reason. The true background was,
 879      that the kernel was compiled for i386 and the 9595 has a 486DX-2. 
 880      Normally, no troubles should appear, but for this special machine,
 881      only the right processor support is working fine!
 882   2) Previous problems with synchronous speed, slowing down from one adapter 
 883      to the next during probing are corrected. Now, local variables store
 884      the synchronous bitmask for every single adapter found on the MCA bus.
 885   3) LED alphanumeric panel support for XX95 systems is now showing some
 886      alive rotator during boottime. This makes sense, when no monitor is 
 887      connected to the system. You can get rid of all display activity, if
 888      you do not use any parameter or just ibmmcascsi=activity, for the 
 889      harddrive activity LED, existent on all PS/2, except models 8595-XXX.
 890      If no monitor is available, please use ibmmcascsi=display, which works
 891      fine together with the linuxinfo utility for the LED-panel.
 892   - Michael Lang
 894   July 29, 2000 (v3.2)
 895   1) Submission of this driver for kernel 2.4test-XX and 2.2.17.
 896   - Michael Lang
 898   December 28, 2000 (v3.2d / v4.0)
 899   1) The interrupt handler had some wrong statement to wait for. This
 900      was done due to experimental reasons during 3.2 development but it
 901      has shown that this is not stable enough. Going back to wait for the
 902      adapter to be not busy is best.
 903   2) Inquiry requests can be shorter than 255 bytes of return buffer. Due
 904      to a bug in the ibmmca_queuecommand routine, this buffer was forced
 905      to 255 at minimum. If the memory address, this return buffer is pointing
 906      to does not offer more space, invalid memory accesses destabilized the
 907      kernel.
 908   3) version 4.0 is only valid for kernel 2.4.0 or later. This is necessary
 909      to remove old kernel version dependent waste from the driver. 3.2d is
 910      only distributed with older kernels but keeps compatibility with older
 911      kernel versions. 4.0 and higher versions cannot be used with older 
 912      kernels anymore!! You must have at least kernel 2.4.0!!
 913   4) The commandline argument 'bypass' and all its functionality got removed
 914      in version 4.0. This was never really necessary, as all troubles were
 915      based on non-command related reasons up to now, so bypassing commands
 916      did not help to avoid any bugs. It is kept in 3.2X for debugging reasons.
 917   5) Dynamic reassignment of ldns was again verified and analyzed to be
 918      completely inoperational. This is corrected and should work now.
 919   6) All commands that get sent to the SCSI adapter were verified and
 920      completed in such a way, that they are now completely conform to the
 921      demands in the technical description of IBM. Main candidates were the
 923      be transferred by bypassing the internal command buffer of the adapter
 924      or else the response can be a random result. GET_POS_INFO would be more
 925      safe in usage, if one could use the SUPRESS_EXCEPTION_SHORT, but this
 926      is not allowed by the technical references of IBM. (Sorry, folks, the
 927      model 80 problem is still a task to be solved in a different way.)
 928   7) v3.2d is still hold back for some days for testing, while 4.0 is 
 929      released.
 930   - Michael Lang
 932   January 3, 2001 (v4.0a)
 933   1) A lot of complains after the 2.4.0-prerelease kernel came in about
 934      the impossibility to compile the driver as a module. This problem is
 935      solved. In combination with that problem, some unprecise declaration
 936      of the function option_setup() gave some warnings during compilation.
 937      This is solved, too by a forward declaration in ibmmca.c.
 938   2) #ifdef argument concerning CONFIG_SCSI_IBMMCA is no longer needed and
 939      was entirely removed.
 940   3) Some switch statements got optimized in code, as some minor variables
 941      in internal SCSI-command handlers.
 942   - Michael Lang
 944   4 To do
 945   -------
 946        - IBM SCSI-2 F/W external SCSI bus support in separate mode!
 947        - It seems that the handling of bad disks is really bad -
 948          non-existent, in fact. However, a low-level driver cannot help
 949          much, if such things happen.
 951   5 Users' Manual
 952   ---------------
 953   5.1 Commandline Parameters
 954   --------------------------
 955   There exist several features for the IBM SCSI-subsystem driver.
 956   The commandline parameter format is:
 958         ibmmcascsi=<command1>,<command2>,<command3>,...
 960   where commandN can be one of the following:
 962         display    Owners of a model 95 or other PS/2 systems with an
 963                    alphanumeric LED display may set this to have their
 964                    display showing the following output of the 8 digits:
 966                                ------DA
 968                    where '-' stays dark, 'D' shows the SCSI-device id
 969                    and 'A' shows the SCSI hostindex, being currently 
 970                    accessed. During boottime, this will give the message
 972                                SCSIini*
 974                    on the LED-panel, where the * represents a rotator, 
 975                    showing the activity during the probing phase of the
 976                    driver which can take up to two minutes per SCSI-adapter.
 977         adisplay   This works like display, but gives more optical overview 
 978                    of the activities on the SCSI-bus. The display will have
 979                    the following output:
 981                                6543210A
 983                    where the numbers 0 to 6 light up at the shown position,
 984                    when the SCSI-device is accessed. 'A' shows again the SCSI
 985                    hostindex. If display nor adisplay is set, the internal
 986                    PS/2 harddisk LED is used for media-activities. So, if
 987                    you really do not have a system with a LED-display, you
 988                    should not set display or adisplay. Keep in mind, that
 989                    display and adisplay can only be used alternatively. It
 990                    is not recommended to use this option, if you have some
 991                    wide-addressed devices e.g. at the SCSI-2 F/W adapter in
 992                    your system. In addition, the usage of the display for
 993                    other tasks in parallel, like the linuxinfo-utility makes 
 994                    no sense with this option.
 995         activity   This enables the PS/2 harddisk LED activity indicator.
 996                    Most PS/2 have no alphanumeric LED display, but some
 997                    indicator. So you should use this parameter to activate it.
 998                    If you own model 9595 (Server95), you can have both, the 
 999                    LED panel and the activity indicator in parallel. However,
1000                    some PS/2s, like the 8595 do not have any harddisk LED 
1001                    activity indicator, which means, that you must use the
1002                    alphanumeric LED display if you want to monitor SCSI-
1003                    activity.
1004         bypass     This is obsolete from driver version 4.0, as the adapters
1005                    got that far understood, that the selection between 
1006                    integrated and bypassed commands should now work completely
1007                    correct! For historical reasons, the old description is
1008                    kept here:
1009                    This commandline parameter forces the driver never to use
1010                    SCSI-subsystems' integrated SCSI-command set. Except of
1011                    the immediate assign, which is of vital importance for
1012                    every IBM SCSI-subsystem to set its ldns right. Instead,
1013                    the ordinary ANSI-SCSI-commands are used and passed by the
1014                    controller to the SCSI-devices, therefore 'bypass'. The
1015                    effort, done by the subsystem is quite bogus and at a
1016                    minimum and therefore it should work everywhere. This
1017                    could maybe solve troubles with old or integrated SCSI-
1018                    controllers and nasty harddisks. Keep in mind, that using 
1019                    this flag will slow-down SCSI-accesses slightly, as the 
1020                    software generated commands are always slower than the 
1021                    hardware. Non-harddisk devices always get read/write-
1022                    commands in bypass mode. On the most recent releases of 
1023                    the Linux IBM-SCSI-driver, the bypass command should be
1024                    no longer a necessary thing, if you are sure about your
1025                    SCSI-hardware!
1026         normal     This is the parameter, introduced on the 2.0.x development
1027                    rail by ZP Gu. This parameter defines the SCSI-device
1028                    scan order in the new industry standard. This means, that
1029                    the first SCSI-device is the one with the lowest pun.
1030                    E.g. harddisk at pun=0 is scanned before harddisk at
1031                    pun=6, which means, that harddisk at pun=0 gets sda
1032                    and the one at pun=6 gets sdb.
1033         ansi       The ANSI-standard for the right scan order, as done by
1034                    IBM, Microware and Microsoft, scans SCSI-devices starting
1035                    at the highest pun, which means, that e.g. harddisk at
1036                    pun=6 gets sda and a harddisk at pun=0 gets sdb. If you
1037                    like to have the same SCSI-device order, as in DOS, OS-9
1038                    or OS/2, just use this parameter.
1039         fast       SCSI-I/O in synchronous mode is done at 5 MHz for IBM-
1040                    SCSI-devices. SCSI-2 Fast/Wide Adapter/A external bus
1041                    should then run at 10 MHz if Fast-SCSI is enabled,
1042                    and at 5 MHz if Fast-SCSI is disabled on the external
1043                    bus. This is the default setting when nothing is 
1044                    specified here.
1045         medium     Synchronous rate is at 50% approximately, which means
1046                    2.5 MHz for IBM SCSI-adapters and 5.0 MHz for F/W ext.
1047                    SCSI-bus (when Fast-SCSI speed enabled on external bus).
1048         slow       The slowest possible synchronous transfer rate is set. 
1049                    This means 1.82 MHz for IBM SCSI-adapters and 2.0 MHz
1050                    for F/W external bus at Fast-SCSI speed on the external
1051                    bus.
1053   A further option is that you can force the SCSI-driver to accept a SCSI-
1054   subsystem at a certain I/O-address with a predefined adapter PUN. This
1055   is done by entering 
1057                  commandN   = I/O-base
1058                  commandN+1 = adapter PUN
1060   e.g. ibmmcascsi=0x3540,7 will force the driver to detect a SCSI-subsystem 
1061   at I/O-address 0x3540 with adapter PUN 7. Please only use this method, if
1062   the driver does really not recognize your SCSI-adapter! With driver version
1063   3.2, this recognition of various adapters was hugely improved and you
1064   should try first to remove your commandline arguments of such type with a 
1065   newer driver. I bet, it will be recognized correctly. Even multiple and 
1066   different types of IBM SCSI-adapters should be recognized correctly, too.
1067   Use the forced detection method only as last solution!
1069   Examples:
1071        ibmmcascsi=adisplay
1073   This will use the advanced display mode for the model 95 LED alphanumeric
1074   display.
1076        ibmmcascsi=display,0x3558,7
1078   This will activate the default display mode for the model 95 LED display
1079   and will force the driver to accept a SCSI-subsystem at I/O-base 0x3558
1080   with adapter PUN 7.
1082   5.2 Troubleshooting
1083   -------------------
1084   The following FAQs should help you to solve some major problems with this
1085   driver.
1087     Q: "Reset SCSI-devices at boottime" halts the system at boottime, why?
1088     A: This is only tested with the IBM SCSI Adapter w/cache. It is not
1089        yet proven to run on other adapters, however you may be lucky.
1090        In version 3.1d this has been hugely improved and should work better,
1091        now. Normally you really won't need to activate this flag in the
1092        kernel configuration, as all post 1989 SCSI-devices should accept
1093        the reset-signal, when the computer is switched on. The SCSI-
1094        subsystem generates this reset while being initialized. This flag
1095        is really reserved for users with very old, very strange or self-made
1096        SCSI-devices.
1097     Q: Why is the SCSI-order of my drives mirrored to the device-order
1098        seen from OS/2 or DOS ?
1099     A: It depends on the operating system, if it looks at the devices in
1100        ANSI-SCSI-standard (starting from pun 6 and going down to pun 0) or
1101        if it just starts at pun 0 and counts up. If you want to be conform
1102        with OS/2 and DOS, you have to activate this flag in the kernel
1103        configuration or you should set 'ansi' as parameter for the kernel.
1104        The parameter 'normal' sets the new industry standard, starting
1105        from pun 0, scanning up to pun 6. This allows you to change your 
1106        opinion still after having already compiled the kernel.
1107     Q: Why can't I find IBM MCA SCSI support in the config menu?
1108     A: You have to activate MCA bus support, first.
1109     Q: Where can I find the latest info about this driver?
1110     A: See the file MAINTAINERS for the current WWW-address, which offers
1111        updates, info and Q/A lists. At this file's origin, the webaddress
1112        was:
1113     Q: My SCSI-adapter is not recognized by the driver, what can I do?
1114     A: Just force it to be recognized by kernel parameters. See section 5.1.
1115        If this really happens, do also send e-mail to the maintainer, as
1116        forced detection should be never necessary. Forced detection is in
1117        principal some flaw of the driver adapter detection and goes into 
1118        bug reports.
1119     Q: The driver screws up, if it starts to probe SCSI-devices, is there
1120        some way out of it?
1121     A: Yes, that was some recognition problem of the correct SCSI-adapter
1122        and its I/O base addresses. Upgrade your driver to the latest release
1123        and it should be fine again.
1124     Q: I get a message: panic IBM MCA SCSI: command error .... , what can
1125        I do against this?
1126     A: Previously, I followed the way by ignoring command errors by using
1127        ibmmcascsi=forgiveall, but this command no longer exists and is
1128        obsolete. If such a problem appears, it is caused by some segmentation
1129        fault of the driver, which maps to some unallowed area. The latest 
1130        version of the driver should be ok, as most bugs have been solved.
1131     Q: There are still kernel panics, even after having set 
1132        ibmmcascsi=forgiveall. Are there other possibilities to prevent
1133        such panics?
1134     A: No, get just the latest release of the driver and it should work 
1135        better and better with increasing version number. Forget about this
1136        ibmmcascsi=forgiveall, as also ignorecmd are obsolete.!
1137     Q: Linux panics or stops without any comment, but it is probable, that my
1138        harddisk(s) have bad blocks.
1139     A: Sorry, the bad-block handling is still a feeble point of this driver,
1140        but is on the schedule for development in the near future.
1141     Q: Linux panics while dynamically assigning SCSI-ids or ldns.
1142     A: If you disconnect a SCSI-device from the machine, while Linux is up
1143        and the driver uses dynamical reassignment of logical device numbers
1144        (ldn), it really gets "angry" if it won't find devices, that were still
1145        present at boottime and stops Linux.
1146     Q: The system does not recover after an abort-command has been generated.
1147     A: This is regrettably true, as it is not yet understood, why the 
1148        SCSI-adapter does really NOT generate any interrupt at the end of
1149        the abort-command. As no interrupt is generated, the abort command
1150        cannot get finished and the system hangs, sorry, but checks are 
1151        running to hunt down this problem. If there is a real pending command,
1152        the interrupt MUST get generated after abort. In this case, it
1153        should finish well.
1154     Q: The system gets in bad shape after a SCSI-reset, is this known?
1155     A: Yes, as there are a lot of prescriptions (see the Linux Hackers'
1156        Guide) what has to be done for reset, we still share the bad shape of
1157        the reset functions with all other low level SCSI-drivers. 
1158        Astonishingly, reset works in most cases quite ok, but the harddisks
1159        won't run in synchronous mode anymore after a reset, until you reboot.
1160     Q: Why does my XXX w/Cache adapter not use read-prefetch?
1161     A: Ok, that is not completely possible. If a cache is present, the 
1162        adapter tries to use it internally. Explicitly, one can use the cache
1163        with a read prefetch command, maybe in future, but this requires
1164        some major overhead of SCSI-commands that risks the performance to
1165        go down more than it gets improved. Tests with that are running.
1166     Q: I have a IBM SCSI-2 Fast/Wide adapter, it boots in some way and hangs.
1167     A: Yes, that is understood, as for sure, your SCSI-2 Fast/Wide adapter
1168        was in such a case recognized as integrated SCSI-adapter or something 
1169        else, but not as the correct adapter. As the I/O-ports get assigned 
1170        wrongly by that reason, the system should crash in most cases. You 
1171        should upgrade to the latest release of the SCSI-driver. The 
1172        recommended version is 3.2 or later. Here, the F/W support is in
1173        a stable and reliable condition. Wide-addressing is in addition 
1174        supported.
1175     Q: I get an Oops message and something like "killing interrupt".
1176     A: The reason for this is that the IBM SCSI-subsystem only sends a 
1177        termination status back, if some error appeared. In former releases
1178        of the driver, it was not checked, if the termination status block
1179        is NULL. From version 3.2, it is taken care of this.
1180     Q: I have a F/W adapter and the driver sees my internal SCSI-devices,
1181        but ignores the external ones.
1182     A: Select combined busmode in the IBM config-program and check for that
1183        no SCSI-id on the external devices appears on internal devices.
1184        Reboot afterwards. Dual busmode is supported, but works only for the
1185        internal bus, yet. External bus is still ignored. Take care for your
1186        SCSI-ids. If combined bus-mode is activated, on some adapters, 
1187        the wide-addressing is not possible, so devices with ids between 8 
1188        and 15 get ignored by the driver & adapter!
1189     Q: I have a 9595 and I get a NMI during heavy SCSI I/O e.g. during fsck.
1190        A COMMAND ERROR is reported and characters on the screen are missing.
1191        Warm reboot is not possible. Things look like quite weird.
1192     A: Check the processor type of your 9595. If you have an 80486 or 486DX-2
1193        processor complex on your mainboard and you compiled a kernel that
1194        supports 80386 processors, it is possible, that the kernel cannot
1195        keep track of the PS/2 interrupt handling and stops on an NMI. Just
1196        compile a kernel for the correct processor type of your PS/2 and
1197        everything should be fine. This is necessary even if one assumes,
1198        that some 80486 system should be downward compatible to 80386
1199        software.
1200     Q: Some commands hang and interrupts block the machine. After some
1201        timeout, the syslog reports that it tries to call abort, but the
1202        machine is frozen.
1203     A: This can be a busy wait bug in the interrupt handler of driver 
1204        version 3.2. You should at least upgrade to 3.2c if you use 
1205        kernel < 2.4.0 and driver version 4.0 if you use kernel 2.4.0 or 
1206        later (including all test releases).
1207     Q: I have a PS/2 model 80 and more than 16 MBytes of RAM. The driver
1208        completely refuses to work, reports NMIs, COMMAND ERRORs or other
1209        ambiguous stuff. When reducing the RAM size down below 16 MB, 
1210        everything is running smoothly.
1211     A: No real answer, yet. In any case, one should force the kernel to
1212        present SCBs only below the 16 MBytes barrier. Maybe this solves the
1213        problem. Not yet tried, but guessing that it could work. To get this,
1214        set unchecked_isa_dma argument of ibmmca.h from 0 to 1.
1216   5.3 Bug reports
1217   --------------
1218   If you really find bugs in the source code or the driver will successfully
1219   refuse to work on your machine, you should send a bug report to me. The
1220   best for this is to follow the instructions on the WWW-page for this
1221   driver. Fill out the bug-report form, placed on the WWW-page and ship it,
1222   so the bugs can be taken into account with maximum efforts. But, please
1223   do not send bug reports about this driver to Linus Torvalds or Leonard
1224   Zubkoff, as Linus is buried in E-Mail and Leonard is supervising all
1225   SCSI-drivers and won't have the time left to look inside every single
1226   driver to fix a bug and especially DO NOT send modified code to Linus
1227   Torvalds or Alan J. Cox which has not been checked here!!! They are both
1228   quite buried in E-mail (as me, sometimes, too) and one should first check
1229   for problems on my local teststand. Recently, I got a lot of 
1230   bug reports for errors in the ibmmca.c code, which I could not imagine, but
1231   a look inside some Linux-distribution showed me quite often some modified
1232   code, which did no longer work on most other machines than the one of the
1233   modifier. Ok, so now that there is maintenance service available for this
1234   driver, please use this address first in order to keep the level of
1235   confusion low. Thank you!
1237   When you get a SCSI-error message that panics your system, a list of
1238   register-entries of the SCSI-subsystem is shown (from Version 3.1d). With 
1239   this list, it is very easy for the maintainer to localize the problem in 
1240   the driver or in the configuration of the user. Please write down all the 
1241   values from this report and send them to the maintainer. This would really 
1242   help a lot and makes life easier concerning misunderstandings.
1244   Use the bug-report form (see 5.4 for its address) to send all the bug-
1245   stuff to the maintainer or write e-mail with the values from the table. 
1247   5.4 Support WWW-page
1248   --------------------
1249   The address of the IBM SCSI-subsystem supporting WWW-page is:
1253   Here you can find info about the background of this driver, patches,
1254   troubleshooting support, news and a bugreport form. Please check that
1255   WWW-page regularly for latest hints. If ever this URL changes, please 
1256   refer to the MAINTAINERS file in order to get the latest address.
1258   For the bugreport, please fill out the formular on the corresponding
1259   WWW-page. Read the dedicated instructions and write as much as you
1260   know about your problem. If you do not like such formulars, please send
1261   some e-mail directly, but at least with the same information as required by
1262   the formular.
1264   If you have extensive bug reports, including Oops messages and
1265   screen-shots, please feel free to send it directly to the address
1266   of the maintainer, too. The current address of the maintainer is:
1268            Michael Lang <>
1270   6 References
1271   ------------
1272   IBM Corp., "Update for the PS/2 Hardware Interface Technical Reference, 
1273   Common Interfaces", Armonk, September 1991, PN 04G3281, 
1274   (available in the U.S. for $21.75 at 1-800-IBM-PCTB or in Germany for
1275   around 40,-DM at "Hallo IBM").
1277   IBM Corp., "Personal System/2 Micro Channel SCSI
1278   Adapter with Cache Technical Reference", Armonk, March 1990, PN 68X2365.
1280   IBM Corp., "Personal System/2 Micro Channel SCSI
1281   Adapter Technical Reference", Armonk, March 1990, PN 68X2397.
1283   IBM Corp., "SCSI-2 Fast/Wide Adapter/A Technical Reference - Dual Bus",
1284   Armonk, March 1994, PN 83G7545.
1286   Friedhelm Schmidt, "SCSI-Bus und IDE-Schnittstelle - Moderne Peripherie-
1287   Schnittstellen: Hardware, Protokollbeschreibung und Anwendung", 2. Aufl.
1288   Addison Wesley, 1996.
1290   Michael K. Johnson, "The Linux Kernel Hackers' Guide", Version 0.6, Chapel
1291   Hill - North Carolina, 1995
1293   Andreas Kaiser, "SCSI TAPE BACKUP for OS/2 2.0", Version 2.12, Stuttgart
1294   1993
1296   Helmut Rompel, "IBM Computerwelt GUIDE", What is what bei IBM., Systeme *
1297   Programme * Begriffe, IWT-Verlag GmbH - Muenchen, 1988
1299   7 Credits to
1300   ------------
1301   7.1 People
1302   ----------
1303   Klaus Grimm
1304                who already a long time ago gave me the old code from the
1305                SCSI-driver in order to get it running for some old machine
1306                in our institute.
1307   Martin Kolinek
1308                who wrote the first release of the IBM SCSI-subsystem driver.
1309   Chris Beauregard
1310                who for a long time maintained MCA-Linux and the SCSI-driver
1311                in the beginning. Chris, wherever you are: Cheers to you!
1312   Klaus Kudielka
1313                with whom in the 2.1.x times, I had a quite fruitful
1314                cooperation to get the driver running as a module and to get
1315                it running with multiple SCSI-adapters.
1316   David Weinehall
1317                for his excellent maintenance of the MCA-stuff and the quite 
1318                detailed bug reports and ideas for this driver (and his 
1319                patience ;-)).
1320   Alan J. Cox  
1321                for his bug reports and his bold activities in cross-checking
1322                the driver-code with his teststand.
1324   7.2 Sponsors & Supporters
1325   -------------------------
1326   "Hallo IBM",
1327   IBM-Deutschland GmbH
1328                the service of IBM-Deutschland for customers. Their E-Mail
1329                service is unbeatable. Whatever old stuff I asked for, I 
1330                always got some helpful answers.
1331   Karl-Otto Reimers,
1332   IBM Klub - Sparte IBM Geschichte, Sindelfingen
1333                for sending me a copy of the w/Cache manual from the 
1334                IBM-Deutschland archives.
1335   Harald Staiger
1336                for his extensive hardware donations which allows me today
1337                still to test the driver in various constellations.
1338   Erich Fritscher
1339                for his very kind sponsoring.
1340   Louis Ohland,
1341   Charles Lasitter
1342                for support by shipping me an IBM SCSI-2 Fast/Wide manual.
1343                In addition, the contribution of various hardware is quite 
1344                decessive and will make it possible to add FWSR (RAID)
1345                adapter support to the driver in the near future! So,
1346                complaints about no RAID support won't remain forever.
1347                Yes, folks, that is no joke, RAID support is going to rise!
1348   Erik Weber
1349                for the great deal we made about a model 9595 and the nice
1350                surrounding equipment and the cool trip to Mannheim
1351                second-hand computer market. In addition, I would like
1352                to thank him for his exhaustive SCSI-driver testing on his 
1353                95er PS/2 park.
1354   Anthony Hogbin
1355                for his direct shipment of a SCSI F/W adapter, which allowed
1356                me immediately on the first stage to try it on model 8557
1357                together with onboard SCSI adapter and some SCSI w/Cache.
1358   Andreas Hotz
1359                for his support by memory and an IBM SCSI-adapter. Collecting
1360                all this together now allows me to try really things with
1361                the driver at maximum load and variety on various models in
1362                a very quick and efficient way.
1363   Peter Jennewein
1364                for his model 30, which serves me as part of my teststand
1365                and his cool remark about how you make an ordinary diskette
1366                drive working and how to connect it to an IBM-diskette port.
1367   Johannes Gutenberg-Universitaet, Mainz &
1368   Institut fuer Kernphysik, Mainz Microtron (MAMI)
1369                for the offered space, the link, placed on the central
1370                homepage and the space to store and offer the driver and 
1371                related material and the free working times, which allow
1372                me to answer all your e-mail.
1374   8 Trademarks
1375   ------------
1376   IBM, PS/2, OS/2, Microchannel are registered trademarks of International 
1377   Business Machines Corporation
1379   MS-DOS is a registered trademark of Microsoft Corporation
1381   Microware, OS-9 are registered trademarks of Microware Systems
1383   9 Disclaimer
1384   ------------
1385   Beside the GNU General Public License and the dependent disclaimers and disclaimers
1386   concerning the Linux-kernel in special, this SCSI-driver comes without any
1387   warranty. Its functionality is tested as good as possible on certain 
1388   machines and combinations of computer hardware, which does not exclude,
1389   that data loss or severe damage of hardware is possible while using this
1390   part of software on some arbitrary computer hardware or in combination 
1391   with other software packages. It is highly recommended to make backup
1392   copies of your data before using this software. Furthermore, personal
1393   injuries by hardware defects, that could be caused by this SCSI-driver are
1394   not excluded and it is highly recommended to handle this driver with a
1395   maximum of carefulness.
1397   This driver supports hardware, produced by International Business Machines
1398   Corporation (IBM).
1401Michael Lang