******************************************************************************
                                 mptlinux.txt
******************************************************************************

This file presents general information about the LSI Logic Fusion-MPT (TM)
(Message Passing Technology) device drivers for Linux(TM).
It also describes the features and use of the device drivers for the
Linux operating system environment.

This file is divided into the following sections:
   Introduction
       Features
       LSI Logic Devices Supported
   Fusion-MPT Linux Drivers
       Installing to a Fusion-MPT Controller
       Adding Pre-Compiled Binaries to an Existing Installation
       Adding or Updating the Fusion-MPT Source to the Linux Kernel
            Updating the Bundled Fusion-MPT Driver Source
            Adding Fusion-MPT Driver Source
            Driver Build Instructions
       Loading the Drivers As Modules
       Boot Setup Commands
            Syntax
            Available Arguments
   Troubleshooting

******************************** Introduction ********************************

The mptlinux drivers are free software and are supported in source form.
These drivers are distributed in the hope that they will be useful, but
without any warranty and without even the implied warranty of merchantability
or fitness for a particular purpose. You can redistribute them and/or modify
them under the terms of version 2 or later of the GNU Public License as
published by the Free Software Foundation. You should have received a copy
of this license with your Linux kernel source tree (/usr/src/linux/COPYING).
For detailed information on the GNU Public License, contact the Free Software
Foundation, Inc at 59 Temple Place - Suite 330, Boston, MA 02111-1307 or at
URL http://www.gnu.org/copyleft/gpl.html.

=== Features ===

o  Supports SCSI, Fibre Channel, and Serial Attached SCSI
o  Supports 1 Gbit/s Fibre Channel transfer rates (LSIFC909)
o  Supports 1 Gbit/s and 2 Gbit/s Fibre Channel transfer rates (LSIFC919,
   LSIFC929, LSIFC919X, LSIFC929X)
o  Supports Ultra320 transfer rates (LSI53C1030, LSI53C1020)
o  Supports Serial Attached SCSI (SAS1064, SAS1068)
o  Supports LSI Logic Fusion-MPT Architecture and common software interface
o  Low host CPU utilization with one, or less than one, interrupt per I/O

=== LSI Logic Devices Supported ===

o LSIFC909 chips and LSI40909 adapters
o LSIFC919 chips and LSI40919 adapters
o LSIFC919X chips and LSI7102X adapters
o LSIFC929 chips and LSI44929, LSI7402 adapters
o LSIFC929X chips and LSI7202X, LSI7402X adapters
o LSIFC949X chips
o LSI53C1020(A) chips and LSI20320 adapters
o LSI53C1030 chips and LSI22320, LSI21320 adapters
o LSISAS1064, LSISAS1068, and LSISAS1078 chips

****************** Fusion-MPT Linux Drivers *******************

The mptlinux drivers are provided in binary and source form
to provide the greatest flexibility to LSI Logic's customers.  
The binaries are suitably formatted for use as installation 
diskettes or post-install binary upgrades.  The source may be 
added to an existing kernel for custom kernel builds.

NOTE: THERE ARE TWO DRIVERS!!
2.xx.xx for Kernel 2.4 (for Red Hat AS2.1, EL3.0, and SuSE SLES8).
3.xx.xx for Kernel 2.6 (for Red Hat EL4.0, SuSE SLES9, and above).

=== Installing to a Fusion-MPT Controller ===

LSI Logic provides 1.44MB images that are suitably formatted to use
as driver update disks for those installations where there is no
bundled driver or when it's necessary to complete the install with
the latest driver:
    Red Hat AS2.1, EL3.0, EL4.0 (i686 and ia64); EL3.0, EL4.0 (x86_64)
    SuSE SLES8, SLES9 (i386, ia64, x86_64); 

=== Adding Pre-Compiled Binaries to an Existing Installation ===

Driver binaries are provided in 1.44MB images that are suitably 
formatted to use as driver update disks for:
    Red Hat AS2.1, EL3.0, EL4.0 (i686 and ia64); EL3.0, EL4.0 (x86_64)
    SuSE SLES8, SLES9 (i386, ia64, x86_64); 
