'\" te
.\" Copyright (c) 2008 Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SGEN 7D "Mar 29, 2008"
.SH NAME
sgen \- Generic SCSI device driver
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/scsi/targets/sgendef.h>\fR
.fi

.LP
.nf
\fBsgen@target,lun:<devtype>\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsgen\fR driver exports the \fBuscsi\fR(7I) interfaces to user processes.
The \fBsgen\fR driver can be configured to bind to \fBSCSI\fR devices for which
no system driver is available. Examples of such devices include \fBSCSI\fR
scanners and \fBSCSI\fR processor devices.
.SH SECURITY
.sp
.LP
Typically, drivers which export the \fBuscsi\fR(7I) interface unconditionally
require that the user present superuser credentials. The \fBsgen\fR driver does
not, and relies on the filesystem permissions on its device special file to
govern who may access that device. By default, access is restricted and device
nodes created by the \fBsgen\fR driver are readable and writable by the
superuser exclusively.
.sp
.LP
It is important to understand that \fBSCSI\fR devices coexisting on the same
\fBSCSI\fR bus may potentially interact with each other. This may result from
firmware bugs in \fBSCSI\fR devices, or may be made to happen programmatically
by sending appropriate \fBSCSI\fR commands to a device. Potentially, any
application controlling a device via the \fBsgen\fR driver can introduce data
integrity or security problems in that device or any other device sharing the
same \fBSCSI\fR bus.
.sp
.LP
Granting unprivileged users access to an \fBsgen\fR-controlled \fBSCSI\fR
device may create other   problems. It may be possible for a user to instruct a
target device to gather data from another target device on the same bus. It may
also be possible for malicious users to install new firmware onto a device to
which they are granted access. In environments where security is a concern but
user access to devices controlled by the \fBsgen\fR driver is nontheless
desired, it is recommended that the devices be separated onto a dedicated
\fBSCSI\fR bus to mitigate the risk of data corruption and security violations.
.SH CONFIGURATION
.sp
.LP
The \fBsgen\fR driver is configurable via the \fBsgen.conf\fR file. In addition
to standard \fBSCSI\fR device configuration directives (see \fBscsi\fR(4)),
administrators can set several additional properties for the \fBsgen\fR driver.
.sp
.LP
By default, the \fBsgen\fR driver will not claim or bind to any devices on the
system. To do so, it must be configured by the administrator using the
\fBinquiry-config-list\fR and/or the \fBdevice-type-config-list\fR properties.
.sp
.LP
As with other \fBSCSI\fR drivers, the \fBsgen.conf\fR configuration file
enumerates the targets  \fBsgen\fR should use. See \fBscsi\fR(4) for more
details. For each target enumerated in the \fBsgen.conf\fR file,  the
\fBsgen\fR driver sends a \fBSCSI INQUIRY\fR command to gather information
about the device present at that target. The \fBinquiry-config-list\fR property
specifies that the \fBsgen\fR driver should bind to a particular device
returning a particular set of inquiry data. The \fBdevice-type-config-list\fR
specifies that the \fBsgen\fR driver should bind to every device that is of a
particular \fBSCSI\fR device type. When examining the device, the \fBsgen\fR
driver tests to see if it matches an entry in the \fBdevice-type-config-list\fR
or the \fBinquiry-config-list\fR. For more detail on these two properties, see
the PROPERTIES section.
.sp
.LP
When a match against the \fBINQUIRY\fR data presented by a device is made,  the
\fBsgen\fR driver attaches to that device and creates a device node and link in
the \fB/devices\fR and \fB/dev\fR hierarchies. See the FILES section for more
information about how these files are named.
.sp
.LP
It is important for the administrator to ensure that devices claimed by the
\fBsgen\fR driver do not conflict with existing target drivers on the system.
For example, if  the \fBsgen\fR driver is configured to bind to a direct access
device, the standard \fBsd.conf\fR file will usually cause \fBsd\fR to claim
the device as well. This can cause unpredictable results. In general, the
\fBuscsi\fR(7I) interface exported by \fBsd\fR(7D) or \fBst\fR(7D) should be
used to gain access to direct access and sequential devices.
.sp
.LP
The \fBsgen\fR driver is disabled by default. The \fBsgen.conf\fR file is
shipped with all of the '\fBname="sgen" class="scsi" target=...\fR' entries
commented out to shorten boot time and to prevent the driver from consuming
kernel resources. To use  the \fBsgen\fR driver effectively on desktop systems,
simply uncomment all of the name="\fBsgen\fR" lines in \fBsgen.conf\fR file. On
larger systems with many \fBSCSI\fR controllers, carefully edit the
\fBsgen.conf\fR file so that \fBsgen\fR binds only where needed. Refer to
\fBdriver.conf\fR(4) for further details.
.SH PROPERTIES
.sp
.ne 2
.na
\fB\fBinquiry-config-list\fR\fR
.ad
.RS 23n
The \fBinquiry-config-list\fR property is a list of pairs of strings that
enumerates a list of specific devices to which the \fBsgen\fR driver will bind.
Each pair of strings is referred to as <\fBvendorid\fR, \fBproductid\fR> in the
discussion below.
.RE

