aboutsummaryrefslogtreecommitdiff
path: root/handbook/scsi.sgml
blob: 9794c720ebe67cc4610b91768a64c7ed4ac8663b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
<!-- $Id: scsi.sgml,v 1.1.1.1.4.6 1996-07-07 23:26:45 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>
      
-->
    <sect1><heading>What is SCSI?<label id="scsi"></heading>

      <p><em>Copyright &copy; 1995, &a.wilko;.<newline>July 6, 1996.</em>

        SCSI is an acronym for Small Computer Systems Interface.  It is an
        ANSI standard that has become one of the leading I/O buses in the
        computer industry.  The foundation of the SCSI standard was laid by
        Shugart Associates (the same guys that gave the world the first
        mini floppy disks) when they introduced the SASI bus (Shugart Associates
        Standard Interface).

        After some time an industry effort was started to come to a more strict
        standard allowing devices from different vendors to work together.
        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.
        This standard is called the Common Command Set (CCS) and was
        developed more or less in parallel with ANSI SCSI-1.  SCSI-2
        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
        single-ended signals, carried on 50 wires.  (If you do not know what
        single-ended means, do not worry, that is what this document is all
        about.)  Modern designs also use 16 bit wide buses, with
        differential signals.  This allows transfer speeds of
        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
	(20 Mbytes/sec on a 8 bit bus), Fast-40 is 40 mega-transfers per
	second (40 Mbytes/sec on a 8 bit bus).

        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
        standard to allow multiple devices to share the bus in an efficient
        manner. In SCSI-2, the data is always checked using a separate
        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
	are all made possible by this 'intelligent device' approach.

        On a SCSI bus, each possible pair of devices can communicate. Whether
        their function allows this is another matter, but the standard does
        not restrict it. To avoid signal contention, the 2 devices have to
        arbitrate for the bus before using it.

        The philosophy of SCSI is to have a standard that allows
        older-standard devices to work with newer-standard ones.  So, an
        old SCSI-1 device should normally work on a SCSI-2 bus.  I say
	Normally, because it is not absolutely sure that the implementation
	of an old device follows the (old) standard closely enough to be
	acceptable on a new bus.  Modern devices are usually more
	well-behaved, because the standardization has become more strict
	and is better adhered to by the device manufacturers. 

	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
	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 seperate your older
	and newer (=faster) devices however.

    <sect2><heading>Components of SCSI</heading>
      <p>
<!--      <sect3><heading>A <it>smart</it> interface</heading>
        <p> -->
          As said before, SCSI devices are smart.  The idea is to put the
          knowledge about intimate hardware details onto the SCSI device
          itself.  In this way, the host system does not have to worry
          about things like how many heads are hard disks has, or how many
          tracks there are on a specific tape device.  If you are curious,
          the standard specifies commands with which you can query your
          devices on their hardware particulars. FreeBSD uses this
	  capability during boot to check out what devices are connected
	  and whether they need any special treatment.

          The advantage of intelligent devices is obvious: the device
          drivers on the host can be made in a much more generic fashion,
	  there is no longer a need to change (and qualify!) drivers for 
	  every odd new device that is introduced.

