Tribblix: manual page: sgen.4d

SGEN(4D) Devices SGEN(4D)

NAME

sgen - Generic SCSI device driver

SYNOPSIS

#include <sys/scsi/targets/sgendef.h>

sgen@target,lun:<devtype>

DESCRIPTION

The sgen driver exports the uscsi(4I) interfaces to user processes.
The sgen driver can be configured to bind to SCSI devices for which
no system driver is available. Examples of such devices include SCSI
scanners and SCSI processor devices.

SECURITY

Typically, drivers which export the uscsi(4I) interface
unconditionally require that the user present superuser credentials.
The sgen 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 sgen
driver are readable and writable by the superuser exclusively.

It is important to understand that SCSI devices coexisting on the
same SCSI bus may potentially interact with each other. This may
result from firmware bugs in SCSI devices, or may be made to happen
programmatically by sending appropriate SCSI commands to a device.
Potentially, any application controlling a device via the sgen driver
can introduce data integrity or security problems in that device or
any other device sharing the same SCSI bus.

Granting unprivileged users access to an sgen-controlled SCSI 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 sgen driver is nonetheless desired, it is
recommended that the devices be separated onto a dedicated SCSI bus
to mitigate the risk of data corruption and security violations.

CONFIGURATION

The sgen driver is configurable via the sgen.conf file. In addition
to standard SCSI device configuration directives (see scsi(5)),
administrators can set several additional properties for the sgen
driver.

By default, the sgen driver will not claim or bind to any devices on
the system. To do so, it must be configured by the administrator
using the inquiry-config-list and/or the device-type-config-list
properties.

As with other SCSI drivers, the sgen.conf configuration file
enumerates the targets sgen should use. See scsi(5) for more
details. For each target enumerated in the sgen.conf file, the sgen
driver sends a SCSI INQUIRY command to gather information about the
device present at that target. The inquiry-config-list property
specifies that the sgen driver should bind to a particular device
returning a particular set of inquiry data. The device-type-config-
list specifies that the sgen driver should bind to every device that
is of a particular SCSI device type. When examining the device, the
sgen driver tests to see if it matches an entry in the device-type-
config-list or the inquiry-config-list. For more detail on these two
properties, see the PROPERTIES section.

When a match against the INQUIRY data presented by a device is made,
the sgen driver attaches to that device and creates a device node and
link in the /devices and /dev hierarchies. See the FILES section for
more information about how these files are named.

It is important for the administrator to ensure that devices claimed
by the sgen driver do not conflict with existing target drivers on
the system. For example, if the sgen driver is configured to bind
to a direct access device, the standard sd.conf file will usually
cause sd to claim the device as well. This can cause unpredictable
results. In general, the uscsi(4I) interface exported by sd(4D) or
st(4D) should be used to gain access to direct access and sequential
devices.

The sgen driver is disabled by default. The sgen.conf file is shipped
with all of the 'name="sgen" class="scsi" target=...' entries
commented out to shorten boot time and to prevent the driver from
consuming kernel resources. To use the sgen driver effectively on
desktop systems, simply uncomment all of the name="sgen" lines in
sgen.conf file. On larger systems with many SCSI controllers,
carefully edit the sgen.conf file so that sgen binds only where
needed. Refer to driver.conf(5) for further details.

PROPERTIES

inquiry-config-list
The inquiry-config-list property is a list of
pairs of strings that enumerates a list of
specific devices to which the sgen driver will
bind. Each pair of strings is referred to as
<vendorid, productid> in the discussion below.

vendorid
is used to match the Vendor ID reported by the device.
The SCSI specification limits Vendor IDs to eight
characters. Correspondingly, the length of this string
should not exceed eight characters. As a special case,
"*" 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. vendorid
is matched against the Vendor ID reported by the device
in a case-insensitive manner.

