IBM SUBSYSTEM DEVICE DRIVER 1.2.0 README FOR SUN TABLE OF CONTENTS 1.0 ABOUT THIS README 2.0 USER LICENSE AGREEMENT FOR IBM DEVICE DRIVERS 3.0 APPENDIX A 4.0 IBM SUBSYSTEM DEVICE DRIVER README 5.0 README.txt 6.0 DEFECTS CORRECTED 7.0 KNOWN PROBLEMS AND WORKAROUNDS 8.0 ADDITIONAL INFORMATION AND CORRECTIONS TO THE "Subsystem Device Driver Installation and User's Guide" publication 9.0 TRADEMARKS 1.0 ABOUT THIS README FILE Welcome to IBM Subsystem Device Driver 1.2.0. This README file contains the latest information about installing IBM Subsystem Device Driver 1.2.0. 2.0 USER LICENSE AGREEMENT FOR IBM DEVICE DRIVERS NOTICE: PLEASE READ THIS AGREEMENT CAREFULLY BEFORE USING THE PROGRAM AND DOCUMENTATION. IBM(R) WILL ONLY LICENSE THIS PROGRAM AND DOCUMENTATION TO YOU IF YOU FIRST ACCEPT THE TERMS OF THIS AGREEMENT. BY USING THE PROGRAM AND DOCUMENTATION, YOU AGREE TO ABIDE BY THESE TERMS AND APPLICABLE COPYRIGHT LAWS. IBM LIMITS YOUR ACCEPTANCE OF THE PROGRAM AND DOCUMENTATION TO THE TERMS OF THIS AGREEMENT. The Program and Documentation is owned by International Business Machines Corporation or one of its subsidiaries (IBM) or IBM suppliers, and is copyrighted and licensed, not sold. IBM does not transfer title to this Program and Documentation to you. The terms of this Agreement apply to any additional license copy of the Program or Documentation that IBM authorizes you to make. The term "Program" means the original program and all whole or partial copies of it, including portions merged with other programs. A Program consists of machine-readable instructions and related license materials. Under this Agreement,IBM provides you with a license to use the Program and Documentation only. 1. BACKGROUND / PURPOSE: IBM provides certain device drivers and Documentation under this Agreement. The device drivers and library support that IBM provides under this Agreement are in object code form only. Appendix A of this Agreement indicates the server platforms that are supported. IBM uses announcements to withdraw service for device drivers, feature codes, etc., on hardware and/or operating system platforms. IBM reserves the right to change the Programs or Documentation at any time without prior notice. 2. DEFINITIONS: Derivative Work is a work based on a preexisting work, including a compilation. A Derivative Work prepared without the authorization of the copyright owner of the preexisting work would constitute a copyright infringement. Documentation is the Program documentation that IBM provides to you as follows: IBM Subsystem Device Driver and README files. Object Code is machine-readable instructions in Object Code format. It is substantially in binary form and directly executable by a computer after suitable processing but without the intervening steps of compilation or assembly. Program is the IBM Subsystem Device Driver in Object Code form. 3. LICENSE GRANT: IBM grants you a revocable, nontransferable, nonexclusive, worldwide, paid-up copyright license to: 1.use the Program and Documentation solely on the platforms and solely with the applicable IBM devices described in Appendix A of this Agreement; and 2.maintain one copy of the Program for backup purposes only. Your license to the Programs and Documentation terminates when you no longer rightfully possess the IBM device described in Appendix A. This Agreement does not grant you any right or license to prepare Derivative Works of the Program and Documentation. Nothing in this Agreement grants either party any rights or licenses under any patents or patent applications regardless of whether use and/or execution of the software licensed herein may be construed to practice one or more patents. 4. RESPONSIBILITIES: You agree to use the Program and Documentation only with the IBM device described in Appendix A of this Agreement. You will not: 1.otherwise copy, display, transfer, adopt, modify or distribute in any form, the Program and Documentation, except as IBM expressly authorizes in the Documentation; 2.decompile, disassemble, reverse engineer, or in any way modify the Program or Documentation; and 3.sell, rent, lease, sublicense the Program or Documentation, unless explicitly permitted by law without the possibility of contractual waiver; and sublicense or assign the license for the Program and Documentation 5. CONFIDENTIAL INFORMATION: Any information which either party may disclose to the other party shall not be deemed to be confidential. If the parties require the exchange of confidential information, such exchange will be made under a separate written confidentiality agreement. 6. LIMITATION OF LIABILITY: IN NO EVENT SHALL IBM OR ITS SUPPLIERS BE LIABLE FOR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF DATA, LOST PROFITS, BUSINESS INTERRUPTION OR ANY SPECIAL, INCIDENTAL, INDIRECT, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY REMEDY. You acknowledge that circumstances may arise where, because of a default on IBM's part or other liability, you may be entitled to recover damages. Under any such circumstances, you agree that in each such instance, regardless of the basis on which you are entitled to claim damages, IBM shall be liable only up to an amount equal to five thousand U.S. dollars ($5,000). This limitation will not apply to claims relating to bodily injury (including death), and damage to real property and personal property. 7. TERMINATION: Termination for Cause. If either party fails to perform its obligations hereunder, then the other party may terminate this Agreement or the license granted hereunder for cause. Effect of Termination. The rights and licenses granted to you under this Agreement shall automatically terminate upon the termination of this Agreement. 8. REPRESENTATIONS AND WARRANTIES: THE PROGRAM AND DOCUMENTATION IS PROVIDED ON AN "AS IS" BASIS. IBM MAKES NO REPRESENTATION OR WARRANTY, EXPRESS OR IMPLIED, WITH RESPECT TO THE PROGRAM AND DOCUMENTATION. IBM DISCLAIMS THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. THE ENTIRE RISK ARISING OUT OF THE USE OR PERFORMANCE OF THE PROGRAM AND DOCUMENTATION REMAINS WITH YOU. 9. GENERAL PROVISIONS: Transfer. You may transfer possession of the program and its media and Documentation to another pay with the transfer of the IBM device described in Appendix A on which such Program is used with. If you do so, you must give the other party a copy of these terms and provide all user documentation to that party, and such party must first agree to such terms before it uses the Program and Documentation. Upon transfer of the Program and Documentation, you must destroy all your copies of the Program and Documentation. Severability. If any provision of this Agreement is found to be illegal or uneforceable, the remainder of this Agreement shall continue in full force and effect provided that the Agreement still effectuates the parties' original intent. Governing Law and Jury Trial Waiver. This Agreement shall be governed by the laws of the State of New York, excluding its conflict of law rules. Each party hereby agrees to waive its rights to a trial by jury. Modifications. No modification to this Agreement, nor any waiver of any rights, shall be effective unless agreed to in a writing that is executed by both parties, and the waiver of any breach or default of this Agreement shall not constitute a waiver of any other right or of any subsequent breach or default. Limitations on Legal Actions. Neither party will bring a legal action against the other more than two (2) years after the cause of action arose. Both parties will act in good faith to resolve disputes. Order of Precedence. In the event of a conflict in terms between this Agreement and another agreement, the terms of this Agreement shall take precedence and prevail over such other terms. Entire Agreement. This Agreement constitutes the entire and exclusive agreement between the parties with respect to this subject matter. All previous discussions and agreements with respect to this subject matter are superseded by this Agreement. 3.0 APPENDIX A This Appendix indicates: 1.which specific IBM devices the Program and Documentation are to be used with; IBM devices: IBM Enterprise Storage Server™ (ESS) 2.For what specific server platforms the Program and Documentation are to be used on and for what software requirements apply to the use of the Program and Documentation reference the ESS Open Systems Support Web page, located at: www.storage.ibm.com/hardsoft/products/ess/supserver.htm END OF USER LICENSE AGREEMENT FOR IBM DEVICE DRIVERS CONTINUING WITH THIS INSTALLATION CONSTITUTES YOUR ACCEPTANCE OF THE TERMS OF THE ABOVE 'USER LICENSE AGREEMENT FOR IBM DEVICE DRIVERS'. 4.0 THE IBM SUBSYSTEM DEVICE DRIVER README IBM Subsystem Device Driver for SUN Version 1 Release 2 Modification 0 Level 0 5.0 README.txt This README file contains last-minute product information for the Subsystem Device Driver 1.2.0. We strongly recommend that you print and review the contents of this README file and the Subsystem Device Driver Installation and User's Guide before installing the Subsystem Device Driver. The most current level of the documentation and support information can be found on the following Web site: www.ibm.com/storage/support/techsup/swtechsup.nsf/support/sddupdates 6.0 DEFECTS CORRECTED The following table lists the defects corrected in this release of Subsystem Device Driver: Table 1. Defects corrected in this release of Subsystem Device Driver ====================================================================== Related to Defect# Description ======================================================================= 52792 Uninstall of Subsystem Device Driver using pkgrm causes the loss of /etc/system on the system. This was attributed to the /tmp file being out of space and the Subsystem Device Driver used that directory as an intermediated work space in updating the /etc/system file. New logic is now used to check the zero byte condition. If it does occur, the Subsystem Device Driver will use other available filesystem to update the /ect/system file. 52549 The Sun host system was crashed after users unallocated the disks / Luns, and "format" was issued. This was caused by an un-initialized variable in the Subsystem Device Driver. The variable has been initialized in this fix. ======================================================================= Note: Defect #'s are for IBM internal reference use only. 7.0 KNOWN PROBLEMS AND WORKAROUNDS The following table lists the known problems discovered, and recommended workarounds in this release of Subsystem Device Driver: Table 2. Summary of known problems and recommended workarounds in this release of Subsystem Device Driver. ====================================================================== Related to Defect# Description ======================================================================= 53575 Patch 108968-02 causes the volume manager to hang in the middle of mounting the Subsystem Device Driver CD on a Sun server running Solaris 8. See "KNOWN PROBLEMS AND WORKAROUNDS - DETAILS SECTION" below, for the workaround procedure. ======================================================================= Note: Defect #'s are for IBM internal reference use only. 7.1 KNOWN PROBLEMS AND WORKAROUNDS - DETAILS SECTION. The following section provides additional updated and additional workaround information for the above related defects (as applicable). ====================================================================== Related to Defect# Details ====================================================================== 53575 Patch 108968-02 causes the volume manager to hang in the middle of mounting the Subsystem Device Driver CD on a Sun server running Solaris 8. Installing the Subsystem Device Driver CD on a Sun server running Solaris 8 patch 108968-02 -------------------------------------------------------------------- The patch 108968-02 causes the volume manager to hang in the middle of mounting the Subsystem Device Driver CD. We recommend that you upgrade Solaris 8.0 to the latest accumulative patches, 108528-08 and beyond. Or, use the following procedure as a workaround if you do not have the latest patches installed, and in the event that Subsystem Device Driver CD installation process fails when installing on a Sun server running Solaris 8 patch 108968-02. Perform the following steps: 1. Stop volume manager by typing this command: /etc/init.d/volmgt stop 2. Insert the CD in the CDROM 3. Manually mount ungtyping this command: mount -F hsfs -o ro /dev/dsk/cxtydzs0 /mnt (where cxtydzs0 is the special file for the CDROM in the intend server) 4. Install the package by typing either one of the following commands: For 32-bit applications, type: pkgadd -d /mnt/sun32bit IBMdpo For 64-bit applications, type: pkgadd -d /mnt/sun64bit IBMdpo 5. Unmount the CD by typing this command: umount -a /mnt 6. Remove the CD by typing this command: eject /dev/dsk/cxtydz 7. Restart the volume manager by typing this command: /etc/init.d/volmgt start ======================================================================= Note: Defect #'s are for IBM internal reference use only. 8.0 ADDITIONAL INFORMATION AND CORRECTIONS TO THE "Subsystem Device Driver Installation and User's Guide" The following table is a summary of any additional information and corrections to the "Subsystem Device Driver Installation and User's Guide" publication. Table 3. Summary of any additional information and corrections to the "Subsystem Device Driver Installation and User's Guide" publication. ====================================================================== Related to Defect# Description ======================================================================= 54901 Message, "Warning: Failed process interrupt for vpathdd0 due to down-rev nexus driver Pseudo0" See "ADDITIONAL INFORMATION AND CORRECTIONS TO THE "Subsystem Device Driver Installation and User's Guide" - DETAILS SECTION." below for details. 54753 Failback for Subsytem Device Driver on Solaris See "ADDITIONAL INFORMATION AND CORRECTIONS TO THE "Subsystem Device Driver Installation and User's Guide" - DETAILS SECTION." below for details. ======================================================================= Note: Defect #'s are for IBM internal reference use only. 8.1 ADDITIONAL INFORMATION AND CORRECTIONS TO THE "Subsystem Device Driver Installation and User's Guide" - DETAILS SECTION. The following section provides any detailed information and corrections to THE "Subsystem Device Driver Installation and User's Guide" publication. ====================================================================== Related to Defect# Details ======================================================================= 54901 Message, "Warning: Failed process interrupt for vpathdd0 due to down-rev nexus driver Pseudo0" Message, "Warning: Failed process interrupt for vpathdd0 due to down-rev nexus driver Pseudo0" -------------------------------------------------------------------- This message shows up during the installation and reboot time on Solaris 8 only. This message will not impact the normal Subsystem Device Driver installation and operation because the VPATHDD device driver does not require interrupt handling by the underlying PSEUDO nexus device driver. The VPATHDD device driver interrupts are the same as the underlying SCSI HBA interrupts, which are generated through the hardware bus, such as, the PCI and SBUS, and handled by the corresponding PCI or SBUS nexus device driver. Hence, it does not require any handling through PSEUDO nexus device driver. ====================================================================== Related to Defect# Details ======================================================================= 54901 Failback for Subsytem Device Driver on Solaris Failback for Subsytem Device Driver on Solaris: ---------------------------------------------- Raw Device Behavior ------------------- This section discusses the behavior when using the raw device or the block vpath device in a way such that it is not being used as a mounted file system. For example, by issuing a dd command directly to the char or block device. The Sun operating system will issue an OPEN to the device when the device is used. There are times when the operating system recognizes that the device is OPEN, and will not pass though further OPENS and CLOSES, until it recognizes the CLOSE as being the last CLOSE. Moreover, this operating system regards the block device and the character device as separate devices. It can also send multiple OPENS to devices that are already OPEN. Normal Usage usage of a disk ---------------------------- The normal usage of a disk would be to build a file system on the disk, and use the block device to mount a file system at boot time. This will cause an OPEN to be issued at mount time and then no more OPENS or CLOSES on the block device will occur until the file system is un-mounted, which would normally be at system shutdown. The file system will not pass through multiple OPENS and CLOSES on an OPEN file system device. Recovery on a file system within the vpath driver is based on an automated, but finite number of periodic retries, and after a certain point, the vpath driver will give up and wait for a manual recovery command to be issued. For example, by issuing the command, datapath set adapter nn online. When a path is lost for a long period, it can be inefficient to keep trying since some retries may take several seconds to time out, and no I/O can be performed during that time. The other way that recovery can happen is by performing OPENS and CLOSES. Performing an OPEN under the Subystem Device Driver will try to OPEN all paths to all underlying devices, irrespective of the state of the device. If the OPEN fails it will mark the path DEAD unless the path is in an OPEN state. Similarly a CLOSE that is the last CLOSE (no one else has the device OPEN) will set the path to a CLOSED state, irrespective of whether the device is DEAD or OPEN. Behaviors --------- 1. Character Only access. On a device that is being used for character I/O, such as Database Access, if OPENS are happening frequently, the path recovery will be quick after a path has become available, since the next OPEN issued will set the device to OPEN immediately. This then, depending on how long it is OPEN, and how much I/O occurs, does not necessarily go through the limited retry mechanism, but will typically, if there are frequent OPENs, the recovery will occur automatically and much quicker. Note: When a path is lost for a long period, it can be inefficient to keep trying since some retries may take several seconds to time out, and no I/O can be performed during that time. 2. Mounted File System Device (even the behavior of a permanently OPENED block device is affected by direct device access). Any command that uses the vpath device bypassing the file system, will issue an OPEN. The most common way is a command that sends an ioctl to the device such as, the Sun format command. This command issues an ioctl to the character device, which will cause the device to be OPENED. At this point, recovery can happen, even if the device was DEAD but it is now available, its status will be set to OPEN, and usage will start immediately, but with one exception; The exception is, when the device is a mounted file system, when it is already OPEN, and it is in the middle of an automatic recovery cycle. The recovery may have to wait up to 2000 selects on the good paths before it retries the other path. So running a command such as, the Sun format command can be used for recovery, instead of using the command, datapath set adapter nn online. ======================================================================= Note: Defect #'s are for IBM internal reference use only. 9.0 TRADEMARKS The following terms are trademarks of the International Business Machines Corporation in the United States, or other countries, or both: AIX Enterprise Storage Server IBM Netfinity RS/6000 Microsoft, Windows, Windows NT, and the Windows logo are registered trademarks of Microsoft Corporation. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others. (C) Copyright IBM Corporation 2000, 2001. All rights reserved.