.sp
.ne 2
.na
\fB\fBvendorid\fR\fR
.ad
.RS 12n
 is used to match the Vendor ID reported by the device. The \fBSCSI\fR
specification limits Vendor IDs to eight characters. Correspondingly, the
length of this string should not exceed eight characters. As a special case,
"\fB*\fR" may be used as a wildcard which matches any Vendor ID. This is useful
in situations where more than one vendor produces a particular model of a
product. \fBvendorid\fR is matched against the Vendor ID reported by the device
in a case-insensitive manner.
.RE

.sp
.ne 2
.na
\fB\fBproductid\fR\fR
.ad
.RS 13n
 is used to match the product ID reported by the device. The \fBSCSI\fR
specification limits product IDs to sixteen characters (unused characters are
filled with the whitespace characters).  Correspondingly, the length  of
\fBproductid\fR should not exceed sixteen characters.  When examining the
product ID of the device, \fBsgen\fR examines the length l of \fBproductid\fR
and performs a match against only the first l characters in the device's
product ID. \fBproductid\fR is matched against the product ID reported by the
device in a case-insensitive manner.
.RE

.sp
.LP
For example, to match some fictitious devices from ACME corp, the
\fBinquiry-config-list\fR can be configured as follows:
.sp

.sp
.TS
l l l
l l l .
\fBinquiry-config-list = \fR	\fB"ACME"\fR,	\fB"UltraToast 3000"\fR,
	\fB"ACME"\fR,	\fB"UltraToast 4000"\fR,
	 \fB"ACME"\fR,	\fB"UltraToast 5000"\fR;
.TE

.sp
.LP
To match "UltraToast 4000" devices, regardless of vendor,
\fBinquiry-config-list\fR is modified as follows:
.sp

.sp
.TS
l l l .
\fBinquiry-config-list = \fR	\fB"*",\fR	 \fB"UltraToast 4000"\fR;
.TE

.sp
.LP
To match every device from ACME in the "UltraToast" series (i.e UltraToast
3000, 4000, 5000, ...), \fB inquiry-config-list\fR is modified as follows:
.sp

.sp
.TS
l l l .
\fBinquiry-config-list = \fR	 \fB"ACME"\fR	\fB "UltraToast";\fR
.TE

.sp
.LP
Whitespace characters \fBare\fR significant when specifying \fBproductid\fR.
For example, a \fBproductid\fR of "UltraToast 1000" is fifteen characters in
length. If a device reported its ID as "UltraToast 10000", the \fBsgen\fR
driver would bind to it because only the first fifteen characters are
considered significant when matching. To remedy this situation, specify
\fBproductid\fR as "UltraToast 1000 ", (note trailing space).  This forces the
\fBsgen\fR driver to consider all sixteen characters in the product ID to be
significant.
.sp
.ne 2
.na
\fB\fBdevice-type-config-list\fR\fR
.ad
.RS 27n
The \fBdevice-type-config-list\fR property is a list of strings that enumerate
a list of device types to which the \fBsgen\fR driver will bind. The valid
device types correspond to those defined by the \fISCSI-3 SPC Draft Standard,
Rev. 11a\fR. These types are:
.RE

.sp

.sp
.TS
c | c
l | l .
Type Name	Inquiry Type ID
_
direct	 0x00
sequential	 0x01
printer 	 0x02
processor	 0x03
worm	 0x04
rodirect	 0x05
scanner 	 0x06
optical	 0x07
changer	 0x08
comm	 0x09
prepress1	 0x0a
prepress2	 0x0b
array_ctrl	 0x0c
ses	 0x0d
rbc	 0x0e
ocrw	 0x0f
bridge	 0x10
type_unknown	 0x1f
.TE

.sp
.LP
Alternately, you can specify device types  by \fBINQUIRY\fR type ID. To do
this, specify \fBtype_0x<typenum>\fR in the \fBsgen-config-list\fR. Case is not
significant when specifying device type names.
.sp
.ne 2
.na
\fB\fBsgen-diag\fR\fR
.ad
.RS 13n
The \fBsgen-diag\fR property sets the diagnostic output level. This property
can be set globally and/or per target/lun pair. \fBsgen-diag\fR is an integer
property, and can be set to 0, 1, 2 or 3. Illegal values will silently default
to 0. The meaning of each diagnostic level is as follows:
.RE

