From owner-freebsd-doc  Thu Oct  2 13:46:03 1997
Return-Path: <owner-freebsd-doc>
Received: (from root@localhost)
          by hub.freebsd.org (8.8.7/8.8.7) id NAA21889
          for doc-outgoing; Thu, 2 Oct 1997 13:46:03 -0700 (PDT)
Received: from iafnl.es.iaf.nl (uucp@iafnl.es.iaf.nl [195.108.17.20])
          by hub.freebsd.org (8.8.7/8.8.7) with SMTP id NAA21820
          for <doc@freebsd.org>; Thu, 2 Oct 1997 13:45:34 -0700 (PDT)
Received: by iafnl.es.iaf.nl with UUCP id AA19496
  (5.67b/IDA-1.5 for doc@freebsd.org); Thu, 2 Oct 1997 22:45:50 +0200
Received: (from wilko@localhost) by yedi.iaf.nl (8.8.5/8.6.12) id WAA02984 for doc@freebsd.org; Thu, 2 Oct 1997 22:37:50 +0100 (MET)
From: Wilko Bulte <wilko@yedi.iaf.nl>
Message-Id: <199710022137.WAA02984@yedi.iaf.nl>
Subject: please review update to scsi doc
To: doc@freebsd.org (FreeBSD Doc Project)
Date: Thu, 2 Oct 1997 22:37:50 +0100 (MET)
X-Organisation: Private FreeBSD site - Arnhem, The Netherlands
X-Pgp-Info: PGP public key at 'finger wilko@freefall.freebsd.org'
X-Mailer: ELM [version 2.4 PL24 ME8a]
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: owner-freebsd-doc@freebsd.org
X-Loop: FreeBSD.org
Precedence: bulk

Below is a diff -c relative to the scsi.sgml taken from the 2.2.1R CD.

I appreciate comments.

Wilko
------------

*** scsi.sgml.orig	Thu Oct  2 21:10:27 1997
--- scsi.sgml	Thu Oct  2 22:04:01 1997
***************
*** 1,15 ****
- <!-- $Id: scsi.sgml,v 1.19.2.1 1997/03/15 23:30:25 jkh Exp $ -->
  <!-- The FreeBSD Documentation Project -->
  
  <!--
        <title>An introduction to SCSI and its use with FreeBSD</title>
!       <author>(c) 1995-1996, Wilko Bulte, <tt/wilko@yedi.iaf.nl/
!       <date>Sat Jul  6 20:57:39 MET DST 1996</date>
!      Copyright 1995-1996, Wilko C. Bulte, Arnhem, The Netherlands 
  
        <abstract>
          This document attempts to describe the background of SCSI, its
!         (mis)use with FreeBSD and some common pitfalls. 
        </abstract>
        
  -->
--- 1,16 ----
  <!-- The FreeBSD Documentation Project -->
  
  <!--
        <title>An introduction to SCSI and its use with FreeBSD</title>
!       <author>(c) 1995-1996, Wilko Bulte, <tt/wilko@freebsd.org/
!       <date> Thu Oct  2 21:10:44 MET 1997 </date>
!      Copyright 1995-1997, Wilko C. Bulte, Arnhem, The Netherlands 
  
        <abstract>
          This document attempts to describe the background of SCSI, its
!         (mis)use with FreeBSD and some common pitfalls. It is not intended 
! 	to be a definitive guide, but should provide enough information
! 	to get people started.
        </abstract>
        
  -->
