SYMBIOS I2O 53C8XX SCSI HDM  Version 1.03.00


************************************Introduction********************************  

The Symbios I2O 8xx SCSI HDM is a Hardware Device Module (HDM) as defined 
by the Intelligent I/O (I2O) Architecture Specification. The I2O Specification 
splits device drivers into two components. An Operating System Module (OSM) 
runs on the host CPU and contains code specific to an operating system. The 
HDM runs in an intelligent IO processor (IOP) and contains code specific to 
the hardware (such as the SYM53C8XX chips in our case). A generic message 
passing protocol is used to communicate between the OSM and HDM. This HDM is 
compliant with the I2O Specification version 1.5. It supports Utility, DDM, 
Host Bus Adapter, SCSI Peripheral, and Block Storage Class messages, with some 
exceptions as described in the "Release Restrictions" section below.

The HDM is distributed in four different formats to meet the needs of various 
types of OEMs. The choices are:

1.  Checked vs. Free build 
    
    The checked build contains print statements and additional error checking. 
    It is to be used with a checked version of IxWorks during system development 
    and debug. It provides lots of status and error messages to the Tornado  
    shell. It should only be used during development and debugging. The free 
    build does not have the additional code in the checked build, so it is 
    smaller and faster.  Symbios strongly recommends using the free build 
    when I2O systems are integrated.

2.  .o format vs. .ddm format 

    The .o object format is the format that has been used in the past, but will 
    be phased out with time. The .ddm format is the official format specified 
    by the I2O Specification for HDMs. 

    The .ddm format is the same as the .o format, with a module header appended 
    to the .o file.  If you are using the .o format, then you need to call the 
    setup routine from the Tornado shell by adding the line "Sym8xxSetup()" 
    after loading the .o and before the runExec line.  Please refer to the 
    "Sample Start Scripts" to see how the setup routine is used. 

The variations of these two choices give four possible formats:

1.  Sym8xx.o:    Free build, .o format
2.  Sym8xxC.o:   Checked build, .o format
3.  Sym8xx.ddm:  Free build, .ddm format
4.  Sym8xxC.ddm: Checked build, .ddm format


*  *  *  *  *  *  *  *  *  *  New Features *  *  *  *  *  *  *  *  *  *  *

o  Put in a workaround for IxWorks Build 5 that left the upper 32 bits of 
   a 64-bit address as 0xFFFFFFFF instead of 0x00000000 
o  Added code to do an EventNotify Reply when a drive or adapter is 
   removed, if the OSM or ISM registers for this functionality. This is the 
   basis for adapter and hard drive hot plug.
o  Enabled scan of all LUNs on the initial scan so multi-LUN devices will 
   be seen on the initial scan instead of requiring a rescan 
o  Removed recognition for the SYM53C810, SYM53C810A, SYM53C860, and 
   SYM53C825 SCSI processors. The HDM now only supports the SYM53C825A, 
   SYM53C875, SYM53C875E, SYM53C895, and SYM53C876. This was done to take 
   advantage of new features only found on these chips.
o  Provided names for all objects 
o  Added a gross timer to recover from a hung bus 
o  Coded the DdmAdapterRelease message 
o  Made performance improvements with new HW layer firmware 
o  Added support for hard drive hot swap 
o  Added code to blink a bus activity LED connected to GPIO0 
o  Added support for the 53C875E
o  Added support for the write through cache flag for a BSA write 
o  Modified the event registration for scsi_smart so devices that do not 
   support smart are not modified.  The OSM can compare the request 
   event mask to the modified mask to determine if the feature is 
   supported.
o  Added code to recognize an enclosure backplane processor (such as 
   a SAF-TE processor) as a SCSI peripheral. 


*  *  *  *  Problems Corrected/Restrictions Lifted in This Release  *  *  *  *  
 
o  Fixed the abort code and bus device reset code.
o  Fixed SCSI class disconnect and queue tag flag mismatch.
o  Changed the owner IDs for many objects from the DDM device ID to the adapter 
   or peripheral ID to allow the IRTOS to automatically destroy the object 
   hierarchy for hot plug.
o  Changed the bus scan code so the device doesn't keep looking for LUNs if 
   it receives a selection timeout on LUN 0.
o  Fixed an error that caused the device to receive a bus reset during the 
   initial bus scan.
o  Fixed a problem with uninitialized CDB bytes causing a drive to return an 
   illegal byte in CDB error.
o  Fixed a problem with devices that return large amounts of sense data.
o  Fixed a problem with the BSADeviceReset command.
o  Fixed a problem with Cache Flush commands
o  We now wait until the drive is spun up to get its serial number, since 
   some drives were returning invalid serial numbers.
