IBM SSA RAID Adapter for PC Servers
               -----------------------------------
 
        OS/2 Device Drivers and Utilities - README.TXT
        ----------------------------------------------
 
This file contains information you need to install the IBM SSA RAID Adapter
for use with OS/2. Please also refer to the sections "Reported Problems
and/or workarounds" and "PC Server BIOS levels" for other important
information about this product.
 
This README file is divided into the following categories:
 - Before You Install the IBM SSA RAID Adapter.
   - Software Requirements.
   - Hardware Requirements.
 - Getting Help.
 - Installing the IBM SSA RAID Adapter.
 - Configurator Error codes.
 - Trademarks.

Before You Install the IBM SSA RAID Adapter
-------------------------------------------

PC Server BIOS Levels
---------------------
 
NOTE: It is recommended that you ensure that the Server you are using
      has the latest BIOS. These can be obtained from the follow sites:

      (919)-517-0001   :  IBM PC Company BBS Research Triangle Park, USA.
      ftp.pc.ibm.com   :  IBM PC Company anonymous ftp site.
      www.compaq.com   :  Compaq company web site.
      www.hp.com       :  Hewlett Packard company web site.
 
      At the time of writing, the tested levels are:
 
           PC Server 704 PCI/EISA, Flash BIOS 10     (06-26-97)
           PC Server 720 PCI/MCA,  Flash BIOS v1.09  (06-16-97)
           PC Server 520 PCI/EISA, Flash BIOS 16T3C  (07-15-96)
           PC Server 320 PCI/EISA, Flash BIOS 16T3B  (07-15-96)
           PC Server 330/325 PCI/EISA, Ship level at time of writing
 
           COMPAQ ProLiant 1500, COMPAQ System BIOS E12 (12/30/1996) 
           COMPAQ ProLiant 2500, COMPAQ System BIOS E24 (12/30/1996) 
           COMPAQ ProLiant 5000, COMPAQ System BIOS E16 (12/30/1996)
           COMPAQ ProLiant 6000, COMPAQ System BIOS E20 (05/16/1997) 

           HP NetServer LH Pro, Phoenix BIOS v 4.05.14PF Plug and Play (12/11/96) 
           HP NetServer LX Pro, AMIBIOS - American Megatrends V 1.00.4.CD0L 

Software Requirements
---------------------

 - IBM Operating System/2 (OS/2) WARP Server V3
 - IBM Operating System/2 (OS/2) WARP Server SMP

Hardware Requirements
---------------------

 - A supported PC Server platform which has a PCI bus (level 2.1).
 - 1 MB of fixed disk space above that required by OS/2.
 - .5 MB of memory above that required by OS/2.
 - 2-button mouse or other pointing device.
 - IBM SSA RAID Adapter, installed into a PCI slot of the personal
   computer.

Getting Help
------------

  Documentation
  Service and Technical Support
  Defect Reporting

Available Documentation
-----------------------
 
 - Installation and Users Guide       S32H-3816-xx
 - Maintenance Information Manual     S32H-3817-xx
 - Technical Reference Manual         SA33-3268-xx

Service and Technical Support
-----------------------------

We are ready to help you with your IBM SSA RAID Adapter questions. You can
contact us through one of the following:
 
  For Technical Support:

  - Please contact your supplier in the first instance
 
  - BBS, for latest files etc.
     o US: (919) 517-0001          (300 - 28.8K,  8-N-1)
     o UK: (0)1705-492831          (2.4K - 14.4K, 8-N-1)
     o Germany:  (0)6131-845070    (2.4K - 14.4K, 8-N-1)
 
  For Product Information:
    - WWW, http://www.storage.ibm.com/storage
 
Defect Reporting
----------------

Please report any defects to the supplier of your adapter.
 
Installing the operating system to SSA disks only from OS/2 media
-----------------------------------------------------------------

If you are installing your operating system onto an SSA disk then follow
the instructions in your SSA Installation and Users Guide to:

 - Boot from the DOS Configurator and Service Aids diskette in order to
   attach an SSA resource to your PC Server.

Before installing the OS/2 operating system, it is suggested that the SSA
device drivers be copied onto the second of the OS/2 installation diskettes.
 
You can install OS/2 without doing these modifications but the installation
process can be much slower.
 
The process of modifying the second installation diskette is as follows:
 
