`sym' driver man page addition.

Reviewed by: David O'Brien

1 files changed, 255 insertions, 0 deletions

diff --git a/share/man/man4/sym.4 b/share/man/man4/sym.4
new file mode 100644
index 0000000..5b749b8
--- /dev/null
+++ b/share/man/man4/sym.4
@@ -0,0 +1,255 @@
+.\"
+.\"  Device driver optimized for the Symbios/LSI 53C896/53C895A/53C1010
+.\"  PCI-SCSI controllers.
+.\"
+.\"  Copyright (C) 1999-2000  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 initialization 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 12, 2000
+.Dt SYM 4 i386
+.Os FreeBSD
+.Sh NAME
+.Nm sym
+.Nd Symbios/LSI Logic PCI-SCSI host adapter driver
+.Sh SYNOPSIS
+For any number of cards:
+.Cd device sym0
+.Pp
+To disable PCI parity checking (needed for broken bridges)
+.Cd options SYM_SETUP_PCI_PARITY=<boolean>
+.Pp
+To control driver probing against HVD buses
+.Cd options SYM_SETUP_SCSI_DIFF=<bit combination>
+.Pp
+To control chip attachment balancing between the ncr driver and this driver
+.Cd options SYM_SETUP_LP_PROBE_MAP=<bit combination>
+.Sh DESCRIPTION
+This driver provides support for the Symbios/LSI Logic
+.Tn 53C810A,
+.Tn 53C825A,
+.Tn 53C860,
+.Tn 53C875,
+.Tn 53C876,
+.Tn 53C895,
+.Tn 53C895A,
+.Tn 53C896,
+.Tn 53C897,
+.Tn 53C1510D,
+and
+.Tn 53C1010
+PCI-SCSI controllers.
+.Pp
+Driver features include support for wide SCSI busses, fast10, fast20,
+fast40 and fast80-dt synchronous data transfers depending on controller
+capabilities. It also provides generic SCSI features as tagged command
+queuing and auto-request sense. This driver is configured by default
+for a maximum of 446 outstanding commands per bus, 8 LUNs per target
+and 64 tagged tasks per LUN. These numbers are not so limited by design,
+as have been considered reasonable values for current SCSI technology.
+These values can be increased by changing appropriate
+constants in driver header files (not recommended).
+.Pp
+This driver requires the PCI-SCSI chip to implement LOAD/STORE SCRIPTS
+instructions and therefore it does not provide support for 53C810 revid < 16,
+53C825 revid < 16 and all 53C815 revisions. The generic
+.Nm ncr
+driver can be used to support these early chips.
+.Pp
+By default, when both the
+.Nm ncr
+and
+.Nm
+drivers are configured, the
+.Nm
+driver takes precedence over the
+.Nm ncr
+driver for all chips that are supported by
+both drivers. As result, the
+.Nm ncr
+driver does only attach the 53C8XX
+chips that donnot support LOAD/STORE (i.e.: 53C810, 53C815 and 53C825).
+User can change the balancing of chip types between drivers by defining
+the
+.Ar SYM_SETUP_LP_PROBE_MAP
+kernel configuration option as follows:
+.Bl -column "Bit   " "53C8XXA, 53C8XX, 53C8XX, 53C8XX, 53C8XX, 53C8XX"
+.Em Bit	Devices attached by ncr instead
+1	53C810a, 53C860
+2	53C825a, 53C875, 53C876, 53C885, 53C895
+4	53C895a, 53C896, 53C897, 53C1510d
+.El
+.Ed
+.Pp
+For example, if
+.Ar SYM_SETUP_LP_PROBE_MAP
+is supplied with value 7, all the
+above chips will be attached by the
+.Nm ncr
+driver and the
+.Nm
+driver will only
+attach the 53C1010 Ultra-3 controllers.
+.Pp
+HVD/LVD capable controllers (895, 895A, 896, 897 and 1010) report
+the actual bus mode from the STEST4 chip IO registers. This feature
+allows to safely probe against bus mode and to set up the chip
+accordingly. By default the driver only supports HVD for these chips.
+For other chips that can support HVD but not LVD, the driver has to probe
+implementation dependent registers (GPIO) in order to detect HVD bus mode.
+Only HVD implementations that conform with Symbios Logic recommendation can
+be detected by the driver. When the
+.Ar SYM_SETUP_SCSI_DIFF
+kernel is provided
+as value 1, the driver will also probe against HVD for 825a, 875, 876 and
+885 chips, assuming Symbios Logic compatible implementation of HVD.
+.Pp
+When supplied as 0, the
+.Ar SYM_SETUP_PCI_PARITY
+kernel configuration option
+indicates the driver not to enable PCI parity checking. PCI parity
+checking should not be an option for PCI-SCSI controllers, but some
+systems have been reported to fail using 53C8XX chips due to spurious or
+permanent PCI parity errors detected. This option is supplied for
+convenience but it is not recommended nor supported.
+.Pp
+This driver offers other options that are not currently exported to user.
+They are defined and documented in the sym_conf.h driver file. It is not
+recommended to change these options unless absolute need. Some of these
+options are planned to be exported through SYSCTL or equivalent mechanism
+in a further driver release and therefore, no compatibility is guaranteed.
+.Pp
+At initialization, the driver tries to detect and read user settings from
+controller NVRAM. The Symbios/Logic NVRAM layout and the Tekram NVRAM
+layout are currently supported. If the reading of the NVRAM succeeds, the
+following settings are taken into account and reported to CAM:
+.Pp
+.Bl -column "SCSI parity checking      " "Symbios     " "Tekram"
+.Em Host settings	Symbios	Tekram
+SCSI parity checking	Y	N
+Host SCSI ident 	Y	Y
+Verbose messages	Y	N
+Scan targets hi-lo	Y	N
+Avoid SCSI bus reset	Y	N
+.Pp
+.El
+.Bl -column "Synchronous period       " "Symbios     " "Tekram"
+.Em Device settings	Symbios	Tekram
+Synchronous period	Y	Y
+SCSI bus width  	Y	Y
+Queue tag enable	Y	Y
+Number of tags  	NA	Y
+Disconnect enable	Y	Y
+Scan at boot time	Y	N
+Scan LUN       	Y	N
+.El
+.Pp
+Devices that are configured as disabled for 'scan' in the NVRAM are not
+reported to CAM at system start-up. They can be discovered later using
+the
+.Nm camcontrol rescan
+command.
+.Pp
+The table below summarizes the main features and capabilities of the
+NCR/Symbios/LSI Logic 53C8XX family of PCI-SCSI controllers.
+.Pp
+.Bl -column sym53c1510d "Sync   " "Width  " "SRAM  " "PCI64"
+.Em Chip	Sync	Width	SRAM	PCI64	Supported
+sym53c810	10MHz	8Bit	N	N	N
+sym53c810a	10MHz	8Bit	N	N	Y
+sym53c815	10MHz	8Bit	N	N	N
+sym53c825	10MHz	16Bit	N	N	N
+sym53c825a	10MHz	16Bit	4KB	N	Y
+sym53c860	20MHz	8Bit	N	N	Y
+sym53c875	20MHz	16Bit	4KB	N	Y
+sym53c876	20MHz	16Bit	4KB	N	Y
+sym53c885	20MHz	16Bit	4KB	N	Y
+sym53c895	40MHz	16Bit	4KB	N	Y
+sym53c895A	40MHz	16Bit	8KB	N	Y
+sym53c896	40MHz	16Bit	8KB	Y	Y
+sym53c897	40MHz	16Bit	8KB	Y	Y
+sym53c1510D	40MHz	16Bit	4KB	Y	Y
+sym53c1010	80MHz	16Bit	8KB	Y	Y
+.El
+.Pp
+.Sh BUGS
+No known bugs.
+.Sh SEE ALSO
+.Xr cd 4 ,
+.Xr da 4 ,
+.Xr ncr 4 ,
+.Xr sa 4 ,
+.Xr scsi 4 ,
+.Xr camcontrol 8
+.Sh AUTHORS
+The
+.Nm
+driver has been written by Gerard Roudier and is derived from the
+Linux sym53c8xx driver from the same author.
+The sym53c8xx driver is derived from the ncr53c8xx driver that had been
+a port of the
+.Fx
+.Nm ncr
+driver to Linux-1.2.13.
+The original
+.Nm ncr
+driver was written for 386BSD and
+.Fx
+by Wolfgang Stanglmeier and Stefan Esser.
+.Sh HISTORY
+The
+.Nm
+driver appeared in
+.Fx 4.0 .
+