productid
is used to match the product ID reported by the device.
The SCSI specification limits product IDs to sixteen
characters (unused characters are filled with the
whitespace characters). Correspondingly, the length of
productid should not exceed sixteen characters. When
examining the product ID of the device, sgen examines
the length l of productid and performs a match against
only the first l characters in the device's product ID.
productid is matched against the product ID reported by
the device in a case-insensitive manner.

For example, to match some fictitious devices from ACME corp, the
inquiry-config-list can be configured as follows:

inquiry-config-list = "ACME", "UltraToast 3000",
"ACME", "UltraToast 4000",
"ACME", "UltraToast 5000";

To match "UltraToast 4000" devices, regardless of vendor, inquiry-
config-list is modified as follows:

inquiry-config-list = "*", "UltraToast 4000";

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

inquiry-config-list = "ACME" "UltraToast";

Whitespace characters are significant when specifying productid. For
example, a productid of "UltraToast 1000" is fifteen characters in
length. If a device reported its ID as "UltraToast 10000", the sgen
driver would bind to it because only the first fifteen characters are
considered significant when matching. To remedy this situation,
specify productid as "UltraToast 1000 ", (note trailing space). This
forces the sgen driver to consider all sixteen characters in the
product ID to be significant.

device-type-config-list
The device-type-config-list property is a
list of strings that enumerate a list of
device types to which the sgen driver will
bind. The valid device types correspond to
those defined by the SCSI-3 SPC Draft
Standard, Rev. 11a. These types are:

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

Alternately, you can specify device types by INQUIRY type ID. To do
this, specify type_0x<typenum> in the sgen-config-list. Case is not
significant when specifying device type names.

sgen-diag
The sgen-diag property sets the diagnostic output level.
This property can be set globally and/or per target/lun
pair. sgen-diag 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:

0
No error reporting [default]

1
Report driver configuration information, unusual conditions, and
indicate when sense data has been returned from the device.

2
Trace the entry into and exit from routines inside the driver,
and provide extended diagnostic data. No error reporting
[default].

3
Provide detailed output about command characteristics, driver
state, and the contents of each CDB passed to the driver.

In ascending order, each level includes the diagnostics that the
previous level reports. See the IOCTLS section for more information
on the SGEN_IOC_DIAG ioctl.

FILES

sgen.conf
Driver configuration file. See
CONFIGURATION for more details.

/dev/scsi/<devtype>/cntndn
The sgen driver categorizes each device
in a separate directory by its SCSI
device type. The files inside the
directory are named according to their
controller number, target ID and LUN as
follows:

cn is the controller number, tn is the
SCSI target id and dn is the SCSI LUN

This is analogous to the
{controller;target;device} naming
scheme, and the controller numbers
correspond to the same controller
numbers which are used for naming
disks. For example, /dev/dsk/c0t0d0s0
and /dev/scsi/scanner/c0t5d0 are both
connected to controller c0.

IOCTLS

The sgen driver exports the uscsi(4I) interface for each device it
manages. This allows a user process to talk directly to a SCSI device
for which there is no other driver installed in the system.
Additionally, the sgen driver supports the following ioctls:

SGEN_IOC_READY
Send a TEST UNIT READY command to the device and
return 0 upon success, non-zero upon failure. This
ioctl accepts no arguments.

SGEN_IOC_DIAG
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 sgen-diag property discussed in
PROPERTIES above.

ERRORS

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

ENXIO
During opening, the device did not respond to a TEST UNIT
READY SCSI command.

ENOTTY
Indicates that the device does not support the requested
ioctl function.

EXAMPLES

Here is an example of how sgen can be configured to bind to scanner
devices on the system:

device-type-config-list = "scanner";

The administrator should subsequently uncomment the appropriate
name="sgen"... lines for the SCSI target ID to which the scanner
corresponds. In this example, the scanner is at target 4.

name= "sgen" class= "scsi" target=4 lun=0;

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 name="sgen"... lines be
uncommented, so that sgen checks all of the targets on the bus.

For large systems where boot times are a concern, it is recommended
that the parent="" property be used to specify which SCSI bus sgen
should examine.