******************************************************************************* 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. It is divided into the following sections: Introduction Features LSI Logic Devices Supported Installing the Linux Driver Modules Kernel Patch Instructions Driver Module Build Instructions Loading the Driver Modules Troubleshooting ******************************** Introduction ******************************* The Linux 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. The currently released Linux kernel does NOT contain these Fusion MPT drivers. Moreover, this [initial] host driver release package supports these drivers compiled as dynamically loadable modules -ONLY- at this time. It is expected that this driver will be bundled in a future linux-2.4.x kernel release, and will also support these drivers (or a subset) compiled into the linux kernel proper. ********************************* Features ********************************** o Supports SCSI and IETF-compliant LAN protocols concurrently over FC (LAN protocol requires kernel 2.4 or later) o Supports 1Gb Fibre Channel transfers (for SYMFC909) o Supports 2Gb Fibre Channel transfers (for SYMFC929 and SYMFC919) o Supports LSI Logic MPT common software interface o Handles one, or less than one, interrupt per I/O ************************ LSI Logic Devices Supported ************************ o SYMFC909 chips and adapters o SYMFC919 chips and adapters o SYMFC929 chips and adapters ******************** Installing the Linux Driver Modules ******************** The Linux driver tar archive should be unpacked from the root of your linux kernel source tree (normally /usr/src/linux). Example: $ cd /usr/src/linux $ zcat /tmp/mptlinux-1.00.00-4.tar.gz | tar xvf - ************************* Kernel Patch Instructions ************************* The Linux host drivers require a small set of patches to your linux kernel source tree. Patch sets for "well known" kernel versions have been included with the packed source tar archive. Supported linux kernel versions: 2.2.5-15, 2.2.5-16, 2.2.12, 2.2.12-20, 2.2.[13-16], 2.3.26, 2.3.[47-51], 2.3.99-pre[1-9], 2.4.0-test[1-5] To identify which kernel version you have, examine your /usr/src/linux/Makefile as follows: Example (on a Redhat(TM) 6.2 system): VERSION = 2 PATCHLEVEL = 2 SUBLEVEL = 14 EXTRAVERSION = -5.0 Then apply the closest patch set you can find. Example (on a Redhat 6.2 system): $ patch -p0 < patch/kpatch-2.2.14.txt These patches will apply small changes to the following files: Documentation/Configure.help arch/i386/config.in arch/sparc64/config.in drivers/Makefile include/linux/proc_fs.h NOTE: You may not find an exact match for your kernel, however, applying the closest patch set *should* work, in general, but may require that you manually fixup any files for which the patch procedure might produce *.rej file sections. You might optionally choose to hand-apply the small set of required kernel patches by examining one or more of the kpatch files. ********************* Driver Module Build Instructions ********************** The following procedure will build the LSI Logic Fusion MPT host driver(s) as kernel modules. 1. From the /usr/src/linux directory, run your normal kernel configuration routine: $ make oldconfig or: $ make config or: $ make menuconfig or: $ make xconfig 2. Look for the new top-level "Fusion MPT device support" entry: Fusion MPT device support ---> and select it to access the Fusion MPT driver submenu entries: Fusion MPT support (base + SCSI-Initiator) Extra English readable strings in SCSI Error Reports < > Fusion MPT misc device (ioctl) support (EXPERIMENTAL+DANGEROUS) < > Fusion MPT LAN driver (EXPERIMENTAL) Select the Fusion MPT support line and enter "m" or "M" to configure the selected driver module. The first line here, Fusion MPT support (base + SCSI-Initiator) module should always be selected, extra English readable strings module is optional, while the Fusion MPT misc device (ioctl) and Fusion MPT LAN drivers are optional and and won't even be visible unless CONFIG_EXPERIMENTAL is turned on. Save your kernel config changes. Follow the remaining instructions, which typically include: $ make dep or: $ make bzImage 3. Rebuild the kernel modules: $ make modules 4. NOTE: These last few steps will require root permission. (Re)Install newly compiled kernel modules: # make modules_install The output from the last step should look something like: 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 5. You should now re-install your newly compiled kernel and reboot. Example: # cp System.map /boot/System.map-2.2.14-5.0 # cd arch/i386/boot # cp bzImage /boot/vmlinuz-2.2.14-5.0 # lilo # shutdown -r now ************************ Loading the Driver Modules ************************* After building the driver modules, as described in the previous section, the newly compiled kernel and modules are ready to be loaded. 1. Load the Fusion MPT base driver. # insmod mpi Fusion MPT base driver 1.00.00-4 Copyright (c) 1999-2000 LSI Logic Corporation 2. Load the Isense driver (optional but highly recommended), to enable english readable SCSI-3 opcode and ASC/ASCQ strings. # insmod isense SCSI-3 Opcodes & ASC/ASCQ Strings 1.00.00-4 Copyright (c) 2000 Steven J. Ralston mpi: English readable SCSI-3 OPs & ASC/ASCQ strings enabled:-) 3. Load the Fusion MPT SCSI Initiator driver. # insmod mpiscsi Fusion MPT SCSI Initiator 1.00.00-4 Copyright (c) 1999-2000 LSI Logic Corporation Depending on what 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: ProductID = 0x0621 FWVersion = 0xe715 (Exp 0721) NumberOfPorts = 0x01 MsgVersion = 0x0100 WhoInit = 0x00 EventState = 0x00 CurrentHostMfaHighAddr = 0x00000000 CurrentSenseBufferHighAddr = 0x00000000 MaxChainDepth = 0x20 frames MinBlockSize = 0x20 bytes RequestFrames @ 0xc70a0000 (Dma @ 0x070a0000) {CurReqSz=128} x {CurReqDepth=1023} = 130944 bytes ^= 0x20000 {MaxReqSz=128} {MaxReqDepth=1023} ReplyFrames @ 0xc70c0000 (Dma @ 0x070c0000) {CurRepSz=128} x {CurRepDepth=128} = 16384 bytes ^= 0x4080 {MaxRepSz=128} {MaxRepDepth=1023} 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 mpiscsi 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 ****************************** Troubleshooting ****************************** 1. The SCSI Driver error reporting has been nicely enhanced, making it much 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 off the SCSI T10.org's ftp site: ftp://ftp.t10.org/t10/drafts/spc2/asc-num.txt If the isense driver is (optionally) loaded, whenever a SCSI check condition is generated[1], an english readable ASC/ASCQ string for the SCSI error. Here's an example: ----- SCSI Error Report =-=-= (ioc0,scsi5:0) SCSI_Status=02h (CHECK_CONDITION) Original_CDB[]: 2A 00 00 00 00 41 00 00 02 00 - "WRITE(10)" SenseData[12h]: 70 00 02 00 00 00 00 0A 00 00 00 00 04 02 02 00 00 00 SenseKey=2h (NOT READY); FRU=02h ASC/ASCQ=29h/00h "LOGICAL UNIT NOT READY, INITIALIZING CMD. REQUIRED" ----- If the Isense shim installed, the SCSI opcode string nor the last ASC/ASCQ string will be displayed. 2. If you have compiled your linux kernel with /proc file system support, you can examine SCSI devices using this command: $ cat /proc/scsi/scsi A few of the Fusion MPT driver internals may be examined with either of the following commands: $ cat /proc/scsi/mpiscsi/0 $ cat /proc/mpi/info 3. If you have a 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. 4. If issues are encountered with the Fusion MPT LAN driver, make sure the most recent kernel (2.4.x?) sources are being used. ***************************************************************************** Fusion MPT is a trademark of LSI Logic Corporation Linux is a registered trademark of Linus Torvalds Redhat is a registered trademark of Red Hat Software, Inc. *****************************************************************************