341 lines
8.4 KiB
Groff
341 lines
8.4 KiB
Groff
.\" $NetBSD: scsi.4,v 1.29 2008/04/13 04:03:23 dholland Exp $
|
|
.\" Copyright (c) 1996
|
|
.\" Julian Elischer <julian@freebsd.org>. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd July 26, 2006
|
|
.Dt SCSI 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm scsi ,
|
|
.Nm scsibus
|
|
.Nd Small Computer Systems Interface (SCSI) bus driver
|
|
.Sh SYNOPSIS
|
|
.Cd "scsibus* at scsi?"
|
|
.Cd "atapibus* at atapi?"
|
|
.Cd options SCSIDEBUG
|
|
.Cd options SCSIVERBOSE
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver is the top, machine-independent layer of the two-layer
|
|
software system that provides an interface for the
|
|
implementation of drivers to control various
|
|
.Tn SCSI
|
|
or
|
|
.Tn ATAPI
|
|
bus devices, and to use different
|
|
.Tn SCSI
|
|
bus host adapters or
|
|
.Tn EIDE
|
|
controllers.
|
|
.Tn SCSI
|
|
bus is capable of supporting a wide variety of peripherals, including
|
|
hard disks, removable disks,
|
|
.Tn CD-ROMs ,
|
|
scanners, tape drives, and other miscellaneous high-speed devices.
|
|
.Pp
|
|
The bottom layer is composed of the drivers for individual
|
|
.Tn EIDE
|
|
or
|
|
.Tn SCSI
|
|
bus controller chips (e.g. NCR 5380), accessed through various host bus
|
|
interfaces, including, but not limited to
|
|
.Tn PCI ,
|
|
.Tn ISA ,
|
|
.Tn Sbus ,
|
|
.Tn TURBOchannel ,
|
|
and
|
|
.Tn NuBus .
|
|
These individual devices are referred to as
|
|
.Qq host adaptors
|
|
in
|
|
.Tn SCSI
|
|
terminology,
|
|
because they connect the
|
|
.Tn SCSI
|
|
bus to the host computer.
|
|
.Pp
|
|
When
|
|
.Nx
|
|
probes the
|
|
.Tn SCSI
|
|
busses, it
|
|
.Qq attaches
|
|
any devices it finds to the appropriate drivers.
|
|
.Pp
|
|
.Bl -tag -compact -width "sd(4)"
|
|
.It Xr sd 4
|
|
hard disks
|
|
.It Xr cd 4
|
|
.Tn CD-ROM
|
|
drives
|
|
.It Xr st 4
|
|
tape drives
|
|
.It Xr ch 4
|
|
media changers
|
|
.It Xr ss 4
|
|
scanners
|
|
.El
|
|
.Pp
|
|
If no specific driver matches the device,
|
|
then
|
|
.Nm
|
|
attaches the device to the
|
|
.Xr uk 4
|
|
driver so that user level
|
|
.Tn SCSI
|
|
.Xr ioctl 2
|
|
calls may still be performed against the device. Currently, only
|
|
.Xr sd 4 ,
|
|
.Xr cd 4 ,
|
|
.Xr st 4
|
|
and
|
|
.Xr uk 4
|
|
can attach to an atapi bus.
|
|
.Pp
|
|
Please see the
|
|
.Xr intro 4
|
|
manual page to see which
|
|
.Tn SCSI
|
|
bus host adaptors are supported by
|
|
.Nx
|
|
on your computer system.
|
|
.Sh KERNEL CONFIGURATION
|
|
The
|
|
.Nm
|
|
software supports some
|
|
.Nx
|
|
kernel
|
|
.Xr config 1
|
|
options.
|
|
They are:
|
|
.Bl -tag -width SCSIVERBOSE
|
|
.It Dv SCSIDEBUG
|
|
Compile in a wide variety of
|
|
.Fn printf
|
|
statements that can be turned on by
|
|
.Xr ioctl 2 .
|
|
.It Dv SCSIVERBOSE
|
|
Enable additional and more descriptive error and status messages
|
|
from the
|
|
.Nm
|
|
software.
|
|
.El
|
|
.Pp
|
|
All devices and the
|
|
.Tn SCSI
|
|
busses support boot time allocation so that an upper number of
|
|
devices and controllers does not need to be configured.
|
|
.Pp
|
|
The devices are either
|
|
.Em wired
|
|
so they appear at a particular device unit number or
|
|
.Em counted
|
|
so that they appear as the next available unused unit number.
|
|
.Pp
|
|
To configure a driver in the kernel without wiring down the device use a
|
|
config line similar to
|
|
.Pp
|
|
.Cd "ch* at scsibus? target ? lun ?"
|
|
.Pp
|
|
to include the
|
|
.Xr ch 4
|
|
changer driver.
|
|
.Pp
|
|
To wire down a unit use a config line similar to
|
|
.Pp
|
|
.Cd "ch1 at scsibus0 target 4 lun 0"
|
|
.Pp
|
|
to assign changer 1 as the changer with
|
|
.Tn SCSI
|
|
ID 4, logical unit 0, on bus 0.
|
|
Individual
|
|
.Tn SCSI
|
|
busses can be wired down to specific controllers with a config line
|
|
similar to
|
|
.Pp
|
|
.Cd "scsibus0 at ahc0"
|
|
.Pp
|
|
which assigns
|
|
.Tn SCSI
|
|
bus 0 to the first unit using the
|
|
.Xr ahc 4
|
|
driver.
|
|
.Pp
|
|
When you have a mixture of wired down and counted devices then the counting
|
|
begins with the first non-wired down unit for a particular type.
|
|
That is, if you have a disk wired down as
|
|
.Pp
|
|
.Cd "sd1 at scsibus0 target 1 lun 0"
|
|
.Pp
|
|
then the first non-wired disk shall come on line as
|
|
.Em sd2 .
|
|
.Sh IOCTLS
|
|
There are a number of
|
|
.Xr ioctl 2
|
|
calls that work on any
|
|
.Tn SCSI
|
|
device.
|
|
They are defined in
|
|
.Pa sys/scsiio.h
|
|
and can be applied against any
|
|
.Tn SCSI
|
|
device that permits them.
|
|
For the tape, it must be applied against the control device.
|
|
See the manual page for each device type for more information about
|
|
how generic
|
|
.Tn SCSI
|
|
.Xr ioctl 2
|
|
calls may be applied to a specific device.
|
|
.Bl -tag -width DIOCSDINFO____
|
|
.It Dv SCIOCRESET
|
|
Reset a
|
|
.Tn SCSI
|
|
device.
|
|
.It Dv SCIOCDEBUG
|
|
Turn on debugging.
|
|
All
|
|
.Tn SCSI
|
|
operations originating from this device's driver
|
|
will be traced to the console, along with other information.
|
|
Debugging is controlled by four bits, described in the header file.
|
|
If no debugging is configured into the kernel, debugging will have
|
|
no effect.
|
|
.Tn SCSI
|
|
debugging is controlled by the configuration option
|
|
.Dv SCSIDEBUG .
|
|
.It Dv SCIOCCOMMAND
|
|
Take a
|
|
.Tn SCSI
|
|
command and data from a user process and apply them to the
|
|
.Tn SCSI
|
|
device.
|
|
Return all status information and return data to the process.
|
|
The
|
|
.Xr ioctl 2
|
|
call will return a successful status even if the device rejected the command.
|
|
As all status is returned to the user, it is up to the user
|
|
process to examine this information to decide the success of the command.
|
|
.It Dv SCIOCREPROBE
|
|
Ask the system to probe the
|
|
.Tn SCSI
|
|
busses for any new devices.
|
|
If it finds any, they will be attached to the appropriate drivers.
|
|
The search can be narrowed to a specific bus, target or Logical
|
|
Unit Number (LUN).
|
|
The new device may or may not be related to the device on which
|
|
the ioctl was performed.
|
|
.It Dv SCIOCIDENTIFY
|
|
Ask the driver what its bus, target and LUN are.
|
|
.It Dv SCIOCDECONFIG
|
|
Ask the device to disappear.
|
|
This may not happen if the device is in use.
|
|
.El
|
|
.Sh ADAPTERS
|
|
The system allows common device drivers to work through many different
|
|
types of adapters.
|
|
The adapters take requests from the upper layers and do all IO between the
|
|
.Tn SCSI
|
|
bus and the system.
|
|
The maximum size of a transfer is governed by the adapter.
|
|
Most adapters can transfer 64KB in a single operation, however
|
|
many can transfer larger amounts.
|
|
.Sh TARGET MODE
|
|
Some adapters support
|
|
.Em Target Mode
|
|
in which the system is capable of operating as a device, responding to
|
|
operations initiated by another system.
|
|
Target Mode will be supported for
|
|
some host adapters, but is not yet complete for this version of the
|
|
.Tn SCSI
|
|
system.
|
|
.Sh DIAGNOSTICS
|
|
When the kernel is compiled with option
|
|
.Dv SCSIDEBUG ,
|
|
the
|
|
.Dv SCIOCDEBUG
|
|
.Xr ioctl 2
|
|
can be used to enable various amounts of tracing information on any
|
|
specific device.
|
|
Devices not being traced will not produce trace information.
|
|
The four bits that make up the debug level, each control certain types
|
|
of debugging information.
|
|
.Bl -tag -width "Bit 0"
|
|
.It Dv Bit 0
|
|
shows all
|
|
.Tn SCSI
|
|
bus operations including
|
|
.Tn SCSI
|
|
commands,
|
|
error information and the first 48 bytes of any data transferred.
|
|
.It Dv Bit 1
|
|
shows routines called.
|
|
.It Dv Bit 2
|
|
shows information about what branches are taken and often some
|
|
of the return values of functions.
|
|
.It Dv Bit 3
|
|
shows more detailed information including
|
|
.Tn DMA
|
|
scatter-gather logs.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr config 1 ,
|
|
.Xr ioctl 2 ,
|
|
.Xr ata 4 ,
|
|
.Xr cd 4 ,
|
|
.Xr ch 4 ,
|
|
.Xr intro 4 ,
|
|
.Xr sd 4 ,
|
|
.Xr se 4 ,
|
|
.Xr ss 4 ,
|
|
.Xr st 4 ,
|
|
.Xr uk 4
|
|
.Sh HISTORY
|
|
This
|
|
.Nm
|
|
system appeared in MACH 2.5 at TRW.
|
|
.Pp
|
|
This man page was originally written by Julian Elischer
|
|
.Aq julian@freebsd.org
|
|
for
|
|
.Fx
|
|
and extensively modified by
|
|
.An Erik Fair
|
|
.Aq fair@NetBSD.org
|
|
for
|
|
.Nx .
|
|
.Sh BUGS
|
|
Not every device obeys the
|
|
.Tn SCSI
|
|
specification as faithfully as it should.
|
|
As such devices are discovered by the
|
|
.Nx
|
|
Project, their names are added to a
|
|
.Em quirk list
|
|
compiled into the
|
|
.Nm
|
|
driver along a list of flags indicating which particular bad behaviors the
|
|
device exhibits (and that the driver should be prepared to work around).
|