and in RPMS:
    Red Hat  i686  : AS2.1, EL3.0, EL4.0
    Red Hat  ia64  : AS2.1, EL3.0, EL4.0
    Red Hat  x86_64: EL3.0, EL4.0
    Red Hat ia32e  : EL3.0 Quarterly Update 2, 3, 4, 5
    SuSE     i386  : SLES8, SLES9
    SuSE     ia64  : SLES8, SLES9
    SuSE     x86_64: SLES8, SLES9
RPMs should be used to upgrade the driver post-install.

The RPMs contain binaries for the install kernel and the latest two
released errata kernels for each distribution at the time the RPM
was created.  See the README_rpms.txt file for a listing of
the kernels supported by the RPM. The update disks should be
used for architectures not supported by RPM.

The driver disk image can be transfered to floppy disk with the 
rawrite tool from dos, or the dd utility in Linux.  Here is the URL
for rawrite:
http://www.tux.org/pub/dos/rawrite/

Special Instructions for Red Hat installs: To use the driver disks, 
follow the instructions from the previous paragraph to transfer 
the image to a diskette.  Then when installation is complete, do
the following:
	# mount /dev/fd0
	# cd /mnt/floppy
	# ./post_install.scr
	# cd
	# umount /dev/fd0

To use the RPMs, the standard install, the erase and upgrade commands
may be used.  The driver source will be placed in your
installations RPM Base directory, i.e. /usr/src/redhat or
/usr/src/packages.  On the ftp site,
    ftp> cd 2.06.48
    ftp> cd mptlinux-rpms
download the appropriate tarball.

=== Adding or Upgrading the Fusion-MPT Source to the Linux Kernel ===

This is a two step procedure:
    1) Add or upgrade the Fusion-MPT source
    2) Patch the kernel


------ Updating Bundled Fusion-MPT Driver Source

LSI Logic recommends that you save the original source:
  # cd /usr/src/linux/drivers/message
  # tar czvf fusion.orig.tar.gz fusion

Continue with the instructions in "Adding Fusion-MPT Driver Source."

------ Adding Fusion-MPT Driver Source

For Red Hat 7.0, all 2.2 and 2.4.0 through 2.4.6 kernels, Fusion-MPT support
must be added to the kernel source.

1. Unpack the mptlinux driver source tar archive in a temporary directory 
   (/home/<myname>/mptlinux-tmp).
    Example:
      $ cd
      $ mkdir mptlinux-tmp
      $ cd mptlinux-tmp
      $ zcat /tmp/mptlinux-2.06.48-src.tar.gz | tar xvf -

2. Run the script "install" to install the source to the kernel 
   directory. For example, to install the source into 
   /usr/src/linux-2.4.18-20
      $ su root
      # ./install /usr/src/linux-2.4.18-20

------ Driver Build Instructions

The following examples show how to configure and build the LSI Logic 
Fusion-MPT driver(s) as kernel modules. However, the MPT base and ScsiHost 
drivers can alternatively be compiled into the Linux kernel instead of 
being built as modules.

1.  From the /usr/src/linux directory, ensure a clean kernel source
    tree by executing the following command:
        # make mrproper

2.  From the /usr/src/linux directory, run the normal kernel
    configuration routine:
        # make oldconfig
      or:
        # make config
      or:
        # make menuconfig
      or:
        # make xconfig

3.  Look for the new top-level "Fusion-MPT device support" entry:
        Fusion-MPT device support  --->
      and select it to access the Fusion-MPT drivers submenu entries:
        <M> Fusion-MPT (base + ScsiHost) drivers
        <M>   Enhanced SCSI error reporting
        < >   Fusion-MPT misc device (ioctl) driver
        < >   Fusion-MPT LAN driver

      On the submenu, select the "Fusion-MPT (base + ScsiHost) drivers" line,
      and then enter "m" to configure for building this support as a module.
      (Alternatively, you can enter "y" to have this support built
      into the kernel.)

      NOTES:
       o  Enhanced SCSI error reporting and ioctl drivers are optional.
          LSI Logic recommends that they only be built as modules,
          due to kernel size considerations.
       o  DO NOT answer "y" for the Fusion-MPT LAN driver option! Support
          for this driver is currently restricted to module use only.

4.  For LAN support, make sure that "Fibre Channel driver support" is turned
    on in the "Network device support" section.

5.  Save the kernel config changes.  Follow any post config instructions,
    and do everything needed on your platform to rebuild the kernel.
    This typically includes:
        # make dep
      and:
        # make bzImage			# varies on non-Intel platforms

