IBM FixID Readme for QLogic Fibre Channel Driver (qla2xxx) for Driver version 8.02.00.05.5.2-k5 © Copyright by IBM Corporation 2008. All rights reserved. Note: Before using this information and the product it supports, read the general information in "Notices and trademarks" in this document. Contents 1. Introduction 2. Requirements 3. Inside the FixID 4. How it all works 5. Naming conventions 6. Typical usage 6.1 Installation 6.2 Upgrading / downgrading 6.3 Uninstallation 7. IBM driver tool manpage 8. Support 9. Notices and trademarks 1. Introduction On a Linux system, loadable device drivers, or kernel modules, are highly dependent on the version of kernel that they support. Generally, when a new kernel is made available by a Linux distribution, new kernel modules are provided at the same time to match this new kernel version. In some cases, there may be a need to use a device driver not provided by the distribution, either the hardware is not yet officially supported, or a specific version is needed. In such cases, it is often the case that one needs to build new device drivers from source or be provided kernel modules that match one's kernel. This README is part of a tarball, also referred to as a FixID, contains a set of device drivers (packaged as RPMs), along with some scripts and tools used to help install these RPM packaged device drivers. 2. Requirements You need to have Perl, rpm-build, and rpm-lib installed to use the installation scripts and its helper 'driver tool'. These are likely already installed, but if not, they can be found on the installation media for your Linux distribution. 3. Inside the FixID At the top level of the FixID is an install.sh script. By default, running this script will install the latest version of ibm-driver-tools. It will then run the driver tool and determine whether or not to install the binary RPM included in the FixID into the currently running kernel. The flavor of the kernel distinguishes a kernel by certain capabilities. For example, you can find uniprocessor, multiprocessor, and extended memory kernel flavors. A kernel module must be built or provided for each flavor of kernel one wishes to run. If the driver tool determines that there is no driver already supplied by the OS vendor and that a version of the driver is compatible with the current kernel/flavor, is present in the FixID, it will install the device driver. By default, the driver tool will not install a new driver over a driver already provided by the OS vendor. However, one can override this behavior by manually passing options to the script. Additionally, there are options for targeting a kernel/flavor besides the currently running one. Also included in the FixID, are source RPMs for building device driver RPMs. Building binary RPMs will target the currently running kernel/flavor for 2.6 based OSs (i.e., RHEL4, RHEL5, SLES9 and SLES10). Inside the source RPM's .spec file are comments on how to target additional kernels. 2.4 based OSs require additional setup before being able to build binary RPMs (documentation included with the FixID). 4. How it all works The Linux kernel exports an interface (kernel application binary interface, or kABI) for device drivers to use to communicate with the kernel. If the interface changes, a newly recompiled version of the device driver will be necessary. In a typical security (and sometimes non-security) update, these interfaces do not change. The ibm-driver-tool scripts analyze whether a change has occurred and if it sees that one hasn't, it will generate a new RPM (using the old binary device drivers) specifically for the newer kernel and install it. The resulting binary can be found in the filesystem wherever the specific OS vendor's RPM directories exist (i.e., Red Hat uses /usr/src/redhat/RPMS and SuSE uses /usr/src/packages). The binary RPMs install their files into the '/extra' directory under the appropriate kernel module directory (i.e., /lib/modules/2.6.18-53.el5/extra). If the RPM is for a storage device driver, then the RPM will generate a new initrd (initial ramdisk) containing the new device driver. Uninstalling the RPM will generate a new initrd with old drivers (if present). 5. Naming conventions The name of the binary RPMs contain the following fields: kmod---- -..rpm NOTE: If no kernel flavor is present (e.g.: 2.6.18-53.el5), the rpm will not have field. An example RPM for RHEL5 might be named: 'kmod-qlgc-qla2xxx-xen-8.02.00.05.5.2-1.x86_64.rpm'. This RPM name can be decoded to reveal that the RPM contains the 8.02.00.05.5.2 version of the device driver for QLogic's qla2xxx cards compiled against the xen flavor of the 2.6.18-53.el5 kernel for the x86_64 architecture. And with no kernel flavor it will be (for 2.6.18-53.el5): 'kmod-qlgc-qla2xxx-8.02.00.05.5.2-1.x86_64.rpm'. 6. Typical usage 6.1 Installation To use IBM's driver tools, you should unpackage the FixID into it's own directory and run './install.sh --update'. This invokes the default behavior of installing the device driver if a compatible version (for the currently running kernel/flavor) is included in the FixID and the OS vendor does not already provide a version of the driver. If a compatible version is found in the FixID but the OS vendor already includes a version of the driver, the script will not install the device driver. The OS version can be overridden with an invocation of './install.sh --update --override'. 6.2 Upgrading / downgrading If you already have a device driver from another FixID installed, the scripts will perform version checking and stop if it detects that the currently installed version of the device driver is newer than what is in the FixID (i.e., you are trying to install an old FixID). This can be overcome by running './install.sh --update --force'. Another way to accomplish the same result is to use the '--force-if-overridden' argument. This will allow you to upgrade (or downgrade) only if the script detects that you've previously installed the driver from a FixID using the '--override' argument. Using '--force-if-overriden' preserves the default behavior of not overriding the device driver if it's included with the OS, but if the OS driver has already been overridden, then it will go ahead and install the device driver included in the FixID (assuming a kernel ABI compatible version of the device driver is included in the FixID). In order to use upgraded device driver, reboot the server. 6.3 Uninstallation After successfully installing a device driver using IBM's driver tools, there will be a corresponding entry in the RPM database. Querying the RPM database for 'kmod-qlgc-qla2xxx' can be accomplished with: 'rpm -qa | grep kmod-qlgc-qla2xxx'. This should output something similar to: 'kmod-qlgc-qla2xxx-xen-8.02.00.05.5.2-1'. To remove the device driver: 'rpm -e kmod-qlgc-qla2xxx-xen-8.02.00.05.5.2-1'. 7. IBM driver tool manpage install.sh NAME install.sh -- installs drivers contained in IBM's FixIDs SYNOPSIS install.sh --update [--force | --override | --force-if-overridden ] [--kernel kernelversion] [--flavor kernelflavor] install.sh --query [ --kernel kernelversion ] [ --flavor kernelflavor ] install.sh --requires install.sh --help install.sh --help-help DESCRIPTION install.sh --update mode determines the correct RPM provided in the FixID and installs it if the RPM is built for the targeted kernel. If a RPM is unavailable for the targeted kernel than it generates a RPM using the RPM built for the least previous kernel and installs it. Note the new RPM is generated and installed only if the Application Binary Interface (ABI) used by the driver is compatible with that provided by the target kernel. The behavior of the tool also depends on the availability of distribution supplied drivers in the kernel and on the use of some of the command line options. The following options can be used to tailor the behavior. By default the driver in the RPM is installed if the distro driver, if present (by a previous installation), is already overridden and any installed non-distro driver is older than this driver. This ensures that either the distro driver is used or the most recent non-distro driver is used. --override override the distro driver and installs this driver if any installed non-distro driver is older than this driver. This option ensures that the most recent non-distro-driver is used. --force installs the RPM containing the driver unconditionally. This option ensures that the non-distro driver is used. --force-if-overridden force-install the driver in the RPM only if the distro driver is already overridden. This option ensures that either the distro driver is used or this driver is used. --kernel Use this flag to specify a kernel other than the currently running one. This should be in the format of a 'uname -r'. --flavor Use this flag to specify a kernel flavor other than the currently running one. For uniprocessor kernels the flavor is 'default' instead of ''. For all other flavors, there is no translation necessary. --query returns the version of the driver already installed by the driver and the version of the driver that will be installed. Also it prints a message informing whether the driver is already installed by the distro, and if it is a newer or a older version of the driver compared to the one that will be installed. --update The IBM driver tools will not perform any driver installs unless '--update' is passed as an argument. --help describes all the modes and options. --help-help describes all of the modes and options, and reports all non-documented and non-supported options that should not be relied upon. --requires returns the all the components that the RPM depends on. NOTE: If no mode is specified the update mode is assumed. By default the current running kernel and flavor is the target. However --kernel option can be used to target a different kernel version and --flavor option can be used to target a different flavor. NOTE: The RPMs supplied in the FixID have the following behavior. A new IBM specific kernel initial ramdisk is created. The name of the new ramdisk should be the same as the kernel's initial ramdisk. If the FixID is used for the first time, then the old ramdisk is saved with '_QLFC.org' appended. Multiple runs of the script will keep overwriting the initial ramdisk and the earlier ramdisk is saved with '-_QLFC.bak' appended. Examples: The following will install for the specified kernel and flavor (assuming a newer version of the driver is not already installed for the target kernel/flavor combination): install.sh --kernel 2.6.18-53.el5 --flavor xen To install for the specified kernel on the currently running flavor (assuming a newer version of the driver is not already installed for the target kernel/flavor combination): install.sh --kernel 2.6.18-53.el5 To install for the currently running kernel for the specified flavor (assuming a newer version of the driver is not already installed for the target kernel/flavor combination): install.sh --flavor PAE To install for the current kernel and flavor regardless of the version currently installed if the kABI is compatible: install.sh --force RETURN CODES install.sh exits with 0 on success or non-zero if failure in regular operation (i.e. not using the --query option). install.sh with the --query option returns 0 if the version presently installed and the version in the FixID are the same, 1 if the version in the FixID is newer or there is no currently installed version of the driver, 2 if the version in the FixID is older than the currently installed driver. 4 : ABI FAILURE 5 : if the rpm for the corresponding kernel is not packaged and the user has indicated not to generate a new rpm. 6 : RPM IS CORRUPT 8 : generation of the new rpm failed (mostly because of unavailability of rpmbuild command) 9 : UNSUPPORTED DISTRO 10: UNDEFINED ARCHITECTURE 11: NO USABLE RPM EXISTS 12: RPM has been generated incorrectly. 8. Support IBM Support Web Site: http://www.pc.ibm.com/support For countries outside the US, start at http://www.ibm.com/ 9. Notices and trademarks This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Software Interoperability Coordinator, Department 49XA 3605 Highway 52 N Rochester, MN 55901 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: © (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear. IBM, eServer, System x, e-business logo and IntelliStation are trademarks of the International Business Machines Corporation in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.