******************************************************************************
                                 Linux_ReadMe.txt
******************************************************************************

This file presents general information about the LSI Logic Fusion-MPT (TM)
(Message Passing Technology) device drivers for Linux(TM). 

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
   Configuration
       Queue Depth
       Maximum I/O Size
       Driver based LUN Persistence
       MSI Support
   Troubleshooting


1.0 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.

1.1 Features
............

The Linux drivers supports these features:

o  1GB, 2GB and 4GB Fibre Channel transfers 
o  PCI, PCI-X and PCIe bus protocols
o  LSI Logic MPT common software interface 
o  Multiple host adapters 
o  Multiple Logical Unit Numbers (LUNs) 
o  Scatter-Gather 
o  SCSI pass-through functionality 
o  Low host CPU utilization with one, or less than one, interrupt per I/O

1.2 LSI Logic FC Devices Supported
...................................

o  LSIFC919 (LSI40919O, LSI40919LO, LSI40919H, LSI40919LH)
o  LSIFC929 (LSI44929O, LSI44929LO, LSI44929H, LSI44929LH, 7004G2-LC)
o  LSIFC919X (LSI7102XP)
o  LSIFC929X (LSI7202XP, LSI7402XP)
o  LSIFC949X (LSI7104XP, LSI7204XP, LSI7404XP)
o  LSIFC949E (LSI7104EP, LSI7204EP, LSI7404EP)


1.3 Fusion-MPT Linux Driver Versions
....................................

There are three LSI driver threads, identified by their version numbers.

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).

4.xx.xx for Kernel 2.6 (for Red Hat EL5.0, SuSE SLES10, and above).


2.0 Installation with Driver Update Disks and RPMs
...................................................

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, EL5.0 (i686 and ia64); 
    Red Hat EL3.0, EL4.0, EL5.0 (x86_64)
    SuSE SLES8, SLES9, SLES10 (i386, ia64, x86_64); 

and in RPMS:

    Red Hat  i686  : AS2.1, EL3.0, EL4.0, EL5.0
    Red Hat  ia64  : AS2.1, EL3.0, EL4.0, EL5.0
    Red Hat  x86_64: EL3.0, EL4.0, EL5.0
    Red Hat ia32e  : EL3.0 Quarterly Update 2, 3, 4, 5
    SuSE     i386  : SLES8, SLES9, SLES10
    SuSE     ia64  : SLES8, SLES9, SLES10
    SuSE     x86_64: SLES8, SLES9, SLES10

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.65.00
    ftp> cd mptlinux-rpms
download the appropriate tarball.



3.0 Installation from Source to the Linux Kernel
..................................................................

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


First, save the original source:

  # cd /usr/src/linux/drivers/message
  # tar czvf fusion.orig.tar.gz fusion

Then, 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
      $ cp /tmp/mptlinux-2.06.65.00-src.tar.gz .
      $ tar xfz mptlinux-2.06.65.00-src.tar.gz

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


4.0 Building the Drivers as Kernel Modules
..........................................

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.



4.0 Loading the Driver Kernel 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.65.00
        Copyright (c) 1999-2007 LSI Logic Corporation
        mptbase: Initiating ioc0 bringup
        ioc0: FC919: Capabilities={Initiator,Target,LAN}
        mptbase: 1 MPT adapter found, 1 installed.

2.  Load the Fusion-MPT SCSI host driver.
        # insmod mptscsih
        Fusion-MPT SCSI Host driver 2.06.65.00

      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


5.0 Configuration 
..................

The configuration options for Linux varies between driver versions and Linux distributions. 
The options available to a particular release can be discovered using this request:

	modinfo mptbase

may return as list as follows:

	parm:   mpt_msi_enable: MSI Support Enable (default=0)
	parm:   mpt_chain_alloc_percent: SG Chain buffer allocation percent (default=100)
	parm:   mpt_reply_depth: Max reply buffers per controller (default=128)
	parm:   mpt_sg_tablesize: Max SG count per IO (default=40)
	parm:   mpt_can_queue: Max IO depth per controller (default=128)

LSI Linux 2.6 kernel drivers may be configured by including command line parameters on the 
mptbase.ko module when the module is installed.   


5.1 Queue Depth 
..................

The mpt_can_queue parameter specifies the maximum IO depth per HBA port. This value can range 
from 32 to 1024, however the value should not be configured to exceed the combined I/O queue 
depths of the attached devices. 

	insmod ./mpbase.ko mpt_can_queue = 128


The reply depth parameter specifies the Reply Queue depth for the HBA.  In general, the reply 
queue depth should be greater than or equal to the mpt_can_queue depth

	insmod ./mpbase.ko mpt_reply_depth = 128

5.2 Maximum I/O Size 
.....................

The mpt_sg_tablesize parameter specifies the maximum number of Scatter Gather entries per 
I/O request. The default value allows an I/O request size of 512kB. Increasing the default 
value is not recommended unless an I/O request size will exceed 512kB.

	insmod ./mpbase.ko mpt_sg_tablesize = 40


The mpt_chain_alloc_percent parameter is used in conjunction with mpt_sg_tablesize. Chain 
buffers are allocated from system memory with the assumption that every I/O request will 
be the max size specified by mpt_sg_tablesize.  If this is not the case, and a percentage 
of max sized I/O requests can be known, this value can be decreased accordingly. If system 
memory resource errors result, the percentage will need to be increased again.

	insmod ./mpbase.ko mpt_chain_alloc_percent = 100


5.3 Driver based LUN Persistence 
.................................

LUN Persistence is enabled by default, on the Linux driver. By changing the mpt_pt_clear
parameter to 1, the persistence table is cleared each time the driver is loaded.

	insmod ./mpbase.ko mpt_pt_clear = 0

5.4 MSI Support 
................

The mpt_msi_enable parameter allows Message Signalled Interrupts to be used on the host 
system. The default value is zero (disabled), meaning hardware interrupts will be used. 
If the HBA supports MSI, MSI can be successfully enabled.  If the HBA does not support MSI, 
hardware interrupts will be the default.

	insmod ./mpbase.ko mpt_msi_enable = 0





6.0 Troubleshooting 
....................


1.  The SCSI driver error reporting has been enhanced, making it much
    more readable.

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

    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)"
    -----

    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.

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