6.  Rebuild the kernel modules:
        # make modules

7.  Optionally, (and potentially dangerous!), do everything needed
    on your platform to install a newly built kernel.
    (possibly temporarily, for sanity testing)

      Be careful with this step, and be sure you know what you're doing!
      It is easy to wipe out a good/stable kernel from this point forward 
      in the procedure!

8.  (Re)Install newly compiled kernel modules:
        # make modules_install

      The output from the last step should look something like this:
        Installing modules under /lib/modules/2.2.14-5.0/block
        Installing modules under /lib/modules/2.2.14-5.0/net
        Installing modules under /lib/modules/2.2.14-5.0/ipv4
        Installing modules under /lib/modules/2.2.14-5.0/scsi
        Installing modules under /lib/modules/2.2.14-5.0/fs
        Installing modules under /lib/modules/2.2.14-5.0/fs
        Installing modules under /lib/modules/2.2.14-5.0/cdrom
        Installing modules under /lib/modules/2.2.14-5.0/video
        Installing modules under /lib/modules/2.2.14-5.0/net
        Installing modules under /lib/modules/2.2.14-5.0/misc

9.   Update your /boot sector with the new System.map and bzImage,
     re-create your ramdisk image (refer to your vendor literature), and
     update your boot manager--i.e., lilo.conf, grub.conf. If you are
     using lilo, you must run lilo -v prior to reboot.

10.  Shut down the system:
      Example:
        # shutdown -r now
      and then reboot with the newly built Linux kernel.

=== Loading the Drivers As Modules ===

Follow these steps to load the new driver binaries:

1.  Load the Fusion-MPT base driver.
        # insmod mptbase
        Fusion-MPT base driver 2.06.48
        Copyright (c) 1999-2002 LSI Logic Corporation
        mptbase: Initiating ioc0 bringup
        ioc0: FC919: Capabilities={Initiator,Target,LAN}
        mptbase: 1 MPT adapter found, 1 installed.

2.  Load the isense driver (optional but highly recommended),
    to enable enhanced SCSI error reporting.
        # insmod isense
        SCSI-3 Opcodes & ASC/ASCQ Strings 2.06.48
        mptbase: English readable SCSI-3 OPs & ASC/ASCQ strings enabled.

3.  Load the Fusion-MPT SCSI host driver.
        # insmod mptscsih
        Fusion-MPT SCSI Host driver 2.06.48

      Depending on which FC devices you have attached to your FC link,
      you should see something like the following on the console and
      in the system log:
        scsi0 : ioc0: LSIFC919, FwRev=1000h, Ports=1, MaxQ=256, IRQ=9
        scsi : 1 host.
          Vendor: SEAGATE   Model: ST39102FC         Rev: 0007
          Type:   Direct-Access                      ANSI SCSI revision: 02
        Detected scsi disk sda at scsi0, channel 0, id 0, lun 0
          Vendor: SEAGATE   Model: ST19171FC         Rev: 0017
          Type:   Direct-Access                      ANSI SCSI revision: 02
        Detected scsi disk sdb at scsi0, channel 0, id 1, lun 0
        SCSI device sda: hdwr sector= 512 bytes. Sectors= 17783240 [8683 MB] [8.7 GB]
         sda: sda1
        SCSI device sdb: hdwr sector= 512 bytes. Sectors= 17783112 [8683 MB] [8.7 GB]
         sdb: sdb1

    All Fibre Channel target devices should be detected and mapped to Linux
    SCSI devices, /dev/sd{a,b,c,...} when the mptscsih module is loaded.

    All Linux commands pertaining to SCSI disk storage management
    (fdisk, mke2fs, mount, etc.) using the /dev/sdX[N] notation
    should now be functional.

    FCP (SCSI) Device Access Example:
        # fdisk /dev/sdb
        # mke2fs /dev/sdb1
        # mount /dev/sdb1 /mnt/s1

=== Boot Setup Commands ===

1. Syntax

Setup commands can be passed to the SCSI host driver mptscsih
as a string variable using 'insmod'.  The following command
installs the driver module with the bus width set to narrow
and Domain Validation disabled:

    insmod mptscsih.o mptscsih="dv:n width:0"

Each string argument must be specified as "keyword:value". Only lower-case
characters and digits are allowed.

2.  Available Arguments
Two arguments require updating: saf-te and pt-clear.