o  Changed the organization ID in the LCT of the DDM TID from Symbios' ID to 0.
o  Removed the config dialog request flag from the LCT entry of the DDM TID.
o  Changed the owner TID field of the DDM TID from 0 to 0xFFF (unclaimed).
o  When registering a TID if the TID the device wants is invalid, it asks for 
   a new one instead of generating an error.
o  i2oDdmCreate() was being called with the second parameter as the MPB 
   version, instead of the I2O spec version. 
o  For the DDM TID, lctInfo.Class.OrganizationID was set to our PCI vendor ID 
   instead of our I2O ID.  
o  The BSInfo.MediaBlockSize was not being filled in.
o  The BSInfo.MediaCapacity was not being filled in.
o  The SCSI LUN was not being filled into the CDB for an Inquiry command to 
   support SCSI-1 devices that don't look for it in the Identify message.
o  Fixed a problem of older drives that didn't support the auto-reassign 
   mode pages being rejected.
o  Fixed SCSI class support so other device types besides disk drives are now 
   given SCSI TIDs. This may allow tapes and CDROMs to work through SCSI class.
o  Fixed the drive hot plug code so drives are correctly unregistered when they 
   are removed and registered when added.
o  Detailed Status codes were not set for a data underrun.
o  Fixed the code that limits the SCSI bus scans by acting on the fields in 
   the adapter parameter group.


**************************** Sample Start Scripts *****************************   

Here are two sample start scripts which show the combinations of the free vs. 
checked build and .ddm vs. .o file formats.


*  *  *  *  *  Sample Start Script for Free Build of Sym8xx.ddm  *  *  *  *  *   

====================================================
# for single-function PCI devices

ixLd<//path where the driver is located\\Sym8xx.ddm
runExec 0
=====================================================

Note: The iopPciSecIntSet needs to be used with  multi-
      function PCI devices are used, such as the SYM53C876 
      (dual channel SCSI chip).  Please refer to the 
      IxWorks documentation from Wind River Systems and 
      the example below for more details.


*  *  *  *  *  Sample Start Script for Checked Build of Sym8xxC.o  *  *  *  *  *   

=====================================================
# for multi-function PCI devices
_iopPciSecIntSet(0,0,3,0,0)
_iopPciSecIntSet(1,1,2,0,0)
_iopPciSecIntSet(2,2,1,0,0)
_iopPciSecIntSet(3,3,0,0,0)
# or greater

ld<//path where the driver is located\\Sym8xxC.o 
Sym8xxDebugLevel=5 
#The debug level can be from 0 (least information) to 9 (most information). 
#The default is level 0, but level 5 is best for most people.  Level 7 is good 
#for finding the cause of an error. Debug level 9 produces too much output 
#to generally be useful.  A higher debug level decreases performance.  Debug 
#information prints on the Tornado shell screen.

Sym8xxSetup()
runExec 0
=====================================================

Note: The Sym8xxSetup is used with the .o file.


*   *   *   Startup Variable Parameters for Debugging the HDM  *   *   * 

These parameters may be included in the start script for the HDM 
to provide additional debugging information.  They can only be 
used with the checked build.  If you do not enter a value with the 
parameter, the default will be used. These parameters are exclusive 
to the Symbios 53C8XX SCSI HDM, and are case sensitive. Additional 
parameters may be available through other ISMs and through the IRTOS; 
consult those vendors for information.

UseTimer  This variable enables timeouts on all I/Os.  The value is in 
          seconds.  The default value is 0, which means no timeout 
          is used.  The minimum value is 3 seconds.  The 
          maximum is 4,294,967,295.
LimitAdpSyncPeriodNs	This sets the maximum transfer time period that 
          the adapter will negotiate.  If this is set to 0 (default), 
          the adapter will negotiate for the maximum speed possible.  If 
          it is set to 50, the adapter will negotiate Ultra SCSI 
          (20 MegaTransfers/sec).  If it is set to 200, the adapter will 
          negotiate SCSI-1 (5 MegaTransfers/sec).
ZeroMPB  If this is set to a non-zero value before the OSM is started, 
         the nonvolatile memory will be cleared.  This variable defaults 
         to zero.
GrossTimerEnabled  Enables the gross timer for detecting bus hang conditions.  
         If it is set to zero, the timer is disabled.  Non-zero (default) 
         will enable this function.


*************************** Release Restrictions ******************************* 
 
o  This release does not support the power management messages defined for 
   Block Storage Class.
