Devices sgen(7D)
NAME
sgen - Generic SCSI device driver
SYNOPSIS
#include
sgen@target,lun:
DESCRIPTION
The sgen driver exports the uscsi(7I) 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 dev-
ices.
SECURITY
Typically, drivers which export the uscsi(7I) 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 possi-
ble for malicious users to install new firmware onto a dev-
ice to which they are granted access. In environments where
security is a concern but user access to devices controlled
by the sgen driver is nontheless desired, it is recommended
that the devices be separated onto a dedicated SCSI bus to
mitigate the risk of data corruption and security viola-
tions.
CONFIGURATION
The sgen driver is configurable via the sgen.conf file. In
addition to standard SCSI device configuration directives
SunOS 5.11 Last change: 29 Mar 2008 1
Devices sgen(7D)
(see scsi(4)), 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(4) 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 par-
ticular 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(7I) interface exported by sd(7D) or
st(7D) 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" tar-
get=...' 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.
SunOS 5.11 Last change: 29 Mar 2008 2
Devices sgen(7D)
Refer to driver.conf(4) 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 in the dis-
cussion 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 charac-
ters. 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. ven-
dorid 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 pro-
duct IDs to sixteen characters (unused charac-
ters are filled with the whitespace charac-
ters). Correspondingly, the length of produc-
tid 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:
SunOS 5.11 Last change: 29 Mar 2008 3
Devices sgen(7D)
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 pro-
ductid. 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 pro-
perty 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
arrayctrl 0x0c
ses 0x0d
SunOS 5.11 Last change: 29 Mar 2008 4
Devices sgen(7D)
rbc 0x0e
ocrw 0x0f
bridge 0x10
typeunknown 0x1f
Alternately, you can specify device types by INQUIRY type
ID. To do this, specify type0x in the sgen-
config-list. Case is not significant when specifying device
type names.
sgen-diag The sgen-diag property sets the diagnostic out-
put 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 fol-
lows:
0 No error reporting [default]
1 Report driverconfiguration information, unusual condi-
tions, 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
infomation on the SGENIOCDIAG ioctl.
FILES
sgen.conf Driver configuration file. See
CONFIGURATION for more
details.
/dev/scsi//cntndn The sgen driver categorizes
each device in a separate
SunOS 5.11 Last change: 29 Mar 2008 5
Devices sgen(7D)
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 con-
troller 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(7I) 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 sup-
ports the following ioctls:
SGENIOCREADY Send a TEST UNIT READY command to the dev-
ice and return 0 upon success, non-zero
upon failure. This ioctl accepts no argu-
ments.
SGENIOCDIAG 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.
ERORS
EBUSY The device was opened by another thread or pro-
cess using the OEXCL flag, or the device is
currently open and OEXCL is being requested.
ENXIO During opening, the device did not respond to a
TEST UNIT READY SCSI command.
SunOS 5.11 Last change: 29 Mar 2008 6
Devices sgen(7D)
ENOTY 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.
SEE ALSO
driver.conf(4), scsi(4), sd(7D), st(7D), uscsi(7I)
Writing Device Drivers
ANSI Small Computer System Interface-2 (SCSI-2)
SCSI-3 SPC Draft Standard, Rev. 11a
SunOS 5.11 Last change: 29 Mar 2008 7
|