<!--      <sect3><heading>Do's and don't's on interconnections</heading>
        <p> -->
          For cabling and connectors there is a golden rule: get good
          stuff. With bus speeds going up all the time you will save
          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.

      <sect2><heading>SCSI bus types</heading>
        <p>
          From an electrical point of view, there are two incompatible bus
          types: single-ended and differential.  This means that there are
          two different main groups of SCSI devices and controllers, which
          cannot be mixed on the same bus.  It is possible however to use
          special converter hardware to transform a single-ended bus into a
          differential one (and vice versa).  The differences between the
          bus types are explained in the next sections.

          In lots of SCSI related documentation there is a sort of jargon
          in use to abbreviate the different bus types. A small list:

          <itemize>
            <item>FWD:	Fast Wide Differential
            <item>FND:	Fast Narrow Differential
            <item>SE:	Single Ended
            <item>FN:	Fast Narrow
            <item>etc.
          </itemize>

          With a minor amount of imagination one can usually imagine what
          is meant.
          
          Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As
          far as I know, the 32 bit variant is not (yet) in use, so wide
          normally means 16 bit.

          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 
	  (Fast-20 == Ultra SCSI and Fast-40 == Ultra2 SCSI). 

	  It should be noted that the data lines &gt; 8 are only used for
	  data transfers and device addressing. The transfers of commands
	  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
	    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 
	    the limits quite a bit, so you'll 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
            reading">) itself, connectors etc are listed there in
            painstaking detail.

	    Beware of devices using non-standard cabling. For instance
	    Apple uses a 25pin D-type connecter (like the one on serial
	    ports and parallel printers). Considering
	    that the official SCSI bus needs 50 pins you can imagine
	    the use of this connector needs some 'creative cabling'.
	    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
	    don't even think about buses like this..

        <sect3><heading>Differential buses</heading>
          <p>
            A differential SCSI bus has a maximum length of 25
            meters. Quite a difference from the 3 meters for a single-ended
            fast-SCSI bus. The idea behind differential signals is that
            each bus signal has its own return wire. So, each signal is
            carried on a (preferably twisted) pair of wires. The voltage
            difference between these two wires determines whether the
            signal is asserted or de-asserted. To a certain extent the
            voltage difference between ground and the signal wire pair is
            not relevant (do not try 10 kVolts though..).
            
            It is beyond the scope of this document to explain why this
            differential idea is so much better. Just accept that
            electrically seen the use of differential signals gives a much
            better noise margin. You will normally find differential buses
            in use for inter-cabinet connections. Because of the lower cost
            single ended is mostly used for shorter buses like inside
            cabinets.

	    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
	    AH1740 as a single ended board, whereas the AH1744 was differential.
	    The software interface to the host is identical for both.

        <sect3><heading>Terminators</heading>
          <p>
            Terminators in SCSI terminology are resistor networks that are
            used to get a correct impedance matching.  Impedance matching
            is important to get clean signals on the bus, without
            reflections or ringing.  If you once made a long distance
            telephone call on a bad line you probably know what reflections
            are.  With 20Mbytes/sec traveling over your SCSI bus, you
            do not want signals echoing back.

            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
            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
            reconfigure your SCSI bus.  There is enough variation in even
            these simple tiny things to make finding the exact replacement
            a frustrating business.  There are also SCSI devices that have
            a single jumper to enable or disable a built-in terminator.
            There are special terminators you can stick onto a flat cable
            bus.  Others look like external connectors, or a connector hood
            without a cable.  So, lots of choice as you can see.

            There is much debate going on if and when you should switch
            from simple resistor (passive) terminators to active
            terminators. Active terminators contain slightly more elaborate
            circuit to give cleaner bus signals. The general consensus
            seems to be that the usefulness of active termination increases
            when you have long buses and/or fast devices. If you ever have
	    problems with your SCSI buses you might consider trying an
	    active terminator. Try to borrow one first, they reputedly are
	    quite expensive.

            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
            the simplest..  The rule is: <bf>every 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.

            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
            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
            terminators, for both the Centronics-type external cabling and
            for the internal flat cable connectors. This makes
            reconfiguration much easier.
        
            On modern devices, sometimes integrated terminators are
            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
            configurable, using some sort of setup tool. Consult you
	    documentation!

        <sect3><heading>Terminator power</heading>
          <p>
            The terminators discussed in the previous chapter need power to
            operate properly.  On the SCSI bus, a line is dedicated to this
            purpose.  So, simple huh?

            Not so. Each device can provide its own terminator power to
            the terminator sockets it has on-device. But if you have
            external terminators, or when the device supplying the
            terminator power to the SCSI bus line is switched off you are
            in trouble.

            The idea is that initiators (these are devices that initiate
            actions on the bus, a discussion follows) must supply
            terminator power. All SCSI devices are allowed (but not
            required) to supply terminator power.

            To allow for un-powered devices on a bus, the terminator
            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
            must respond using a set of jumpers, or a dip switch, or
            something similar. 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
	    devices sharing the same ID sometimes even manages to answer
	    to I/O requests! 

            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
            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).

            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
            have LUN 0 for the tape device itself, and LUN 1 for the
            tape changer. In this way, the host system can address each of
            the functional units of the tape changer as desired.

        <sect3><heading>Bus layout</heading>
          <p>
            SCSI buses are linear. So, not shaped like Y-junctions, star
            topologies, cobwebs or whatever else people might want to
            invent.

            You might notice that the terminator issue discussed earlier
            becomes rather hairy if your bus is not linear..

            The electrical characteristics, its noise margins and
            ultimately the reliability of it all are tightly related to
            linear bus rule.

            <bf>Stick to the linear bus rule!</bf>

    <sect2><heading>Using SCSI with FreeBSD</heading>
      <p>
      <sect3><heading>About translations, BIOSes and magic...</heading>
        <p>
          As stated before, you should first make sure that you have a
          electrically sound bus.

          When you want to use a SCSI disk on your PC as boot disk, you
          must aware of some quirks related to PC BIOSes. The PC BIOS in
          its first incarnation used a low level physical interface to the
          hard disk. So, you had to tell the BIOS (using a setup tool or a
          BIOS built-in setup) how your disk physically looked like. This
          involved stating number of heads, number of cylinders, number of
          sectors per track, obscure things like precompensation and
          reduced write current cylinder etc.

          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
          <bf>translated</bf> drive. This means that a fake drive table is
          constructed that allows the PC to boot the drive.  This
          translation is often (but not always) done using a pseudo drive
          with 64 heads and 32 sectors per track. By varying the number of
          cylinders, the SCSI BIOS adapts to the actual drive size. It is
          useful to note that 32 * 64 / 2 = the size of your drive in
          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
          1 Gb. With disk capacities going up all the time this is causing
          problems.

          Fortunately, the solution is simple: just use another
          translation, e.g. with 128 heads instead of 32. In most cases new
          SCSI BIOS versions are available to upgrade older SCSI host
          adapters. Some newer adapters have an option, in the form of a
          jumper or software setup selection, to switch the translation the
          SCSI BIOS uses.

          It is very important that <bf>all</bf> operating systems on the
	  disk use the <bf>same translation</bf> to get the right idea about
	  where to find the relevant partitions. So, when installing
	  FreeBSD you must answer any questions about heads/cylinders
	  etc using the translated values your host adapter uses.

	  Failing to observe the translation issue might lead to
	  un-bootable systems or operating systems overwriting each
	  others partitions. Using fdisk you should be able to see
	  all partitions.

          You might have heard some talk of 'lying' devices?
	  Older FreeBSD kernels used to report the geometry
          of SCSI disks when booting. An example from one of my systems:

          <verb>
	aha0 targ 0 lun 0: <MICROP  1588-15MB1057404HSP4>
	sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512
          </verb>
          Newer kernels usually do not report this information.. e.g.
	  <verb>
	 (bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2
	 sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors)
	  </verb>

	  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.

      <sect3><heading>SCSI subsystem design</heading>
        <p>
          FreeBSD uses a layered SCSI subsystem. For each different
          controller card a device driver is written. This driver
          knows all the intimate details about the hardware it
          controls. The driver has a interface to the upper layers of the
          SCSI subsystem through which it receives its commands and
          reports back any status.

          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)
          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.

          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>
          Dependent on your hardware, the kernel configuration file must
          contain one or more lines describing your host adapter(s). 
	  This includes I/O addresses, interrupts etc. 
	  Consult the man page for your
          adapter driver to get more info. Apart from that, check out
	  /sys/i386/conf/LINT for an overview of a kernel config file.
	  LINT contains every possible option you can dream of. It
	  does <em>not</em> imply LINT will actually get you to a
	  working kernel at all.

	  Although it is probably stating the obvious: the kernel config
	  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.

          An example loosely based on the FreeBSD 2.0.5-Release kernel config 
	  file LINT with some added comments (between &lsqb;&rsqb;):

	  <verb>
		
