Update scsi.sgml to reflect recent reality. Change Japanese

translation to match it.  Refine Japanese translation.  Move around
newlines in Japanese version to make it look more pleasant on a
graphical web browser (i.e., netscape).

Submitted by:	asami, Yoshiaki Uchikawa <yoshiaki@kt.rim.or.jp>

handbook/scsi.sgml

@@ -1,4 +1,4 @@
-<!-- $Id: scsi.sgml,v 1.24 1997-12-25 09:36:38 hoek Exp $ -->
+<!-- $Id: scsi.sgml,v 1.25 1997-12-28 20:18:14 asami Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!--
@@ -49,9 +49,10 @@
         20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2
         allows a maximum bus width of 32 bits, using an additional cable.
 	Quickly emerging are Ultra SCSI (also called Fast-20) and Ultra2
-	(also called Fast-40). Fast-20 is 20 mega-transfers per second
+	(also called Fast-40). Fast-20 is 20 million transfers per second
-	(20 Mbytes/sec on a 8 bit bus), Fast-40 is 40 mega-transfers per
+	(20 Mbytes/sec on a 8 bit bus), Fast-40 is 40 million transfers per
-	second (40 Mbytes/sec on a 8 bit bus).
+	second (40 Mbytes/sec on a 8 bit bus).  Most hard drives sold today
+	are single-ended Ultra SCSI (8 or 16 bits).
 
         Of course the SCSI bus not only has data lines, but also a number
         of control signals. A very elaborate protocol is part of the
@@ -91,7 +92,7 @@
 	Generally speaking, the chances of getting a working set of
 	devices on a single bus is better when all the devices are SCSI-2
 	or newer.  This implies that you do not have to dump all your old
-	stuff when you get that shiny 2Gb disk: I own a system on which a
+	stuff when you get that shiny 2GB disk: I own a system on which a
 	pre-SCSI-1 disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan
 	tape unit and 2 SCSI-1 disks work together quite happily. From
 	a performance standpoint you might want to separate your older
@@ -160,7 +161,7 @@
           Fast means that the timing on the bus is somewhat different, so
           that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead
           of 5 Mbytes/sec for 'slow' SCSI. As discussed before, bus
-	  speeds of 20 and 40 megatransfers/second are also emerging 
+	  speeds of 20 and 40 million transfers/second are also emerging 
 	  (Fast-20 == Ultra SCSI and Fast-40 == Ultra2 SCSI). 
 
 	  It should be noted that the data lines &gt; 8 are only used for
@@ -183,8 +184,8 @@
             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 
+	    Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million
-	    megatransfers/second respectively. So, F20 is 20 Mbytes/second
+	    transfers/second respectively. So, F20 is 20 Mbytes/second
 	    on a 8 bit bus, 40 Mbytes/second on a 16 bit bus etc.
 	    For F20 the max bus length is 1.5 meters, for F40 it
 	    becomes 0.75 meters. Be aware that F20 is pushing 
@@ -252,7 +253,7 @@
 
             Terminators come in various incarnations, with more or less
             sophisticated designs.  Of course, there are internal and
-            external variants.  Almost every SCSI device comes with a
+            external variants.  Many SCSI devices come with a
             number of sockets in which a number of resistor networks can
             (must be!) installed.  If you remove terminators from a device,
             carefully store them. You will need them when you ever decide to
@@ -280,14 +281,15 @@
 
             OK, and now where should you install your terminators?  This is
             by far the most misunderstood part of SCSI. And it is by far
-            the simplest.  The rule is: <bf>every SCSI bus has 2 (two)
+            the simplest.  The rule is: <bf>every single line on the SCSI bus has 2 (two)
             terminators, one at each end of the bus.</bf> So, two and not
             one or three or whatever. Do yourself a favor and stick to
             this rule. It will save you endless grief, because wrong
             termination has the potential to introduce highly mysterious
-            bugs.
+            bugs.  (Note the "potential" here; the nastiest part is that
+            it may or may not work.)
 
-            A common pitfall is to have an internal (flat)cable in a
+            A common pitfall is to have an internal (flat) cable in a
             machine and also an external cable attached to the
             controller. It seems almost everybody forgets to remove the
             terminators from the controller. The terminator must now be on
@@ -295,6 +297,12 @@
             general, every reconfiguration of a SCSI bus must pay attention
             to this.
 
+            Note that termination is to be done on a per-line basis.
+            This means if you have both narrow and wide buses
+            connected to the same host adapter, you need to enable
+            termination on the higher 8 bits of the bus on the adapter
+            (as well as the last devices on each bus, of course).
+
             What I did myself is remove all terminators from my SCSI
             devices and controllers. I own a couple of external
             terminators, for both the Centronics-type external cabling and
@@ -305,9 +313,11 @@
             used. These things are special purpose integrated circuits that
             can be dis/en-abled with a control pin. It is not necessary to
             physically remove them from a device.  You may find them on