1) Edit the config.sys and add the statements:
 
   BASEDEV-ISSAPCI.ADD
   BASEDEV-ISSADSK.ADD
 
   just before the first BASEDEV- statement in the config.sys file. This
   causes the SSA device drivers to load first.
 
2) Copy ISSAPCI.ADD and ISSADSK.ADD from the OS/2 Device Driver and
   Utilities diskette onto the installation diskette.
 
   You will need approximately 196000 bytes of free space and depending on
   your system configuration you may be able to delete some of the
   following files in order to provide room for the SSA device drivers.

   IBM2FLPY.ADD   Supports disk drives on Microchannel computers.
   IBM2ADSK.ADD   Supports non-SCSI hard drives on Microchannel systems.
   IBM2SCSI.ADD   Supports SCSI hard drives on Microchannel system.
 
   Note: The three device drivers listed above can only be deleted from an
         installation diskette associated with a EISA/PCI PC Server. The
         MCA/PCI PC Server (e.g. PC Server 720) requires all of the above.
 
   PRINT02.SYS    Supports local printers on Microchannel systems.
   IBMIDECD.FLT   IDE connected CD.
 
   Also, depending on other vendor options which may be installed,
 
   SONY*.*
   TOSH*.*
   HIT*.*
   NEC*.*
   CHI*.*
   AHA152*.*
   AHA154*.*
   SBCD2.*
   LMS206.*
 
   Now follow the installation instructions which you will have received
   with your operating system.

IMPORTANT NOTE
--------------

   The ISSAPCI.ADD and the ISSADSK.ADD devices drivers may be copied to the
   root (\) directory during the install process. These two files should be
   moved (i.e. copied and deleted) to the \OS2 directory once installation
   of the Operating System has completed.

Installing the operating system to SSA disks only from SERVER GUIDE
-------------------------------------------------------------------

IBM Operating System/2 (OS/2) WARP Server SMP
------------------------------------------------

If you are installing your operating system onto an SSA disk then follow
the instructions in your SSA Installation and Users Guide to:

 - Boot from the DOS Configurator and Service Aids diskette in order to
   attach an SSA resource to your PC Server.

NOTE: Attach ONLY the devices which are to be the target for the
      installation.

During installation the system reboots several times. At the the reboot
which gives the error message:

    OS2KRNL is not valid

It is necessary to copy the version of OS2KRNL present in the root
directory of the D drive to the root directory of the C drive. In order to
do this, the attributes must be changed. Reboot the machine from a DOS
diskette with ATTRIB.EXE available on it and with the following command
line:

    attrib -h -r -s C:\OS2KRNL [ENTER]

Change the attributes. The OS2KRNL file can now be copied:

    copy D:\OS2KRNL C:\OS2KRNL [ENTER]

And the attributes reapplied:

    attrib +h +r +s C:\OS2KRNL [ENTER]

Rebooting the machine with the diskette removed will allow the installation
to complete normally.

IBM Operating System/2 (OS/2) WARP Server
--------------------------------------------

If you are installing your operating system onto an SSA disk then follow
the instructions in your SSA Installation and Users Guide to:

 - Boot from the DOS Configurator and Service Aids diskette in order to
   attach an SSA resource to your PC Server.

NOTE: Attach ONLY the devices which are to be the target for the
      installation.

During the installation the message "LOADING SYSTEM FILES PLEASE WAIT" is
displayed. At this point the machine and disk activity stop. When this
happens reboot the machine from a bootable DOS diskette which has a text
editor available on it. Edit the OS2INST.RSP file on the D drive and insert
above the line:

    ConfigSysLine-BASEDEV
                                                                                
The two lines:

    ConfigSysLine-BASEDEV-ISSAPCI.ADD
    ConfigSysLine-BASEDEV-ISSADSK.ADD

Copy the IBM SSA Device drivers from the driver diskette into the OS2
directory on C.

    copy A:\ISSAPCI.ADD C:\OS2 [ENTER]
    copy A:\ISSADSK.ADD C:\OS2 [ENTER]

Rebooting the machine with the diskette removed will allow the installation
to complete normally.

Installing IBM SSA RAID Adapter Device Driver and Utilities for OS/2
--------------------------------------------------------------------
 
The software required to support the IBM SSA RAID Adapter for your OS/2
operating system can be simply installed by inserting the SSA RAID Adapter,
OS/2 Device Drivers and Utilities, diskette into your diskette drive,
typing the command:
 
    a:install [ENTER]
 