# SCSI host adapters: `aha', `ahb', `aic', `bt', `nca'
#
# aha: Adaptec 154x
# ahb: Adaptec 174x
# ahc: Adaptec 274x/284x/294x
# aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!)
# bt: Most Buslogic controllers
# nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130
# 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;
controller	ahc0	at isa? bio irq ? vector ahcintr # port??? iomem?

&lsqb;For an Adaptec AHA174x controller&rsqb;
controller	ahb0	at isa? bio irq ? vector ahbintr

&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	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]
tape st1 at scbus0 target 6		[SCSI tape at target 6]
device cd0 at scbus?			[the first ever CDROM 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 
	  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
	  LUN specified on the corresponding bus. 

	  Wired down devices get 'first shot' at the unit numbers
	  so the first non 'wired down' device, is allocated the unit number 
	  one greater than the highest 'wired down' unit number 
	  for that kind of device.
	  So, if you had a SCSI tape at target ID 2 it would be
	  configured as st2, as the tape at target ID 6 is wired down
	  to unit number 1. Note that <em>wired down devices need not
	  be found</em>
	  to get their unit number. The unit number for a wired down device
	  is reserved for that device, even if it is turned off at boot
	  time. This allows the device to be turned on and brought
	  on-line at a later time, without rebooting. Notice that a device's
	  unit number has <em>no</em> relationship with its target ID on 
	  the SCSI bus.

	  Below is another example of a kernel config file as used by
	  FreeBSD version < 2.0.5. The difference with the first example is
          that devices are not 'wired down'. 'Wired down' means
          that you specify which SCSI target belongs to which device.

	  A kernel built to the config file below will attach 
	  the first SCSI disk it finds to sd0, the second disk to sd1
	  etc. If you ever removed or added a disk, all other devices
	  of the same type (disk in this case) would 'move around'.
	  This implies you have to change <tt>/etc/fstab</tt> each time.

	  Although the old style still works, you 
	  are <em>strongly</em> recommended to use this new feature.
	  It will save you a lot of grief whenever you shift your
	  hardware around on the SCSI buses. So, when you re-use
	  your old trusty config file after upgrading from a 
	  pre-FreeBSD2.0.5.R system check this out.

          <verb>
&lsqb;driver for Adaptec 174x&rsqb;
controller      ahb0    at isa? bio irq 11 vector ahbintr
&lsqb;for Adaptec 154x&rsqb;
controller      aha0    at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr
&lsqb;for Seagate ST01/02&rsqb;
controller      sea0    at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr
controller      scbus0

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;
device          cd0     #Only need one of these, the code dynamically grows
          </verb>

	
          Both examples support SCSI disks. If during boot more
          devices of a specific type (e.g. sd disks) are found than are
          configured in the booting kernel, the system will simply allocate
	  more devices, incrementing the unit number starting at the last
	  number 'wired down'. If there are no 'wired down' devices
	  then counting starts at unit 0.

          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.

      <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
	  specific target ID. This process is called device probing by the way.

	  To work around the 'slow response' problem, FreeBSD allows a 
	  tunable delay time
	  before the SCSI devices are probed following a SCSI bus reset.
	  You can set this delay time in your kernel configuration file
	  using a line like:

	  <verb>
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.
	  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>  
	  Although the SCSI standard tries to be complete and concise, it is
	  a complex standard and implementing things correctly is no easy task.
          Some vendors do a better job then others. 

	  This is exactly where the 'rogue' devices come into view. Rogues are
	  devices that are recognized by the FreeBSD kernel as behaving slightly
	  (...) non-standard. Rogue devices are reported by the kernel when
	  booting. An example for two of my cartridge tape units:
	
	 <verb>
Feb 25 21:03:34 yedi /386bsd: ahb0 targ 5 lun 0: <TANDBERG TDC 3600       -06:>
Feb 25 21:03:34 yedi /386bsd: st0: Tandberg tdc3600 is a known rogue

Mar 29 21:16:37 yedi /386bsd: aha0 targ 5 lun 0: <ARCHIVE VIPER 150  21247-005>
Mar 29 21:16:37 yedi /386bsd: st1: Archive  Viper 150 is a known rogue
	 </verb>

	  For instance, there are devices that respond to 
	  all LUNs on a certain target ID, even if they are actually only one
	  device. It is easy to see that the kernel might be fooled into 
	  believing that there are 8 LUNs at that particular target ID. The
	  confusion this causes is left as an exercise to the reader.

	  The SCSI subsystem of FreeBSD recognizes devices with bad habits by
	  looking at the INQUIRY response they send when probed. Because the
	  INQUIRY response also includes the version number of the device 
	  firmware, it is even possible that for different firmware versions
	  different workarounds are used. See e.g. /sys/scsi/st.c and
	  /sys/scsi/scsiconf.c for more info on how this is done.

	  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
	  that has to define which workaround is needed.

	  After you got your Mumbletech working, please send the required
	  workaround to the FreeBSD development team for inclusion in the
          next release of FreeBSD. Other Mumbletech owners will be grateful 
	  to you.

      <sect3><heading>Multiple LUN devices</heading>
        <p>  
	  In some cases you come across devices that use multiple
	  logical units (LUNs) on a single SCSI ID. In most cases
	  FreeBSD only probes devices for LUN 0. An example are
	  so called bridge boards that connect 2 non-SCSI harddisks
	  to a SCSI bus (e.g. an Emulex MD21 found in old Sun systems).

	  This means that any devices with LUNs != 0 are not normally
	  found during device probe on system boot. To work around this
	  problem you must add an apropriate entry in /sys/scsi/scsiconf.c
	  and rebuild your kernel.

	  Look for a struct that is initialised like below:
	  <verb>
	  {
                T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A",
                "mx1", SC_ONE_LU
          }
	  </verb>

	  For you Mumbletech BRIDGE2000 that has more than one LUN,
	  acts as a SCSI disk
	  and has firmware revision 123 you would add something like:

	  <verb>
	  {
                T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123",
                "sd", SC_MORE_LUS
          }
	  </verb>

	  The kernel on boot scans the inquiry data it receives against
	  the table and acts accordingly. See the source for more info.

      <sect3><heading>Tagged command queueing</heading>
        <p>  
	  Modern SCSI devices, particularly magnetic disks, support
	  what is called tagged command queuing (TCQ). 

	  In a nutshell, TCQ allows the device to have multiple I/O
	  requests outstanding at the same time. Because the device
	  is intelligent, it can optimise it's operations (like
  	  head positioning) based on it's own request queue. On 
	  SCSI devices like RAID (Redundant Array of Independent
	  Disks) arrays the TCQ function is indispensable to take
	  advantage of the device's inherent parallelism.

	  Each I/O request is uniquely identified by a 'tag' (hence
	  the name tagged command queuing) and this tag is used by 
          FreeBSD to see which I/O in the device drivers queue is
	  reported as complete by the device.

	  It should be noted however that TCQ requires device driver
	  support and that some devices implemented it 'not quite
	  right' in their firmware. This problem bit me once, and
 	  it leads to highly mysterious problems. In such cases,
	  try to disable TCQ.

      <sect3><heading>Busmaster host adapters</heading>
        <p>
	  Most, but not all, SCSI host adapters are bus mastering controllers.
	  This means that they can do I/O on their own without putting load onto
	  the host CPU for data movement.

	  This is of course an advantage for a multitasking operating system like
	  FreeBSD. It must be noted however that there might be some rough edges.

	  For instance an Adaptec 1542 controller can be set to use different
	  transfer speeds on the host bus (ISA or AT in this case). The controller
          is settable to different rates because not all motherboards can handle
	  the higher speeds. Problems like hangups, bad data etc might be the
	  result of using a higher data transfer rate then your motherboard
	  can stomach.

	  The solution is of course obvious: switch to a lower data transfer rate
	  and try if that works better. 

	  In the case of a Adaptec 1542, there is an option that can be put
	  into the kernel config file to allow dynamic determination of the
	  right, read: fastest feasible, transfer rate. This option is 
          disabled by default:

	  <verb>
