File Name: MPTLINUX.TXT LSI Logic Fusion-MPT (TM) LINUX OS Driver: V2.05.00 CONTENTS --------- 1.0 Overview 2.0 Change History 3.0 Installation and Setup Instructions 4.0 Configuration Information 5.0 Unattended Mode 6.0 Web Sites and Support Phone Number 7.0 Trademarks and Notices 8.0 Disclaimer 1.0 Overview: 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. 1.1 Overview about this code None. 1.2 Limitations None. 1.3 Enhancements o Supports Ultra320 transfer rates 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 1.4 Level of Recommendations and Prerequisites for the Update: None. 1.5 Dependencies: None. 2.0 Change History -------------------- 2.05.00 more Performance enhancements 2.03.00 Performance enhancements. Fixed memory leak. 2.02.00 New release. 3.0 Installation and Setup Instructions ----------------------------------------- The mptlinux drivers are provided in binary and source form to provide the greatest flexibility to our 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. 3.1 Installing to a Fusion-MPT controller The Fusion-MPT driver is a bundled boot controller for Red Hat 7.3 and SuSE 8.0. You may install to a disk attached to the controller with no additional media. 1.44MB images are provided that are suitably formatted to use as driver update disks for: Red Hat 7.2 (32 bit and 64 bit), 7.3 and 2.1ASE SuSE 7.2, 7.3 and 8.0 Caldera 3.1 and 3.1.1 For Red Hat 8.0 and SuSE 8.1, the user must install using the bundled driver. Upgrades may be performed using the appropriate RPM. For further instructions, refer to the included OS-specific readme files and use the appropriate tarball. 3.2 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 7.2 (32 bit and 64 bit), 7.3 and 2.1ASE SuSE 7.2, 7.3 and 8.0 Caldera 3.1 and 3.1.1 and in RPMS: Red Hat 7.2 (i686, ia64), 7.3(i686), 8.0(i686) and 2.1ASE(i686) SuSE 7.2(i386), 7.3(i386), 8.0(i386) and 8.1(i386) Either may be used to upgrade the driver. The RPMs contain binaries for the install kernel and the latest released kernel for each distribution. The update disks contain a wider collection of binaries. To use the driver disks, follow the instructions from the previous section to transfer the image to a diskette. Then: # mount /dev/fd0 # cd /mnt/floppy # ./post_install.scr # cd # umount /dev/fd0 To use the RPMs, the standard install, 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. 3.3 Adding or Upgrading 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 3.3.1 Adding the 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. In these cases, the mptlinux driver source 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-2.03.00-src.tar.gz | tar xvf - 3.3.2 Updating Bundled Fusion-MPT Driver Source A version of the mptlinux driver is bundled in Red Hat 7.1 and 7.2 and official kernels starting with version 2.4.7. Before updating the bundled source, save the original driver tree in a compressed tar file. Example: # cd /usr/src/linux/drivers/message # tar czvf fusion.orig.tar.gz fusion Extract the tarball into a temporary directory, $ mkdir Fusion-Tmp $ tar xzvf /tmp/mptlinux-2.03.00-src.tar.gz then # cd /usr/src/linux/drivers/message/fusion Clean the existing C-source and patch files: # rm -f *[ch] lsi/* patch/* Copy the new sources: # cp /Fusion-Tmp/drivers/message/fusion/*[ch] . # cp /Fusion-Tmp/drivers/message/fusion/lsi/*.h lsi # cp /Fusion-Tmp/drivers/message/fusion/patch/* patch Do not overwrite the existing Makefile. 3.3.3 Kernel Patch Instructions The mptlinux host drivers may require a small set of patches to your linux kernel source tree. Patch sets for stock and "well known" kernel versions have been included with the packed source tar archive. Patches may be required even if the mptlinux driver is currently bundled. Fusion patch files available for linux 2.2.x kernel versions: 2.2.5-15, 2.2.5-16, (Red Hat 6.0) 2.2.12, 2.2.12-20, (Red Hat 6.1) 2.2.13, 2.2.14, 2.2.14-5.0, 2.2.14-6.0, (Red Hat 6.2) 2.2.14-caldera, (Caldera 2.3.1) 2.2.15, 2.2.16, 2.2.16-22, (Red Hat 7.0) 2.2.17, 2.2.18, 2.2.18-2, (TurboLinux 6.5) 2.2.19, 2.2.20 Fusion patch files available for linux 2.4.x kernel versions: 2.4.0, 2.4.1, 2.4.2, 2.4.2-2, (Red Hat 7.1) , (Caldera 3.1) 2.4.3, 2.4.3-6, (Red Hat 7.1, SBE) 2.4.3-12, (Red Hat 7.1, upd#1) 2.4.4, 2.4.4-4GB, (SuSE 7.2 - i386 and ia64) 2.4.5, 2.4.5-3, (TurboLinux 7.0) 2.4.6, 2.4.7, 2.4.7-10, (Red Hat 7.2) 2.4.7-4GB, (SuSE Enterprise Server 7) 2.4.8, 2.4.9, 2.4.9-e.3, (Red Hat 7.2 ASE) 2.4.9-6, (Red Hat 7.1, upd#2) 2.4.9-13, (Red Hat 7.2, upd#1) 2.4.9-18, (Red Hat 7.2 IA64) 2.4.9-21, (Red Hat 7.2, upd#2) 2.4.9-31, (Red Hat 7.2 IA64, upd#1) 2.4.9-34, (Red Hat 7.2 IA64, upd#2) 2.4.10, 2.4.10-4GB, (SuSE 7.3) 2.4.11 (broken kernel, do not use), 2.4.12, 2.4.13, 2.4.13-caldera, (Caldera 3.1.1) 2.4.14, 2.4.15, 2.4.16, 2.4.17, 2.4.18, No Patches are required for kernels > 2.4.18 That is, no kernel patches are required for: 2.4.18-3, 2.4.18-4, ..(Red Hat 7.3 ...) 2.4.18-4GB (SuSE 8.0) 2.4.19 Fusion patch files available for linux 2.5.x kernel versions: Fusion support starts with kernel 2.4.24. No patches required. NOTES: o The Fusion-MPT LAN driver is NOT supported in any of the 2.2.x kernels listed here. You MUST be working with a linux-2.4.x kernel for Fusion-MPT LAN support. o For module support under 2.3.x and 2.4.x kernels you must have modutils v2.3.15 or newer installed. o IA64 support requires a linux-2.4.x kernel. 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 Red Hat 6.2 system): $ patch -p0 < drivers/message/fusion/patch/linux-2.2.14-5.0.txt These patches will apply small changes to the following files: Makefile arch/alpha/config.in arch/i386/config.in arch/sparc64/config.in drivers/Makefile include/linux/miscdevice.h 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 kernel patch files. 3.3.4 Driver Build Instructions The following examples illustrate configuring and building the LSI Logic Fusion-MPT driver(s) as kernel modules, however, please note that the MPT base and ScsiHost drivers can alternatively be compiled into the linux kernel instead of 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 your 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: Fusion-MPT (base + ScsiHost) drivers 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" here to have this support built into the kernel.) NOTES: o Enhanced SCSI error reporting and ioctl drivers are optional, and it is recommended they only be built as modules, due to kernel size considerations. o DO NOT answer "y" for Fusion-MPT LAN driver option as 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 your kernel config changes. Follow any post config instructions and do everything needed on your platform to rebuild the kernel. This will typically include: # 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) Take care with this step and make sure you know what you're doing as it's easy to wipe out a good/stable kernel from here on out! 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. 3.4 Loading the Drivers As Modules The new driver binaries are ready to be loaded. 1. Load the Fusion-MPT base driver. # insmod mptbase Fusion-MPT base driver 2.03.00 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.03.00 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.03.00 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: 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 3.5 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 will install 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 2.1 Domain Validation dv:n disabled dv:y enabled [default] The SCSI host driver will perform a sequence of write, read and compare commands to each target device during driver initialization. If data corruption or bus hangs are detected during this sequence, the driver will automatically slow the transfer rate until reliable transmission is achieved. Warning! These tests use a devices internal buffer. Some older SCSI devices behave badly, that is, 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. 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. 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 will be set to 0 (asynchronous). 4.0 Configuration Information ------------------------------- None. 5.0 Unattended Mode ------------------------------- None. 6.0 WEB Sites and Support Phone Number ---------------- 6.1 IBM Support Web Site: http://www.ibm.com/server/support 6.2 IBM eServer xSeries Web Site: http://www.pc.ibm.com/us/eserver/xseries/ 6.3 IBM Support Telephone Numbers: http://www.ibm.com/planetwide/ 7.0 Trademarks and Notices ---------------------------- 7.1 The following terms are trademarks of the IBM Corporation in the United States or other countries or both: IBM 7.2 Intel trademarks or registered trademarks are trademarks of Intel Corporation. 7.3 Other company, product, and service names may be trademarks or service marks of others. 8.0 Disclaimer ---------------------------- 8.1 THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY PATENTS OR COPYRIGHTS. 8.2 Note to Government Users Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.