-            newer host adapters, sometimes they even are software
+            newer host adapters, sometimes they are software
-            configurable, using some sort of setup tool. Consult you
+            configurable, using some sort of setup tool. Some will even
-	    documentation!
+            auto-detect the cables attached to the connectors and
+            automatically set up the termination as necessary.  At any
+            rate, consult your documentation!
 
         <sect3><heading>Terminator power</heading>
           <p>
@@ -346,11 +356,14 @@
             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
+            This is done by means of the SCSI or target ID. Each
-            a unique target ID.  You can select the ID to which a device
+            device has a unique target ID.  You can select the ID to
-            must respond using a set of jumpers, or a dip switch, or
+            which a device must respond using a set of jumpers, or a
-            something similar. Consult the documentation of your device for
+            dip switch, or something similar. Some SCSI host adapters
-            more information.
+            let you change the target ID from the boot menu.  (Yet
+            some others will not let you change the ID from 7.) 
+            Consult the documentation of your device for more
+            information.
 
             Beware of multiple devices configured to use the same ID. Chaos
             normally reigns in this case. A pitfall is that one of the
@@ -360,13 +373,24 @@
             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.
+            number of data lines (usually 16).
+
+            Note that a narrow SCSI device can not communicate with a
+            SCSI device with a target ID larger than 7.  This means it
+            is generally not a good idea to move your SCSI host
+            adapter's target ID to something higher than 7 (or your
+            CD-ROM will stop working).
 
             The higher the SCSI target ID, the higher the priority the
             devices has.  When it comes to arbitration between devices that
             want to use the bus at the same time, the device that has the
             highest SCSI ID will win. This also means that the SCSI
-            host adapter usually uses target ID 7 (for narrow buses).
+            host adapter usually uses target ID 7.
+            Note however that the lower 8 IDs have higher priorities than
+            the higher 8 IDs on a wide-SCSI bus.  Thus, the order of target
+            IDs is: <tt>[7 6 .. 1 0 15 14 .. 9 8]</tt> on a wide-SCSI
+            system.  (If you you are wondering why the lower 8 have higher
+            priority, read the previous paragraph for a hint.)
 
             For a further subdivision, the standard allows for Logical
             Units or LUNs for short. A single target ID may have multiple
@@ -377,12 +401,24 @@
 
         <sect3><heading>Bus layout</heading>
           <p>
-            SCSI buses are linear. So, not shaped like Y-junctions, star
+            SCSI buses are linear. So, not shaped like Y-junctions,
-            topologies, cobwebs or whatever else people might want to
+            star topologies, rings, cobwebs or whatever else people
-            invent.
+            might want to invent.  One of the most common mistakes is
+            for people with wide-SCSI host adapters to connect devices
+            on all three connecters (external connector, internal wide
+            connector, internal narrow connector).  Don't do that.  It
+            may appear to work if you are really lucky, but I can
+            almost guarantee that your system will stop functioning at
+            the most unfortunate moment (this is also known as
+            "Murphy's law").
 
-            You might notice that the terminator issue discussed earlier
+            You might notice that the terminator issue discussed
-            becomes rather hairy if your bus is not linear.
+            earlier becomes rather hairy if your bus is not linear.
+            Also, if you have more connectors than devices on your
+            internal SCSI cable, make sure you attach devices on
+            connectors on both ends instead of using the connectors in
+            the middle and let one or both ends dangle.  This will
+            screw up the termination of the bus.
 
             The electrical characteristics, its noise margins and
             ultimately the reliability of it all are tightly related to
@@ -433,7 +469,7 @@
           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
-          1 Gb. With disk capacities going up all the time this is causing
+          1 GB. With disk capacities going up all the time this is causing
           problems.
 
           Fortunately, the solution is simple: just use another
@@ -494,7 +530,7 @@
 
           On top of the card drivers there are a number of more generic
           drivers for a class of devices. More specific: a driver for
-          tape devices (abbreviation: st), magnetic disks (sd), cdroms (cd)
+          tape devices (abbreviation: st), magnetic disks (sd), CD-ROMs (cd)
           etc. In case you are wondering where you can find this stuff, it
           all lives in <tt>/sys/scsi</tt>. See the man pages in section 4
 	  for more details.
@@ -519,9 +555,13 @@
 	  file should reflect your actual hardware setup. So, interrupts,
 	  I/O addresses etc must match the kernel config file. During
 	  system boot messages will be displayed to indicate whether
