'\" 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 \fR .fi .LP .nf \fBsgen@target,lun:\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\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//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