.\"	$NetBSD: scsi.4,v 1.32 2019/08/18 11:53:23 maya 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 August 18, 2019
.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 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 ,
.Xr scsictl 8
.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).