-	  the configured hardware was actually found.
+	  the configured hardware was actually found.  Note that most
+	  of the EISA/PCI drivers (namely <tt>ahb, ahc, ncr</tt> and
+	  <tt>amd</tt> will automatically obtain the correct parameters
+	  from the host adapters themselves at boot time; thus, you just
+	  need to write, for instance, "<tt>controller ahc0</tt>".
 
-          An example loosely based on the FreeBSD 2.0.5-Release kernel config 
+          An example loosely based on the FreeBSD 2.2.5-Release kernel config 
 	  file LINT with some added comments (between &lsqb;&rsqb;):
 
 	  <verb>
@@ -532,39 +572,41 @@
 # ahb: Adaptec 174x
 # ahc: Adaptec 274x/284x/294x
 # aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!)
+# amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T)
 # bt: Most Buslogic controllers
 # nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130
+# ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards
 # uha: UltraStore 14F and 34F
 # sea: Seagate ST01/02 8 bit controller (slow!)
 # wds: Western Digital WD7000 controller (no scatter/gather!).
 #
 
-&lsqb;For an Adaptec AHA274x, 284x etc controller&rsqb;
+&lsqb;For an Adaptec AHA274x/284x/294x/394x etc controller&rsqb;
-controller	ahc0	at isa? bio irq ? vector ahcintr # port??? iomem?
+controller	ahc0
 
-&lsqb;For an Adaptec AHA174x controller&rsqb;
+&lsqb;For an NCR/Symbios 53c875 based controller&rsqb;
-controller	ahb0	at isa? bio irq ? vector ahbintr
+controller	ncr0
 
 &lsqb;For an Ultrastor adapter&rsqb;
 controller	uha0	at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr
 
 # Map SCSI buses to specific SCSI adapters
 controller	scbus0	at ahc0
-controller	scbus2  at ahb0
+controller	scbus2  at ncr0
 controller	scbus1  at uha0
 
 # The actual SCSI devices
 disk sd0 at scbus0 target 0 unit 0	[SCSI disk 0 is at scbus 0, LUN 0]
 disk sd1 at scbus0 target 1		[implicit LUN 0 if omitted]
 disk sd2 at scbus1 target 3		[SCSI disk on the uha0]
-disk sd3 at scbus2 target 4		[SCSI disk on the ahb0]
+disk sd3 at scbus2 target 4		[SCSI disk on the ncr0]
 tape st1 at scbus0 target 6		[SCSI tape at target 6]
-device cd0 at scbus?			[the first ever CDROM found, no wiring]
+device cd0 at scbus?			[the first ever CD-ROM found, no wiring]
 
 	  </verb>
 
 	  The example above tells the kernel to look for a ahc (Adaptec 274x)
-	  controller, then for an Adaptec 174x board, and 
+	  controller, then for an NCR/Symbios board, and 
 	  so on. The lines following the controller specifications 
 	  tell the kernel to configure specific devices but 
 	  <em>only</em> attach them when they match the target ID and
@@ -616,7 +658,7 @@ device          sd0	&lsqb;support for 4 SCSI harddisks, sd0 up sd3&rsqb;
 
 device          st0	&lsqb;support for 2 SCSI tapes&rsqb;
 
-&lsqb;for the cdrom&rsqb;
+&lsqb;for the CD-ROM&rsqb;
 device          cd0     #Only need one of these, the code dynamically grows
           </verb>
 
@@ -630,14 +672,14 @@ device          cd0     #Only need one of these, the code dynamically grows
 
           Use <tt>man 4 scsi</tt> to check for the latest info on the SCSI
           subsystem. For more detailed info on host adapter drivers use eg
-          <tt>man 4 aha</tt> for info on the Adaptec 154x driver.
+          <tt>man 4 ahc</tt> for info on the Adaptec 294x driver.
 
       <sect3><heading>Tuning your SCSI kernel setup</heading>
         <p>
           Experience has shown that some devices are slow to respond to INQUIRY 
 	  commands after a SCSI bus reset (which happens at boot time).
 	  An INQUIRY command is sent by the kernel on boot to see what
-	  kind of device (disk, tape, CDROM etc) is connected to a
+	  kind of device (disk, tape, CD-ROM etc) is connected to a
 	  specific target ID. This process is called device probing by the way.
 
 	  To work around the 'slow response' problem, FreeBSD allows a 
@@ -650,7 +692,7 @@ device          cd0     #Only need one of these, the code dynamically grows
 options         SCSI_DELAY=15         #Be pessimistic about Joe SCSI device
 	  </verb>
 	  This line sets the delay time to 15 seconds. On my own system I had to
-	  use 3 seconds minimum to get my trusty old CDROM drive to be recognized.
+	  use 3 seconds minimum to get my trusty old CD-ROM 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.
@@ -690,7 +732,7 @@ Mar 29 21:16:37 yedi /kernel: st1: Archive  Viper 150 is a known rogue
 
 	  This scheme works fine, but keep in mind that it of course only
 	  works for devices that are KNOWN to be weird. If you are the first
-          to connect your bogus Mumbletech SCSI CDROM you might be the one
+          to connect your bogus Mumbletech SCSI CD-ROM you might be the one
 	  that has to define which workaround is needed.
 
 	  After you got your Mumbletech working, please send the required