The install program will copy the device drivers to the appropriate
directory and modify your system's CONFIG.SYS file to ensure that these
device drivers will be correctly started at the next, and subsequent,
system initialisation time.
 
The install program will also copy the utility software into a directory
(default of c:\issa) and will create an IBM SSA RAID folder on your
desktop, within which you will find the three utility programs of:

   SSA Configurator
   SSA Event Logger
   SSA Topology Display
 
A shadow of the SSA Event Logger will also be placed in the system's
startup folder so that it will automatically be invoked whenever your
system is initialised.

NOTE: The Install program automatically updates your config.sys file.
      In the unlikely event that you have manually amended the entry for
      "basedev-issapci" or "basedev-issadsk" it is possible that a
      duplicate entry will be made. Such duplicate entries can cause the
      operating system to hang and if you have amended the original lines
      please ensure that the config.sys file created as a result of the
      installation process only contains one reference to the IBM SSA RAID
      Adapter device drivers.

      On early (beta) releases of the device drivers, the device drivers
      were named "IPNDD.ADD" and "PCIKNL.ADD". Please ensure that all
      reference to these names are deleted from the config.sys file.

Manual Install
--------------

If the Install Program does not work on your system, or it is necessary to
manipulate the files manually, then the following notes will be of use.
 
The files on the diskette are in a packed format, and the EPFIUPK2.EXE
program can be used to unpack them.
 
The EPFIUPK2 program will create the correct file names.
 
To copy the files manually (replicate the action of the install program),
follow the steps provided below:
 
1) Create a directory in which to store the IBM SSA Adapter software. If
   'ISSA' were to be used, then type:

   mkdir ISSA [ENTER]
 
2) Copy this file onto the new directory by issuing the commands:
 
   copy a:readme.txt \issa\readme.txt [ENTER]
 
3) Now unpack the SSA device drivers and utility software by issuing the
   commands:
 
   cd ISSA [Enter]
   copy a:*.ex_ . [Enter]
   copy a:*.nl_ . [Enter]
   copy a:*.ic_ . [Enter]
   copy a:*.tx_ . [Enter]
   copy a:epfiupk2.exe . [Enter]
   epfiupk2 issacfg.ex_ [Enter]
   epfiupk2 issaelog.ex_ [Enter]
   epfiupk2 issatopo.ex_ [Enter]
   epfiupk2 cfgmenu.nl_ [Enter]
   epfiupk2 cfghelp.nl_ [Enter]
   epfiupk2 evnlog.nl_ [Enter]
   epfiupk2 evncntlf.tx_ [Enter]
   del *.ex_ [Enter]
   del *.nl_ [Enter]
   del *.tx_ [Enter]
   del epfiupk2.exe [Enter]

4) Copy the device drivers to the \OS2 directory by issuing the commands:
 
   copy a:ISSAPCI.ADD \OS2 [Enter]
   copy a:ISSADSK.ADD \OS2 [Enter]
 
5) Edit the CONFIG.SYS file and, at the bottom of the file, add the lines:
 
   BASEDEV-ISSAPCI.ADD
   BASEDEV-ISSADSK.ADD
 
   NOTE: If you have previously installed an older version of the IBM SSA
         RAID Adapter card, the device drivers may have been named
         "PCIKNL.ADD" and "IPNDD.ADD". Please delete any reference to these
         from the CONFIG.SYS file.
 