***************
*** 29,35 ****
          This effort was recognized in the ANSI SCSI-1 standard.  The SCSI-1
          standard (approx 1985) is rapidly becoming obsolete.  The current
          standard is SCSI-2 (see <ref id="scsi:further-reading" name="Further
!         reading">), with SCSI-3 on the drawing boards.
  
          In addition to a physical interconnection standard, SCSI defines a
          logical (command set) standard to which disk devices must adhere.
--- 30,38 ----
          This effort was recognized in the ANSI SCSI-1 standard.  The SCSI-1
          standard (approx 1985) is rapidly becoming obsolete.  The current
          standard is SCSI-2 (see <ref id="scsi:further-reading" name="Further
!         reading">), with SCSI-3 almost finished. SCSI-3 is divided in a
!  	number of sub-standards, for the sake of simplicity I'll ignore this
! 	here.
  
          In addition to a physical interconnection standard, SCSI defines a
          logical (command set) standard to which disk devices must adhere.
***************
*** 38,44 ****
          includes the (revised) CCS as part of the standard itself.  The
          commands are dependent on the type of device at hand. It does not
          make much sense of course to define a Write command for a
!         scanner.
  
          The SCSI bus is a parallel bus, which comes in a number of
          variants.  The oldest and most used is an 8 bit wide bus, with
--- 41,48 ----
          includes the (revised) CCS as part of the standard itself.  The
          commands are dependent on the type of device at hand. It does not
          make much sense of course to define a Write command for a
!         scanner. SCSI-3 builds upon earlier work and adds more standard
! 	commands for newer device types.
  
          The SCSI bus is a parallel bus, which comes in a number of
          variants.  The oldest and most used is an 8 bit wide bus, with
***************
*** 60,74 ****
          parity line. In pre-SCSI-2 designs parity was optional.
  
  	In SCSI-3 even faster bus types are introduced, along with a serial
! 	SCSI busses that reduces the cabling overhead and allows a higher
! 	maximum bus length. You might see names like SSA and Fiberchannel
  	in this context. None of the serial buses are currently in widespread
  	use (especially not in the typical FreeBSD environment). For
  	this reason the serial bus types are not discussed any further.
  	
          As you could have guessed from the description above, SCSI devices
          are intelligent.  They have to be to adhere to the SCSI standard
!         (which is over 2 inches thick BTW).  So, for a hard disk drive for
          instance you do not specify a head/cylinder/sector to address a
          particular block, but simply the number of the block you want.
  	Elaborate caching schemes, automatic bad block replacement etc
--- 64,78 ----
          parity line. In pre-SCSI-2 designs parity was optional.
  
  	In SCSI-3 even faster bus types are introduced, along with a serial
! 	SCSI interconnects that reduces the cabling overhead and allows a higher
! 	maximum link length. You might see names like SSA and Fibrechannel
  	in this context. None of the serial buses are currently in widespread
  	use (especially not in the typical FreeBSD environment). For
  	this reason the serial bus types are not discussed any further.
  	
          As you could have guessed from the description above, SCSI devices
          are intelligent.  They have to be to adhere to the SCSI standard
!         (which is over 3 inches thick BTW).  So, for a hard disk drive for
          instance you do not specify a head/cylinder/sector to address a
          particular block, but simply the number of the block you want.
  	Elaborate caching schemes, automatic bad block replacement etc
***************
*** 123,130 ****
            yourself a lot of grief by using good material.
  
            So, gold plated connectors, shielded cabling, sturdy connector
!           hoods with strain reliefs etc are the way to go. Second golden
!           rule: do no use cables longer than necessary. I once spent 3 days
            hunting down a problem with a flaky machine only to discover that
            shortening the SCSI bus by 1 meter solved the problem.  And the
            original bus length was well within the SCSI specification.
--- 127,138 ----
            yourself a lot of grief by using good material.
  
            So, gold plated connectors, shielded cabling, sturdy connector
!           hoods with strain reliefs etc are the way to go. For longer 
! 	  cabling you might want to consider Teflon insulated cabling.
! 	  Expensive, but good.
! 
! 	  Second golden rule: do no use cables longer than necessary. I once 
! 	  spent 3 days
            hunting down a problem with a flaky machine only to discover that
            shortening the SCSI bus by 1 meter solved the problem.  And the
            original bus length was well within the SCSI specification.
***************
*** 168,187 ****
  	  and status messages etc are only performed on the lowest 8
            data lines. The standard allows narrow devices to operate on
  	  a wide bus. The usable bus width is negotiated 
!           between the devices. You have to watch your device addressing
!           closely when mixing wide and narrow.
  
          <sect3><heading>Single ended buses</heading>
            <p>
              A single-ended SCSI bus uses signals that are either 5 Volts or
              0 Volts (indeed, TTL levels) and are relative to a COMMON
!             ground reference. A singled ended 8 bit SCSI bus has
              approximately 25 ground lines, who are all tied to a single
              `rail' on all devices. A standard single ended bus has a
              maximum length of 6 meters. If the same bus is used with
              fast-SCSI devices, the maximum length allowed drops to 3
!             meters. Fast-SCSI means that instead of 5Mbytes/sec the bus
!             allows 10Mbytes/sec transfers. 
  
  	    Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 
  	    megatransfers/second respectively. So, F20 is 20 Mbytes/second
--- 176,196 ----
  	  and status messages etc are only performed on the lowest 8
            data lines. The standard allows narrow devices to operate on
  	  a wide bus. The usable bus width is negotiated 
!           between the devices, and negotiation is always done via the 8bit
! 	  path. You have to watch your device addressing closely when 
! 	  mixing wide and narrow.
  
          <sect3><heading>Single ended buses</heading>
            <p>
              A single-ended SCSI bus uses signals that are either 5 Volts or
              0 Volts (indeed, TTL levels) and are relative to a COMMON
!             ground reference. A single ended 8 bit SCSI bus has
              approximately 25 ground lines, who are all tied to a single
              `rail' on all devices. A standard single ended bus has a
              maximum length of 6 meters. If the same bus is used with
              fast-SCSI devices, the maximum length allowed drops to 3
!             meters. Fast-SCSI means that instead of 5 Mtransfers/sec the bus
!             allows 10 Mtransfers/sec transfers. 
  
  	    Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 
  	    megatransfers/second respectively. So, F20 is 20 Mbytes/second
***************
*** 191,203 ****
  	    the limits quite a bit, so you will quickly find out if your
  	    SCSI bus is electrically sound.
  
! 	    Please note that this means that
              if some devices on your bus use 'fast' to communicate your
              bus must adhere to the length restrictions for fast buses!
  
!             It is obvious that with the newer fast-SCSI devices the
!             bus length can become a real bottleneck. This is why the
!             differential SCSI bus was introduced in the SCSI-2 standard.
  
              For connector pinning and connector types please refer to the
              SCSI-2 standard (see <ref id="scsi:further-reading" name="Further
--- 200,217 ----
  	    the limits quite a bit, so you will quickly find out if your
  	    SCSI bus is electrically sound.
  
! 	    Please note that the above means that
              if some devices on your bus use 'fast' to communicate your
              bus must adhere to the length restrictions for fast buses!
  
! 	    New developments are single chip based bus isolator chips that
! 	    re-condition signal levels and allow e.g. 10 meter cables even
! 	    with Ultra bus speeds. You need to carefully study the
! 	    restrictions that are associated with the use of these devices.
! 	    When used properly they allow much more wiring flexibility while
! 	    still using single ended signalling.
! 
! 	    More mainstream is the older differential signalling technique.
  
              For connector pinning and connector types please refer to the
              SCSI-2 standard (see <ref id="scsi:further-reading" name="Further
***************
*** 212,218 ****
  	    The reduction of the number of ground wires they used
  	    is a bad idea, you better stick to 50 pins cabling 
  	    in accordance with the SCSI standard. For Fast-20 and 40
! 	    do not even think about buses like this.
  
          <sect3><heading>Differential buses</heading>
            <p>
--- 226,235 ----
  	    The reduction of the number of ground wires they used
  	    is a bad idea, you better stick to 50 pins cabling 
  	    in accordance with the SCSI standard. For Fast-20 and 40
! 	    do not even think about buses like this. 
! 
! 	    Older Sun equipment ('shoeboxes' and the like) uses D-type
! 	    connectors with 3 rows of pins.
  
          <sect3><heading>Differential buses</heading>
            <p>
***************
*** 236,244 ****
  
  	    There is nothing that stops you from using differential stuff
  	    with FreeBSD, as long as you use a controller that has device
! 	    driver support in FreeBSD. As an example, Adaptec marketed the
! 	    AHA1740 as a single ended board, whereas the AHA1744 was differential.
! 	    The software interface to the host is identical for both.
  
          <sect3><heading>Terminators</heading>
            <p>
--- 253,262 ----
  
  	    There is nothing that stops you from using differential stuff
  	    with FreeBSD, as long as you use a controller that has device
! 	    driver support in FreeBSD. As an example, Adaptec markets the
! 	    AHA2940 as a single ended board, whereas the AHA2944 is 
! 	    differential. The software interface to the host is identical 
!             for both.
  
          <sect3><heading>Terminators</heading>
            <p>
***************
*** 276,282 ****
  
              Please keep in mind that terminators for differential and
              single-ended buses are not identical. You should <bf>not
!             mix</bf> the two variants.
  
              OK, and now where should you install your terminators?  This is
              by far the most misunderstood part of SCSI. And it is by far
--- 294,304 ----
  
              Please keep in mind that terminators for differential and
              single-ended buses are not identical. You should <bf>not
!             mix</bf> the two variants. Also, terminators should be installed
! 	    in the right orientation. That is, please put the pin 1 (normally
! 	    indicated by a black dot or something similar) in socket 1.
! 	    Reversing them can lead to very interesting and almost
! 	    impossible to debug effects.
  
              OK, and now where should you install your terminators?  This is
              by far the most misunderstood part of SCSI. And it is by far
***************
*** 293,299 ****
              terminators from the controller. The terminator must now be on
              the last external device, and not on the controller! In
              general, every reconfiguration of a SCSI bus must pay attention
!             to this.
  
              What I did myself is remove all terminators from my SCSI
              devices and controllers. I own a couple of external
--- 315,321 ----
              terminators from the controller. The terminator must now be on
              the last external device, and not on the controller! In
              general, every reconfiguration of a SCSI bus must pay attention
!             to terminator location. 
  
              What I did myself is remove all terminators from my SCSI
              devices and controllers. I own a couple of external
***************
*** 330,350 ****
              power must be supplied to the bus via a diode. This prevents
              the backflow of current to un-powered devices.
  
!             To prevent all kinds of nastiness, the terminator power is
!             usually fused.  As you can imagine, fuses might blow. This can,
              but does not have to, lead to a non functional bus. If multiple
              devices supply terminator power, a single blown fuse will not
              put you out of business. A single supplier with a blown fuse
              certainly will. Clever external terminators sometimes have a 
  	    LED indication that shows whether terminator power is present.
  
!             In newer designs auto-restoring fuses that 'reset'
!             themselves after some time are sometimes used.
  
          <sect3><heading>Device addressing</heading>
            <p>
              Because the SCSI bus is, ehh, a bus there must be a way to
              distinguish or address the different devices connected to it.
  
              This is done by means of the SCSI or target ID. Each device has
              a unique target ID.  You can select the ID to which a device
--- 352,375 ----
              power must be supplied to the bus via a diode. This prevents
              the backflow of current to un-powered devices.
  
!             To prevent all kinds of other nastiness, the terminator power 
!             has to be fused.  As you can imagine, fuses might blow. This can,
              but does not have to, lead to a non functional bus. If multiple
              devices supply terminator power, a single blown fuse will not
              put you out of business. A single supplier with a blown fuse
              certainly will. Clever external terminators sometimes have a 
  	    LED indication that shows whether terminator power is present.
+ 	    A very useful feature.
  
!             Newer designs often use auto-restoring fuses that 'reset'
!             themselves some time after a short circuit.
  
          <sect3><heading>Device addressing</heading>
            <p>
              Because the SCSI bus is, ehh, a bus there must be a way to
              distinguish or address the different devices connected to it.
+ 	    During the arbitration phase devices decide which device is
+ 	    allowed use of the bus.
  
              This is done by means of the SCSI or target ID. Each device has
              a unique target ID.  You can select the ID to which a device
***************
*** 360,366 ****
              For an 8 bit bus, a maximum of 8 targets is possible. The
              maximum is 8 because the selection is done bitwise using the 8
              data lines on the bus.  For wide buses this increases to the 
!             number of data lines.
  
              The higher the SCSI target ID, the higher the priority the
              devices has.  When it comes to arbitration between devices that
--- 385,391 ----
              For an 8 bit bus, a maximum of 8 targets is possible. The
              maximum is 8 because the selection is done bitwise using the 8
              data lines on the bus.  For wide buses this increases to the 
!             number of data lines available.
  
              The higher the SCSI target ID, the higher the priority the
              devices has.  When it comes to arbitration between devices that
***************
*** 368,373 ****
--- 393,402 ----
              highest SCSI ID will win. This also means that the SCSI
              host adapter usually uses target ID 7 (for narrow buses).
  
+ 	    Wide (16 bit) buses are tricky, the priority is in this case
+ 	    7 - 6 - ...  - 2 - 1 - 0 - 15 - 14 - ... - 8 (where 7 is the
+ 	    highest priority).
+ 
              For a further subdivision, the standard allows for Logical
              Units or LUNs for short. A single target ID may have multiple
              LUNs. For example, a tape device including a tape changer may
***************
*** 408,422 ****
  
            One might be inclined to think that since SCSI disks are smart
            you can forget about this. Alas, the arcane setup issue is still
!           present today. The system BIOS needs to know how to access your
            SCSI disk with the head/cyl/sector method in order to load the
  	  FreeBSD kernel during boot.
  
            The SCSI host adapter or SCSI controller you have put in your
            AT/EISA/PCI/whatever bus to connect your disk therefore has its
            own on-board BIOS. During system startup, the SCSI BIOS takes over
!           the hard disk interface routines from the system BIOS. To fool the
!           system BIOS, the system setup is normally set to No hard disk
            present. Obvious, isn't it?
  
            The SCSI BIOS itself presents to the system a so called
--- 437,451 ----
  
            One might be inclined to think that since SCSI disks are smart
            you can forget about this. Alas, the arcane setup issue is still
!           present today. The PC's system BIOS needs to know how to access your
            SCSI disk with the head/cyl/sector method in order to load the
  	  FreeBSD kernel during boot.
  
            The SCSI host adapter or SCSI controller you have put in your
            AT/EISA/PCI/whatever bus to connect your disk therefore has its
            own on-board BIOS. During system startup, the SCSI BIOS takes over
!           the hard disk interface routines from the PC's system BIOS. To fool 
! 	  the system BIOS, the system setup is normally set to No hard disk
            present. Obvious, isn't it?
  
            The SCSI BIOS itself presents to the system a so called
***************
*** 429,435 ****
            megabytes. The division by 2 is to get from disk blocks that are
            normally 512 bytes in size to Kbytes.
  
!           Right. All is well now?! No, it is not. The system BIOS has
            another quirk you might run into. The number of cylinders of a
            bootable hard disk cannot be greater than 1024. Using the
            translation above, this is a show-stopper for disks greater than
--- 458,464 ----
            megabytes. The division by 2 is to get from disk blocks that are
            normally 512 bytes in size to Kbytes.
  
!           Right. All is well now?! No, it is not. The PC's system BIOS has
            another quirk you might run into. The number of cylinders of a
            bootable hard disk cannot be greater than 1024. Using the
            translation above, this is a show-stopper for disks greater than
***************
*** 470,484 ****
  
  	  Why has this changed?
  
!           This info is retrieved from the SCSI disk itself. Newer disks
            often use a technique called zone bit recording. The idea is that
!           on the outer cylinders of the drive there is more space so more
            sectors per track can be put on them. This results in disks that
            have more tracks on outer cylinders than on the inner cylinders
            and, last but not least, have more capacity. You can imagine that
            the value reported by the drive when inquiring about the geometry
!           now becomes suspect at best, and nearly always misleading. When
! 	  asked for a geometry , it is nearly always better to supply the
  	  geometry used by the BIOS, or <em>if the BIOS is never going to know
  	  about this disk</em>, (e.g. it is not a booting disk) to supply a
  	  fictitious geometry that is convenient.
--- 499,513 ----
  
  	  Why has this changed?
  
!           This information is retrieved from the SCSI disk itself. Newer disks
            often use a technique called zone bit recording. The idea is that
!           on the outer cylinders of the drive more space is available so more
            sectors per track can be put on them. This results in disks that
            have more tracks on outer cylinders than on the inner cylinders
            and, last but not least, have more capacity. You can imagine that
            the value reported by the drive when inquiring about the geometry
!           now becomes suspect at best, and is nearly always misleading. When
! 	  asked for a geometry , it is usually better to supply the
  	  geometry used by the BIOS, or <em>if the BIOS is never going to know
  	  about this disk</em>, (e.g. it is not a booting disk) to supply a
  	  fictitious geometry that is convenient.
***************
*** 501,507 ****
  
            The multi level design allows a decoupling of low-level bit
            banging and more high level stuff. Adding support for another
!           piece of hardware is a much more manageable problem.
          
        <sect3><heading>Kernel configuration</heading>
          <p>
--- 530,538 ----
  
            The multi level design allows a decoupling of low-level bit
            banging and more high level stuff. Adding support for another
!           piece of hardware is a much more manageable problem. It is easy
! 	  to acknowledge the design elegance of SCSI that makes this
! 	  approach feasible.
          
        <sect3><heading>Kernel configuration</heading>
          <p>
***************
*** 653,659 ****
  	  use 3 seconds minimum to get my trusty old CDROM drive to be recognized.
  	  Start with a high value (say 30 seconds or so) when you have problems 
  	  with device recognition. If this helps, tune it back until it just stays
! 	  working.
  
        <sect3><heading>Rogue SCSI devices</heading>
          <p>  
--- 684,691 ----
  	  use 3 seconds minimum to get my trusty old CDROM drive to be recognized.
  	  Start with a high value (say 30 seconds or so) when you have problems 
  	  with device recognition. If this helps, tune it back until it just stays
! 	  working (I know, I'm impatient. You can leave it at 30 secs if you
! like).
  
        <sect3><heading>Rogue SCSI devices</heading>
          <p>  
***************
*** 756,761 ****
--- 788,796 ----
   	  it leads to highly mysterious problems. In such cases,
  	  try to disable TCQ.
  
+ 	  Adding 'options FAILSAFE' to your kernel config file disables
+ 	  the use of TCQ.
+ 
        <sect3><heading>Busmaster host adapters</heading>
          <p>
  	  Most, but not all, SCSI host adapters are bus mastering controllers.
***************
*** 795,806 ****
  
          <itemize>
            <item>
!             Check for loose connectors and cables.
            <item>
              Check and double check the location and number of your terminators.
            <item>
!             Check if your bus has at least one supplier of terminator power
!             (especially with external terminators.
            <item>
              Check if no double target IDs are used.
            <item>
--- 830,842 ----
  
          <itemize>
            <item>
!             Check for loose connectors, bent connector pins and loose cables.
            <item>
              Check and double check the location and number of your terminators.
+ 	    And check if they are inserted in the right orientation. 
            <item>
!             Check if your bus has at least one supplier of terminator power,
!             especially with external terminators.
            <item>
              Check if no double target IDs are used.
            <item>
***************
*** 826,831 ****
--- 862,869 ----
  	    This will give you COPIOUS debugging output with which to confuse
  	    the gurus. see <tt>man 4 scsi</tt> for more exact information.
  	    Also look at <tt>man 8 scsi</tt>.
+ 	    The gurus can be found on the freebsd-scsi mailing list. Our
+ 	    friendly majordomo@freebsd.org can get you a free subscription.
          </itemize>
  
      <sect2><heading>Further reading<label id="scsi:further-reading"></heading>
***************
*** 888,891 ****
  
          Most major SCSI device and host adapter suppliers operate ftp sites
          and/or BBS systems. They may be valuable sources of information
!         about the devices you own.
--- 926,930 ----
  
          Most major SCSI device and host adapter suppliers operate ftp sites
          and/or BBS systems. They may be valuable sources of information
!         about the devices you own. Some examples are www.adaptec.com,
! 	www.symbios.com, www.quantum.co,

_     ____________________________________________________________________
 |   / o / /  _  Bulte  email: wilko@yedi.iaf.nl http://www.tcja.nl/~wilko
 |/|/ / / /( (_) Arnhem, The Netherlands - Do, or do not. There is no 'try'
----------------------------------------------------------------------Yoda