options        "TUNE_1542"             #dynamic tune of bus DMA speed
	  </verb>
	  
	  Check the man pages for the host adapter that you use. Or better
	  still, use the ultimate documentation (read: driver source).

    <sect2><heading>Tracking down problems</heading>
      <p>
        The following list is an attempt to give a guideline for the most
        common SCSI problems and their solutions. It is by no means
        complete.

        <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>
            Check if all devices to be used are powered up. 
          <item>
            Make a minimal bus config with as little devices as possible.
          <item>
            If possible, configure your host adapter to use slow bus speeds.
	  <item>
 	    Disable tagged command queuing to make things as simple as
	    possible (for a NCR hostadapter based system see man
ncrcontrol)
          <item>
            If you can compile a kernel, make one with the SCSIDEBUG option,
	    and try accessing the device with debugging turned on for
	    that device. If your device does not even probe at startup,
	    you may have to define the address of the device that
	    is failing, and the desired debug level in
	    <tt>/sys/scsi/scsidebug.h</tt>.
	    If it probes but just does not work, you can use the
	    <tt>scsi(8)</tt> command to dynamically set a debug level to
	    it in a running kernel (if SCSIDEBUG is defined).
	    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>.
        </itemize>

    <sect2><heading>Further reading<label id="scsi:further-reading"></heading>
      <p>
        If you intend to do some serious SCSI hacking, you might want to
        have the official standard at hand:

        Approved American National Standards can be purchased from ANSI at
        11 West 42nd Street, 13th Floor, New York, NY 10036, Sales Dept:
        (212) 642-4900.  You can also buy many ANSI standards and most
        committee draft documents from Global Engineering Documents, 15
        Inverness Way East, Englewood, CO 80112-5704, Phone: (800)
        854-7179, Outside USA and Canada: (303) 792-2181, FAX: (303) 792-
        2192.

        Many X3T10 draft documents are available electronically on the SCSI
        BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site.

        Latest X3T10 committee documents are:
        <itemize>
