freebsd-nq/sys/dev/sym/README.sym

/*
 *  Device driver optimized for the Symbios/LSI 53C896/53C895A/53C1010 
 *  PCI-SCSI controllers.
 *
 *  Copyright (C) 1999  Gerard Roudier <groudier@club-internet.fr>
 *
 *  This driver also supports the following Symbios/LSI PCI-SCSI chips:
 *	53C810A, 53C825A, 53C860, 53C875, 53C876, 53C885, 53C895.
 *
 *  but does not support earlier chips as the following ones:
 *	53C810, 53C815, 53C825.
 *  
 *  This driver for FreeBSD-CAM is derived from the Linux sym53c8xx driver.
 *  Copyright (C) 1998-1999  Gerard Roudier
 *
 *  The sym53c8xx driver is derived from the ncr53c8xx driver that had been 
 *  a port of the FreeBSD ncr driver to Linux-1.2.13.
 *
 *  The original ncr driver has been written for 386bsd and FreeBSD by
 *          Wolfgang Stanglmeier        <wolf@cologne.de>
 *          Stefan Esser                <se@mi.Uni-Koeln.de>
 *  Copyright (C) 1994  Wolfgang Stanglmeier
 *
 *  The initialisation code, and part of the code that addresses 
 *  FreeBSD-CAM services is based on the aic7xxx driver for FreeBSD-CAM 
 *  written by Justin T. Gibbs.
 *
 *  Other major contributions:
 *
 *  NVRAM detection and reading.
 *  Copyright (C) 1997 Richard Waltham <dormouse@farsrobt.demon.co.uk>
 *
 *-----------------------------------------------------------------------------
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

Status:
   BETA-RELEASE
   This driver is currently developped under the following O/S:
         FreeBSD 4.0 SNAPSHOT July 5th 1999
         FreeBSD 4.0 current  October 1999
   Starting with version 0.9.0, the driver contains conditionnal code 
   for using pre-4.0 BUS stuff for PCI. I have successfully tested driver 
   version 0.9.0 under:
         FreeBSD 3.2 RELEASE
         FreeBSD 3.3 RELEASE

Latest revision:
   sym-0.10.0-19991111
   Files to download:
      SYM-0.9.0-19991024.tar.gz
      PATCH-SYM-0.10.0-19991111.tar.gz

Supported SCSI features:
  - Initiator mode
  - Wide 16 SCSI BUS
  - FAST10 up to FAST80-DT synchronous data transfers (1)
    (depends on controller capabilities)
  - 64 luns per target
  - 256 tags per lun
  - MDP (2)
  - BUS DEVICE RESET message
  - ABORT, ABORT TAG message (2)

Supported generic chip features:
  - On chip RAM
  - PCI optimized transactions.

Supported features of 896/895A/1010:
  - Full SCRIPTS in on-board RAM (8K)
  - Phase mismatch handling from SCRIPTS.

Others:
  - SYMBIOS NVRAM layout using 24c16 EEPROM
  - TEKRAM  NVRAM layout using 24c16 EEPROM (2)
  - TEKRAM  NVRAM layout using 93c46 EEPROM (2)
  - Transfer residuals
  - 0(1) for both SCRIPTS and C code, allowing 
    100% scalability.

Notes:
(1) Only supported by the LSI53C1010 and not yet 
    tested due to lack of C1010 based controller.
(2) Not yet reported. May not work as expected.
   
Files:
  README.sym		this file
  sym_conf.h		driver configuration
  sym_defs.h		driver definitions
  sym_hipd.c		driver code
  sym_sys.patch		kernel patch for FreeBSD 4
  sym_sys_3.patch	kernel patch for FreeBSD 3

These patches apply a change to the ncr.c driver that forces it to 
ignore SYM53C8XX chips that support LOAD/STORE. These devices will 
be attached by the sym_hipd.c driver.

Installation:
  1) Untar SYM-0.9.0-19991024.tar.gz
  2) Copy README.sym, sym_conf.h, sym_defs.h and sym_hipd.c to 
     /usr/src/sys/pci/
  3) Change to /usr/src/sys/ directory
  4) If FreeBSD-4, apply the unified patch sym_sys.patch
         (patch -p0 <sym_sys.patch)
     Otherwise,
     If FreeBSD-3, apply the unified patch sym_sys_3.patch
         (patch -p0 <sym_sys_3.patch)
     Otherwise, leave here. ;)
  5) Change to /usr/src/sys/pci directory
  6) Update to SYM-0.10.0-19991111
     gzip -d <PATCH-SYM-0.10.0-19991111.gz | patch -p0
  7) Add sym0 to your kernel configuration as indicated in patched LINT file.
     Configure and make your kernel.

As seen from the shell history file (driver material assumed from /tmp), 
installation should proceed as follow (modulo mistakes from me:)):

cd /tmp
tar zxvf SYM-0.9.0-19991024.tar.gz
cp SYM-0.9.0-19991024/* /usr/src/sys/pci
cd /usr/src/sys
patch -p0 <pci/sym_sys.patch    # use sym_sys_3.patch if FreeBSD-3.X
cd pci
gzip -d </tmp/PATCH-SYM-0.10.0-19991111.gz | patch -p0


Warnings:
- This driver uses LOAD/STORE instructions from SCRIPTS and therefore does 
  not support earliest NCR chips (NCR53C810, NCR53C815, NCR53C825).

Versionning:
- The version number consists in 3 numbers X.Y.Z, starting with 0.0.0.
- Z will not be used for incremental patches, but may be used for 
  quick fixes.
- Incremental diff files are of the following pattern:
            PATCH-SYM-X.Y.Z-YYYYMMDD
  They must be applied from directory: /usr/src/sys/pci/
- Version 1.0.0 will happen when the driver will be tested enough but this 
  driver version will probably not officially support the C1010 (Ultra-3) 
  since the testing hasn't started yet. Some 1.X.0 version will support the 
  C1010 (DT data transfer). 
- Version 2.0.0 is not planned for now, but will add support for host target 
  mode if it will ever exist.

Change log:
* SYM-0.0.0-19990915
  Initial release.

* SYM-0.1.0-19990919  (diff file PATCH-SYM-0.1.0-19990919
  Add NVRAM support for latest Tekram boards using 24c16 EEPROM.

* SYM-0.2.0-19990922  (diff file PATCH-SYM-0.2.0-19990922
  Add PPR negotiation and Ultra3 DT transfers for the LSI53C1010.
  This corresponding code is untested since I haven't yet the 
  hardware. But the driver is not broken for current chips.

* SYM-0.3.0-19990925  (diff file PATCH-SYM-0.3.0-19990925
  Source review.
  Testing of the QUEUE FULL handling (some fixes applied).

* SYM-0.4.0-19990925  (diff file PATCH-SYM-0.4.0-19990928)
  Fixes, notably the QUEUE FULL handling that requeued everything 
  without telling the XPT about the error. Note that this did not 
  break anything, but the queue depth was never reduced.

* SYM-0.5.0-19991001  (diff file PATCH-SYM-0.5.0-19991001)
  Problem of not discovering LUNs != 0 hopefully fixed.
  Some other minor fixes.

* SYM-0.6.0-19991003  (diff file PATCH-SYM-0.6.0-19991003)
  Test error recovery pathes and residual calculation.
  Improve Symbios NVRAM support by applying the SCAN_LUNS flag. The driver 
  answers DEV_NOT_THERE to INQUIRYs for LUNs that are not to be scanned.
  Switch the driver status for SPI2 support to BETA-RELEASE.

* SYM-0.7.0-19991006  (diff file PATCH-SYM-0.7.0-19991006)
  Add support of the LSI1510D that emulates a 895 (infos sent by Compaq 
  that seems to be the only supplier of this chip)
  Return CAM_REQ_ABORTED on HS_ABORT host status.
  Fix a tiny bug that let the driver miss the TAG setting.

* SYM-0.8.0-19991016  (diff file PATCH-SYM-0.8.0-19991016)
  Heavy rewrite/rewamping of the error handling code in order to conform 
  to FreeBSD-CAM expectation of commands having to be requeued and device 
  queue to be frozen on any kind of error. Driver status switched back 
  to EXPERIMENTAL due to these changes.
  Warn user about targets that are not flagged for SCAN AT BOOT in the 
  NVRAM, since the driver will not allow the corresponding devices to be 
  discovered by XPT.
  And numerous minor changes.

* SYM-0.9.0-19991024  (Tar file SYM-0.9.0-19991024.tar.gz)
  Add support for previous PCI BUS stuff, for the driver to be useable 
  under FreeBSD 3.X RELEASES. The source is #ifdefed for using the old 
  PCI BUS code under __FreeBSD_version < 400000 and the new one otherwise.
  Tested under RELENG_3_2_0_RELEASE, but should also be just fine for 3.3.
  Other changes against version 0.8.0 are only minor buglet fixes.

* SYM-0.10.0-19991111  (diff file PATCH-SYM-0.10.0-19991111)
  Add support for Alpha - UNTESTED. Consists in some minor changes picked 
  mostly from the ncr driver and some others as ahc_pci.c.
  Fix the LED support through GPIO0 for pre-896 chips. In fact some code 
  was wrongly conditionned by something that was never met.
  Switch driver status to BETA-RELEASE given that this driver has been rock 
  solid even if s small number of users seems to actually use it.


November 11 1999.          "Gerard Roudier"<groudier@club-internet.fr>