|
| sgen - Generic SCSI device driver |
SYNOPSIS
|
#include <sys/scsi/targets/sgendef.h>
|
|
sgen@target,lun:<devtype>
|
|
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 devices.
|
|
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 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 nontheless desired, it is recommended that the devices
be separated onto a dedicated SCSI bus to mitigate the
risk of data corruption and security violations.
|
|
The sgen driver is configurable via the sgen.conf file. In addition to standard SCSI
device configuration directives (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 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(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" 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(4)
for further details.
|
|
-
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 infomation
on the SGEN_IOC_DIAG ioctl.
|
|
-
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.
|
|
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 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.
|
|
-
EBUSY
- The device was opened by another thread or process. The driver maintains
a strict exclusive-open policy for each device.
-
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.
|
|
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.
|
| |