6) Now create a method of accessing the SSA utility software. One method is
   to create program objects within a new folder. The steps required to do
   this are outlined below:

   a) Drag a Folder object from the OS/2 System Templates folder onto your
      desktop. Open the settings for this new folder and in "General"
      change the folder name to IBM SSA RAID, and you can find an SSA icon
      by searching on the \ISSA path.
 
   b) Drag a Program object from the OS/2 System Templates folder put this
      into the new (SSA) Folder. A "Program Settings" prompt will be
      provided. The Path and file name: should be entered as:
 
        c:\ISSA\issacfg.exe    (where c: and \ISSA must match the drive and
                               directory in which you have expanded the SSA
                               software)
 
      No Parameters are required but the Working directory should be entered as:
 
        C:\ISSA
 
      Under the General section, change the Title: to read SSA Configurator
      and, if required, choose the SSA icon by finding the ICON on the
      SSA path.
 
   c) Drag a Program object from the OS/2 System Templates folder put this
      into the new (SSA) Folder.
 
      A "Program Settings" prompt will be provided. The Path and file name
      should be entered as:
 
        c:\ISSA\issatopo.exe   (where c: and \ISSA must match the drive and
                               directory in which you have expanded the SSA
                               software)
 
      A single parameter is required - this is the PCI slot number in which
      the SSA adapter has been placed. The Working directory should be
      entered as:

        C:\ISSA
 
      Under the General section, change the Title: to read SSA Topology and,
      if required, choose the SSA icon by Finding the ICON on the SSA path.
 
   d) Drag a Program object from the OS/2 System Templates folder put this
      into the new (SSA) Folder.
 
      A "Program Settings" prompt will be provided. The Path and file name:
      should be entered as:
 
        c:\ISSA\issaelog.exe   (where c: and \ISSA must match the drive and
                               directory in which you have expanded the SSA
                               software)
 
      No Parameters are required but the Working directory should be entered
      as:

        C:\ISSA
 
      Under the General section, change the Title: to read SSA Event Logger
      and, if required, choose the SSA icon by Finding the ICON on the
      SSA path.
 
7) Now create a shadow of the SSA Event Logger in the startup folder, such
   that the Event Logger will be started each time your system is
   initialised.
 
   To do this, open the startup folder (usually found within the OS/2
   System folder and drag a copy  (Ctrl+Right Hand Mouse Button) of the SSA
   Event Logger object from the IBM SSA RAID folder to the Startup Folder.
 
For information, the following files will have been expanded.
 
SSA Device Drivers
 
   ISSAPCI.ADD
   ISSADSK.ADD
 
Support software
 
   ISSACFG.EXE   -- The configuration tool
     CFGMENU.NLS  -  )
     CFGHELP.NLS  -  )  National Language Support (UK English)
 
   ISSAELOG.EXE   -- The SSA Event Logger, with pop-up menu
                     for error notification
     EVNCNTLF.TXT -     SSA Event Logger control file
     EVNLOG.NLS   -     National Language Support (UK English)
 
   ISSATOPO.EXE  -- SSA Topology Generation

Setting up the Topology Display Program
---------------------------------------
 
The topology display program uses the "Node Number" assigned by the SSA
Device Driver software to identify which SSA Adapter's resources are to be
displayed.
 
You could create a different Topology Display object for each adapter
installed in your system.
 
The easiest way to determine the node number(s) is to run the SSA
Configurator program and, from the SSA Adapter menu make note of the node
number(s) assigned to each adapter.
 
Alter the settings for the ISSATOPO program and set the PARAMETERS value
to a single node number obtained above.
 
If you have more than one adapter installed then create other program
objects in the IBM SSA RAID folder and, for each adapter installed, set the
PARAMETERS value to an alternative node number.

NOTE: For convenience of use, you may also like to alter the name of the
      program object to indicate which adapter's SSA topology is being
      displayed.

Using SSA for Operating System Boot
-----------------------------------
 
If your primary boot device is a logical SSA drive, then the SSA adapter
must be installed into a PCI slot with a lower number than that in which
any SCSI adapters are installed.
 
You should also edit the config.sys file to ensure that the SSA device
drivers (ISSAPCI.ADD and ISSADSK.ADD) are loaded before any SCSI device
drivers.

Reported problems and/or workarounds
------------------------------------
 
1) Isolated instances have been seen when a 520 server, will not boot first
   time from an operating system installed on an SSA DRIVE. The temporary
   solution is to reboot the PC Server.

2) It has been observed that, if a fixed disk drive fails (or an array goes
   offline, due to the failure of more than 1 member), OS/2 can "hang".
   Under normal circumstances an error message such as "The x: drive is not
   ready" will be generated by the Operating System.
   The rarer "hang" condition is not related to whether or not your SSA
   RAID Adapter is installed - it appears to be related to the Operating
   Systems inability, in some circumstances, to continue in the event of
   one of its fixed drives failing due to a hardware fault.
 
3) If you wish to create a RAID array you should ensure that all of the
   disks you elect to use as array members are the same capacity.

   NOTE: The smallest capacity of an array member is used when determining
         the size of the array.

Adapter Firmware Download  -  ISSAADLD.EXE
-------------------------

What it does
------------