<item>AT Attachment (ATA or IDE) &lsqb;X3.221-1994&rsqb; (<em>Approved</em>)
<item>ATA Extensions (ATA-2) &lsqb;X3T10/948D Rev 2i&rsqb;
<item>Enhanced Small Device Interface (ESDI) &lsqb;X3.170-1990/X3.170a-1991&rsqb;   (<em>Approved</em>)
<item>Small Computer System Interface - 2 (SCSI-2) &lsqb;X3.131-1994&rsqb; (<em>Approved</em>)
<item>SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM) 
                                   &lsqb;X3T10/792D Rev 11&rsqb;
        </itemize>
        Other publications that might provide you with additional information are:
<itemize>
<item>"SCSI: Understanding the Small Computer System Interface", written by NCR 
Corporation.  Available from: Prentice Hall, Englewood Cliffs, NJ, 07632
Phone: (201) 767-5937 ISBN 0-13-796855-8

<item>"Basics of SCSI", a SCSI tutorial written by Ancot Corporation
Contact Ancot for availability information at:
Phone: (415) 322-5322  Fax: (415) 322-0455

<item>"SCSI Interconnection Guide Book", an AMP publication (dated 4/93, Catalog 
65237) that lists the various SCSI connectors and suggests cabling schemes.  
Available from AMP at (800) 522-6752 or (717) 564-0100

<item>"Fast Track to SCSI", A Product Guide written by Fujitsu.
Available from: Prentice Hall, Englewood Cliffs, NJ, 07632
Phone: (201) 767-5937 ISBN 0-13-307000-X

<item>"The SCSI Bench Reference", "The SCSI Encyclopedia", and the "SCSI Tutor",
ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070
Phone: (408) 867-6642
        
<item>"Zadian SCSI Navigator" (quick ref. book) and "Discover the Power of SCSI" 
(First book along with a one-hour video and tutorial book), Zadian Software, 
Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800
        </itemize>

        On Usenet the newsgroups <htmlurl
        url="news:comp.periphs.scsi" name="comp.periphs.scsi">
        and <htmlurl url="news:comp.periphs" name="comp.periphs">
        are noteworthy places to look for more info. You can also
        find the SCSI-Faq there, which is posted periodically.

        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.