.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
No error reporting [default]
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
Report driver configuration information, unusual conditions, and indicate when
sense data has been returned from the device.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Trace the entry into and exit from routines inside the driver, and provide
extended diagnostic data. No error reporting [default].
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 5n
Provide detailed output about command characteristics, driver state, and the
contents of each CDB passed to the driver.
.RE

.sp
.LP
In ascending order, each level includes the diagnostics that the previous level
reports. See the IOCTLS section for more infomation on the \fBSGEN_IOC_DIAG\fR
ioctl.
.SH FILES
.sp
.ne 2
.na
\fB\fBsgen.conf\fR\fR
.ad
.RS 30n
Driver configuration file. See CONFIGURATION  for more details.
.RE

.sp
.ne 2
.na
\fB\fB/dev/scsi/<devtype>/c\fIn\fRt\fIn\fRd\fIn\fR\fR\fR
.ad
.RS 30n
The \fBsgen\fR driver categorizes each device in a separate directory by its
\fBSCSI\fR device type. The files inside the directory are named according to
their controller number, target ID and LUN as follows:
.sp
c\fIn\fR is the controller number, t\fIn\fR is the \fBSCSI\fR target id and
d\fIn\fR is the \fBSCSI\fR LUN
.sp
This is analogous to the {\fBcontroller;target;device\fR} naming scheme,  and
the controller numbers correspond to the same controller numbers which are used
for naming disks. For example, \fB/dev/dsk/c0t0d0s0\fR and
\fB/dev/scsi/scanner/c0t5d0\fR are both connected to controller \fBc0\fR.
.RE

.SH IOCTLS
.sp
.LP
The \fBsgen\fR driver exports the \fBuscsi\fR(7I) interface for each device it
manages. This allows a user process to talk directly to a \fBSCSI\fR device for
which there is no other driver installed in the system. Additionally,  the
\fBsgen\fR driver supports the following ioctls:
.sp
.ne 2
.na
\fB\fBSGEN_IOC_READY\fR\fR
.ad
.RS 18n
Send a \fBTEST UNIT READY\fR command to the device and return 0 upon success,
non-zero upon failure. This ioctl accepts no arguments.
.RE

.sp
.ne 2
.na
\fB\fBSGEN_IOC_DIAG\fR\fR
.ad
.RS 18n
Change the level of diagnostic reporting provided by the driver. This ioctl
accepts a single integer argument between 0 and 3. The levels have the same
meaning as in the \fBsgen-diag\fR property discussed in PROPERTIES above.
.RE

.SH ERRORS
.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
The device was opened by another  thread or process using the O_EXCL flag, or
the device is       currently open and O_EXCL is being requested.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
During opening, the device did not respond to a \fBTEST UNIT READY\fR
\fBSCSI\fR command.
.RE

.sp
.ne 2
.na
\fB\fBENOTTY\fR\fR
.ad
.RS 10n
Indicates that the device does  not  support the  requested ioctl function.
.RE

.SH EXAMPLES
.sp
.LP
Here is an example of how \fBsgen\fR can be configured to bind to scanner
devices on the system:
.sp
.LP
\fBdevice-type-config-list = "scanner";\fR
.sp
.LP
The administrator should subsequently uncomment the appropriate
\fBname="sgen"...\fR lines for the \fBSCSI\fR target ID to which the scanner
corresponds.  In this example, the scanner is at target 4.
.sp
.LP
\fBname= "sgen" class= "scsi" target=4 lun=0;\fR
.sp
.LP
If it is expected that the scanner will be moved from target to target over
time, or that more scanners might be added in the future, it is recommended
that all of the \fBname="sgen"...\fR lines be uncommented, so that \fBsgen\fR
checks all of the targets on the bus.
.sp
.LP
For large systems where boot times are a concern, it is recommended that the
\fBparent=""\fR property be used to specify which \fBSCSI\fR bus \fBsgen\fR
should examine.
.SH SEE ALSO
.sp
.LP
\fBdriver.conf\fR(4), \fBscsi\fR(4), \fBsd\fR(7D), \fBst\fR(7D),
\fBuscsi\fR(7I)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fIANSI Small Computer System Interface-2 (SCSI-2) \fR
.sp
.LP
\fISCSI-3 SPC Draft Standard, Rev. 11a\fR