o  The release does not support the BSA media commands required to support 
   removable media drives.
o  This release does not support all of the DDM class messages defined in 
   section 5.3.1 of the I2O Specification.
o  This HDM may not function properly if any legacy Symbios SCSI drivers 
   (SDMS) are present in the system.  This is only a problem if the IOP 
   configures the SYM53C8XX device as "public" instead of "private". When the 
   adapter is private, the host system BIOS and OS cannot see the adapter so 
   there will be no conflict.  The SDMS drivers are embedded in some operating 
   systems and load automatically when the OS is installed, so you may have to 
   manually unload or delete the files before using the HDM.  Please refer to 
   the Symbios SDMS User's Guide for more information on how to determine 
   whether the SDMS drivers are loaded, and how to remove them from your system.


*  *  *  *  *  *  *  *  *  Hardware Requirements  *  *  *  *  *  *  *  *  *  *  

o  This version of the HDM has been compiled for the Intel i960RP and RD
   processors.
o  This version of the HDM only supports the Symbios SYM53C875, SYM53C85E, 
   SYM53C876 and SYM53C895 SCSI IO Processors.


*  *  *  *  *  *  *  *  *  *  Software Requirements  *  *  *  *  *  *  *  *  *  * 
 
o  An OSM is required for the operating system you choose to run. The versions 
   of OSMs that this release of the HDM has been tested with are: 

   1. Windows NT Block Storage OSM, running under Windows NT Server or
      Workstation version 4.0  
      Windows NT         v.  4.0_SP 3  11/21/1997
      Block Storage OSM	 v.  19        02/25/1997


   2.Novell NetWare Block Storage OSM, running under Novell NetWare version 4.11 
      NetWare            v.  4.11       06/01/1995
      Block Storage OSM  v.  0.12f      12/17/1997
      Message Layer      v.  0.12f      12/17/1997
      Transport Layer    v.  0.12f      12/17/1997
      NBI                v.  1.44       07/02/1996
      MSM                v.  3.17       07/01/1996


   3. SCO UnixWare Block Storage OSM, running under SCO UnixWare Enterprise and
      Personal Edition version 2.1. 
      SCO UnixWare             v. 2.11         03/13/1997
      SCSI Class OSM           v. 0.00.01.01   08/01/1997
      Message/Transport Layer  v. 0.00.01.00   07/22/1997
      SDMS 4 UnixWare driver   v. 4.02.03      11/10/1997

      Note: Symbios performs continuous testing and integration to 
            remain compatible with the latest releases of all supported 
            operating systems. This list only contains those OS versions 
            that are completely tested.

o  An IRTOS compliant with Chapter 5 of the I2O Specification is required to 
   run the HDM. At this time the only one that exists is IxWorks from Wind River
   Systems. This version of the HDM has been tested under IxWorks build 5. 
   Preliminary testing has been performed under IxWorks build 6 with no known
   issues.


****************************** Troubleshooting *********************************

Problem:  The second channel of the SYM22802 may not seen.  
Workaround:  This is fixed in build 6 of IxWorks.

Problem:  Under UnixWare unexpected disconnects during data phase may not 
          recover properly, resulting in an IOP hang.
Workaround:  None

Problem:  Under Windows NT IOPs configured with more than two host adapters 
          may not operate properly.
Workaround:  None

Problem:  Under UnixWare IOPs configured with more than three host adapters 
          may not operate properly.
Workaround:  None

Problem:  Under NetWare IOPs configured with more than four host adapters 
          may not operate properly.
Workaround:  None


*  *  *  *  *  *  *  *  Shell Debugging Variables  *  *  *  *  *  *  *  *  *  *

The variables described in this section are Tornado shell command line variables 
that can be used to debug the Symbios SYM8XXHDM while the IOP is running.  These 
variables can only be used with the checked build.  They are exclusive to the 
Symbios SYM53C8XX SCSI HDM and are case sensitive.  Enter the variable at the 
Tornado shell command line, and wait for a returned value.  Additional variables 
may be available through other ISMs and through the IRTOS; consult those vendors 
for more information.

ReqID	This variable is read only.  It displays the number of block storage 
        read and write commands, as well as the number of internally generated 
        commands.
OutStanding1, OutStanding2  The number of commands currently outstanding for 
        that adapter.  OutStanding1 refers to the first adapter, while 
        OutStanding2 refers to the second adapter.  The HDM does not keep 
        track of more than two adapters.
BigOutstanding1, 2  This is the largest number of I/Os that have been queued 
        during this session for the respective adapter.  The maximum value 
        is 255.
 