ISSAADLD downloads an adapter microcode image to a specific SSA adapter,
or to all SSA adapters of the correct type it can find.

  usage: issaadld [-n node] [-a] [-Q] microcode
  flags: -n node   identify adapter by node number (default all adapters)
         -a        microcode is in AIF format (default is customer package)
         -Q        quiet mode (default is verbose)
         microcode input adapter microcode image file

The adapter microcode image file is identified by the subscript. These are:

xxxxxxxx.L03   :   image file for 512K adapters
xxxxxxxx.L11   :   image file for 1M adapters

The adapter download program checks the "Loadable microcode field" in the
adapter VPD in order that the wrong image is not inadvertently loaded to the
card. Care should be taken if renaming the files that the subscript is not
altered.

NOTE: Versions of the ISSAADLD program dated prior to that of this installation
      should NOT be used. This program was intended to service the 512K adapter
      only.

Examples
--------

To download a particular adapter microcode image (LD960701.L03, for
instance) to all 512K SSA adapters:

    issaadld LD960701.L03

To download just to the 1M SSA adapter which is 'Node 13':-

    issaadld -n 13 LD960701.L11

Important
---------

Do NOT download whilst disks are performing I/O. All open occurrences of the
SSA Configurator should also be closed, prior to performing the download.

Only use this utility program when instructed to do so by your service
representative since downloading incorrect images, for example, could have
a detrimental effect on your SSA Subsystem.

Errors may be generated in SSA Event Log. These can be ignored and are 
a result of adapter reset which is necessary to initialise the new microcode.

DASD Microcode Download - ISSADDLD.EXE
--------------------------------------
 
ISSADDLD downloads a disk microcode image to a specific disk, or to all
disks on a given SSA Adapter, or to all disks on all SSA Adapters.
 
  usage: issaddld [-a node] [-u uid] [-v vendor] [-f] [-q] microcode
 
  flags: -a node     identify adapter by node number (default all adapters)
         -u serial   15 character full serial number (default all disks)
         -v vendor   identify drive vendor (default is IBM)
         -f          force download (default is to upgrade)
         -q          quiet mode (default is verbose)
         microcode   input disk microcode image file
 
Examples
--------
 
To download a new IBM DFHC microcode image (for instance, DFHC7968.DL)
to all the disks on all the adapters
 
  issaddld DFHC7968.DL
 
To update all the DFHC disks on the adapter referred to as node 13:-
 
  issaddld -a 13 DFHC7968.DL
 
Important
---------
 
Do not download to disks whilst they are performing I/O.
 
Only use this utility program when instructed to do so by your service
representative since downloading incorrect images, for example, could have
a detrimental effect on your SSA Subsystem.

Errors may be generated in SSA Event Log. These can be ignored and are 
a result of adapter reset which is necessary to initialise the new microcode.

SSA Configurator Error Messages
-------------------------------
 
The Configurator does not currently display all error codes it in a
meaningful textual fashion. The error codes include:

0xfffd : General non-specific failure return code.
0xfffc : Hardware error.
0xfff8 : Illegal request.
0xfff0 : Not in table. Can't find disk with given serial number.
0xffe2 : Not yet implemented.
0xffef : Disk is currently offline.
0xffe0 : Not found.
0xfe1e : Array is broken or degraded. Some operations require a
         non-degraded array.
0xfe1a : NVRAM error. Its probably full with dormant entries. You could go
         and delete a few and then retry.
0xfe17 : Bad component exchange candidate.
0xfe18 : Array is broken. Some operations require a non-broken array.
0xfe13 : Bad new component serial number. New component is not suitable
         for component exchange.
0xfe11 : Bad disk serial number. Perhaps the disk went offline.
0xfe0c : Bad serial number. Perhaps there is already an array with this
         name.
0xff3a : Can't delete in-use resource. You can only delete dormant NVRAM
         entries.
0xff39 : Operation is not applicable for resource type. Perhaps you're
         trying to do a disk type of operation to an NVRAM entry
         (you can only list and delete these).
0xff38 : NVRAM is defective. The only sensible option here is to replace
         the module.

Trademarks and Notices
----------------------

The following terms are trademarks of the IBM Corporation in the
United States or other countries or both:

IBM, OS/2

Microsoft and Windows are trademarks or registered trademarks of
Microsoft Corporation.

Novell Netware is a trademark or registered trademark of Novell Inc.

Other company, product, and service names may be trademarks or service
marks of others.

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.

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