2.1 Domain Validation
        dv:n    disabled
        dv:y    enabled [default]

    The SCSI host driver performs a sequence of write, read, and compare
    commands to each target device during driver initialization. If the 
    driver detects data corruption or bus hangs during this sequence, it
    automatically slows the transfer rate until reliable transmission is
    achieved.

    Warning: These tests use a device's internal buffer.  Some older SCSI 
    devices freeze when they receive a Read or Write Buffer command.

    DV may be disabled on a per-device basis by setting the transfer
    characterists to ASYNC and NARROW in the adapter BIOS.  Alternatively,
    DV may be disabled for the driver by passing in dv:n as a command
    line argument.

    This option has no effect for LSIFC9XX parts.

2.2 Maximum SCSI Bus Width
        width:0      wide SCSI disabled
        width:1      wide SCSI enabled

    The maximum allowed SCSI bus data transfer width is set to the
    minimum of the command line options, adapter capabilities, and
    NVRAM settings.

    This option has no effect for LSIFC9XX parts.

2.3 Minimum SCSI Synchronous Factor
        factor:0x08   Ultra320 (160 Mega-transfers / second)
        factor:0x09   Ultra160 ( 80 Mega-transfers / second)
        factor:0x0A   Ultra2   ( 40 Mega-transfers / second)
        factor:0x0C   Ultra    ( 20 Mega-transfers / second)
        factor:0x19   FAST     ( 10 Mega-transfers / second)
        factor:0x32   SCSI     (  5 Mega-transfers / second)
        factor:0xFF   5 Mega-trasfers/second and asynchronous

    The minimum allowed SCSI synchronous factor is set to the
    maximum of the command line input, adapters capabilities, and
    NVRAM setting.  If the minimum synchronous factor is 0xFF, the
    synchronous offset is set to 0 (asynchronous).

    This option has no effect for LSIFC9XX parts.

Note: The above requires corrections for C1020A capability.

****************************** Troubleshooting *******************************

1.  The SCSI driver error reporting has been nicely, making it much
    more readable. Also, there's an (optional) isense driver/shim which
    provides SCSI-3 opcode string lookup and a LARGE sorted table of 463
    unique SCSI-3 Additional Sense Code & Qualifier (ASC/ASCQ) strings,
    translated directly from a text file from the SCSI T10.org's ftp site:

        ftp://ftp.t10.org/t10/drafts/spc2/asc-num.txt

    If the isense driver is (optionally) loaded, it displays an English readable 
    ASC/ASCQ string for the SCSI error whenever a SCSI check condition is 
    generated[1].

    Here is an example:
    -----
    SCSI Error (<ioc number>:<target id>:<lun>) SCSI_Status=02h (CHECK_CONDITION)
      Key=2h (NOT READY); FRU=02h
      ASC/ASCQ=29h/00h "LOGICAL UNIT NOT READY, INITIALIZING CMD. REQUIRED"
      CDB[]: 2A 00 00 00 00 41 00 00 02 00 - "WRITE(10)"
    -----

    If the isense driver is NOT installed, neither the SCSI opcode string
    nor the last ASC/ASCQ string is displayed.

    The SCSI Error report is displayed only if the error occured on
    a SCSI read or write command.  Any errors on other commands, Request Sense,
    Test Unit Ready, etc., are not displayed.

2.  If you compiled the Linux kernel with /proc file system support,
    you can examine SCSI devices using this command:
      $ cat /proc/scsi/scsi

    A summary of attached/recognized Fusion-MPT adapters can be examined with the
    following command:
      $ cat /proc/mpt/summary

    The driver version is stored in
      $ cat /proc/mpt/version

3.  If you have an LSI Fibre Channel RAID subsystem attached, some of the
    standard Linux SCSI devices that show up will not be accessible,
    depending on the exact configuration of the RAID controller(s).
    For example, if you have dual active controllers in one subsystem with
    8 active LUNs configured for each controller, all 16 LUNs will be visible
    through each controller (32 SCSI devices total), although only 8 LUNs
    will actually be accessible from each controller.  There is currently
    no filtering out of the "visible but not accessible" entries.

******************************************************************************

Fusion-MPT is a trademark of LSI Logic Corporation
Linux is a registered trademark of Linus Torvalds
Red Hat is a registered trademark of Red Hat Software, Inc.

******************************************************************************


