| blob | dc2c9078f1cf06cb477033b2ab7e65fab6624eac |
1 '\" te
2 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH SGEN 7D "April 9, 2016"
7 .SH NAME
8 sgen \- Generic SCSI device driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include <sys/scsi/targets/sgendef.h>\fR
13 .fi
15 .LP
16 .nf
17 \fBsgen@target,lun:<devtype>\fR
18 .fi
20 .SH DESCRIPTION
21 .LP
22 The \fBsgen\fR driver exports the \fBuscsi\fR(7I) interfaces to user processes.
23 The \fBsgen\fR driver can be configured to bind to \fBSCSI\fR devices for which
24 no system driver is available. Examples of such devices include \fBSCSI\fR
25 scanners and \fBSCSI\fR processor devices.
26 .SH SECURITY
27 .LP
28 Typically, drivers which export the \fBuscsi\fR(7I) interface unconditionally
29 require that the user present superuser credentials. The \fBsgen\fR driver does
30 not, and relies on the filesystem permissions on its device special file to
31 govern who may access that device. By default, access is restricted and device
32 nodes created by the \fBsgen\fR driver are readable and writable by the
33 superuser exclusively.
34 .sp
35 .LP
36 It is important to understand that \fBSCSI\fR devices coexisting on the same
37 \fBSCSI\fR bus may potentially interact with each other. This may result from
38 firmware bugs in \fBSCSI\fR devices, or may be made to happen programmatically
39 by sending appropriate \fBSCSI\fR commands to a device. Potentially, any
40 application controlling a device via the \fBsgen\fR driver can introduce data
41 integrity or security problems in that device or any other device sharing the
42 same \fBSCSI\fR bus.
43 .sp
44 .LP
45 Granting unprivileged users access to an \fBsgen\fR-controlled \fBSCSI\fR
46 device may create other problems. It may be possible for a user to instruct a
47 target device to gather data from another target device on the same bus. It may
48 also be possible for malicious users to install new firmware onto a device to
49 which they are granted access. In environments where security is a concern but
50 user access to devices controlled by the \fBsgen\fR driver is nonetheless
51 desired, it is recommended that the devices be separated onto a dedicated
52 \fBSCSI\fR bus to mitigate the risk of data corruption and security violations.
53 .SH CONFIGURATION
54 .LP
55 The \fBsgen\fR driver is configurable via the \fBsgen.conf\fR file. In addition
56 to standard \fBSCSI\fR device configuration directives (see \fBscsi\fR(4)),
57 administrators can set several additional properties for the \fBsgen\fR driver.
58 .sp
59 .LP
60 By default, the \fBsgen\fR driver will not claim or bind to any devices on the
61 system. To do so, it must be configured by the administrator using the
62 \fBinquiry-config-list\fR and/or the \fBdevice-type-config-list\fR properties.
63 .sp
64 .LP
65 As with other \fBSCSI\fR drivers, the \fBsgen.conf\fR configuration file
66 enumerates the targets \fBsgen\fR should use. See \fBscsi\fR(4) for more
67 details. For each target enumerated in the \fBsgen.conf\fR file, the
68 \fBsgen\fR driver sends a \fBSCSI INQUIRY\fR command to gather information
69 about the device present at that target. The \fBinquiry-config-list\fR property
70 specifies that the \fBsgen\fR driver should bind to a particular device
71 returning a particular set of inquiry data. The \fBdevice-type-config-list\fR
72 specifies that the \fBsgen\fR driver should bind to every device that is of a
73 particular \fBSCSI\fR device type. When examining the device, the \fBsgen\fR
74 driver tests to see if it matches an entry in the \fBdevice-type-config-list\fR
75 or the \fBinquiry-config-list\fR. For more detail on these two properties, see
76 the PROPERTIES section.
77 .sp
78 .LP
79 When a match against the \fBINQUIRY\fR data presented by a device is made, the
80 \fBsgen\fR driver attaches to that device and creates a device node and link in
81 the \fB/devices\fR and \fB/dev\fR hierarchies. See the FILES section for more
82 information about how these files are named.
83 .sp
84 .LP
85 It is important for the administrator to ensure that devices claimed by the
86 \fBsgen\fR driver do not conflict with existing target drivers on the system.
87 For example, if the \fBsgen\fR driver is configured to bind to a direct access
88 device, the standard \fBsd.conf\fR file will usually cause \fBsd\fR to claim
89 the device as well. This can cause unpredictable results. In general, the
90 \fBuscsi\fR(7I) interface exported by \fBsd\fR(7D) or \fBst\fR(7D) should be
91 used to gain access to direct access and sequential devices.
92 .sp
93 .LP
94 The \fBsgen\fR driver is disabled by default. The \fBsgen.conf\fR file is
95 shipped with all of the '\fBname="sgen" class="scsi" target=...\fR' entries
96 commented out to shorten boot time and to prevent the driver from consuming
97 kernel resources. To use the \fBsgen\fR driver effectively on desktop systems,
98 simply uncomment all of the name="\fBsgen\fR" lines in \fBsgen.conf\fR file. On
99 larger systems with many \fBSCSI\fR controllers, carefully edit the
100 \fBsgen.conf\fR file so that \fBsgen\fR binds only where needed. Refer to
101 \fBdriver.conf\fR(4) for further details.
102 .SH PROPERTIES
103 .ne 2
104 .na
105 \fB\fBinquiry-config-list\fR\fR
106 .ad
107 .RS 23n
108 The \fBinquiry-config-list\fR property is a list of pairs of strings that
109 enumerates a list of specific devices to which the \fBsgen\fR driver will bind.
110 Each pair of strings is referred to as <\fBvendorid\fR, \fBproductid\fR> in the
111 discussion below.
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB\fBvendorid\fR\fR
118 .ad
119 .RS 12n
120 is used to match the Vendor ID reported by the device. The \fBSCSI\fR
121 specification limits Vendor IDs to eight characters. Correspondingly, the
122 length of this string should not exceed eight characters. As a special case,
123 "\fB*\fR" may be used as a wildcard which matches any Vendor ID. This is useful
124 in situations where more than one vendor produces a particular model of a
125 product. \fBvendorid\fR is matched against the Vendor ID reported by the device
126 in a case-insensitive manner.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fBproductid\fR\fR
133 .ad
134 .RS 13n
135 is used to match the product ID reported by the device. The \fBSCSI\fR
136 specification limits product IDs to sixteen characters (unused characters are
137 filled with the whitespace characters). Correspondingly, the length of
138 \fBproductid\fR should not exceed sixteen characters. When examining the
139 product ID of the device, \fBsgen\fR examines the length l of \fBproductid\fR
140 and performs a match against only the first l characters in the device's
141 product ID. \fBproductid\fR is matched against the product ID reported by the
142 device in a case-insensitive manner.
143 .RE
145 .sp
146 .LP
147 For example, to match some fictitious devices from ACME corp, the
148 \fBinquiry-config-list\fR can be configured as follows:
149 .sp
151 .sp
152 .TS
153 l l l
154 l l l .
155 \fBinquiry-config-list = \fR \fB"ACME"\fR, \fB"UltraToast 3000"\fR,
156 \fB"ACME"\fR, \fB"UltraToast 4000"\fR,
157 \fB"ACME"\fR, \fB"UltraToast 5000"\fR;
158 .TE
160 .sp
161 .LP
162 To match "UltraToast 4000" devices, regardless of vendor,
163 \fBinquiry-config-list\fR is modified as follows:
164 .sp
166 .sp
167 .TS
168 l l l .
169 \fBinquiry-config-list = \fR \fB"*",\fR \fB"UltraToast 4000"\fR;
170 .TE
172 .sp
173 .LP
174 To match every device from ACME in the "UltraToast" series (i.e UltraToast
175 3000, 4000, 5000, ...), \fB inquiry-config-list\fR is modified as follows:
176 .sp
178 .sp
179 .TS
180 l l l .
181 \fBinquiry-config-list = \fR \fB"ACME"\fR \fB "UltraToast";\fR
182 .TE
184 .sp
185 .LP
186 Whitespace characters \fBare\fR significant when specifying \fBproductid\fR.
187 For example, a \fBproductid\fR of "UltraToast 1000" is fifteen characters in
188 length. If a device reported its ID as "UltraToast 10000", the \fBsgen\fR
189 driver would bind to it because only the first fifteen characters are
190 considered significant when matching. To remedy this situation, specify
191 \fBproductid\fR as "UltraToast 1000 ", (note trailing space). This forces the
192 \fBsgen\fR driver to consider all sixteen characters in the product ID to be
193 significant.
194 .sp
195 .ne 2
196 .na
197 \fB\fBdevice-type-config-list\fR\fR
198 .ad
199 .RS 27n
200 The \fBdevice-type-config-list\fR property is a list of strings that enumerate
201 a list of device types to which the \fBsgen\fR driver will bind. The valid
202 device types correspond to those defined by the \fISCSI-3 SPC Draft Standard,
203 Rev. 11a\fR. These types are:
204 .RE
206 .sp
208 .sp
209 .TS
210 c | c
211 l | l .
212 Type Name Inquiry Type ID
213 _
214 direct 0x00
215 sequential 0x01
216 printer 0x02
217 processor 0x03
218 worm 0x04
219 rodirect 0x05
220 scanner 0x06
221 optical 0x07
222 changer 0x08
223 comm 0x09
224 prepress1 0x0a
225 prepress2 0x0b
226 array_ctrl 0x0c
227 ses 0x0d
228 rbc 0x0e
229 ocrw 0x0f
230 bridge 0x10
231 type_unknown 0x1f
232 .TE
234 .sp
235 .LP
236 Alternately, you can specify device types by \fBINQUIRY\fR type ID. To do
237 this, specify \fBtype_0x<typenum>\fR in the \fBsgen-config-list\fR. Case is not
238 significant when specifying device type names.
239 .sp
240 .ne 2
241 .na
242 \fB\fBsgen-diag\fR\fR
243 .ad
244 .RS 13n
245 The \fBsgen-diag\fR property sets the diagnostic output level. This property
246 can be set globally and/or per target/lun pair. \fBsgen-diag\fR is an integer
247 property, and can be set to 0, 1, 2 or 3. Illegal values will silently default
248 to 0. The meaning of each diagnostic level is as follows:
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fB0\fR\fR
255 .ad
256 .RS 5n
257 No error reporting [default]
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fB1\fR\fR
264 .ad
265 .RS 5n
266 Report driver configuration information, unusual conditions, and indicate when
267 sense data has been returned from the device.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fB2\fR\fR
274 .ad
275 .RS 5n
276 Trace the entry into and exit from routines inside the driver, and provide
277 extended diagnostic data. No error reporting [default].
278 .RE
280 .sp
281 .ne 2
282 .na
283 \fB\fB3\fR\fR
284 .ad
285 .RS 5n
286 Provide detailed output about command characteristics, driver state, and the
287 contents of each CDB passed to the driver.
288 .RE
290 .sp
291 .LP
292 In ascending order, each level includes the diagnostics that the previous level
293 reports. See the IOCTLS section for more information on the \fBSGEN_IOC_DIAG\fR
294 ioctl.
295 .SH FILES
296 .ne 2
297 .na
298 \fB\fBsgen.conf\fR\fR
299 .ad
300 .RS 30n
301 Driver configuration file. See CONFIGURATION for more details.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fB/dev/scsi/<devtype>/c\fIn\fRt\fIn\fRd\fIn\fR\fR\fR
308 .ad
309 .RS 30n
310 The \fBsgen\fR driver categorizes each device in a separate directory by its
311 \fBSCSI\fR device type. The files inside the directory are named according to
312 their controller number, target ID and LUN as follows:
313 .sp
314 c\fIn\fR is the controller number, t\fIn\fR is the \fBSCSI\fR target id and
315 d\fIn\fR is the \fBSCSI\fR LUN
316 .sp
317 This is analogous to the {\fBcontroller;target;device\fR} naming scheme, and
318 the controller numbers correspond to the same controller numbers which are used
319 for naming disks. For example, \fB/dev/dsk/c0t0d0s0\fR and
320 \fB/dev/scsi/scanner/c0t5d0\fR are both connected to controller \fBc0\fR.
321 .RE
323 .SH IOCTLS
324 .LP
325 The \fBsgen\fR driver exports the \fBuscsi\fR(7I) interface for each device it
326 manages. This allows a user process to talk directly to a \fBSCSI\fR device for
327 which there is no other driver installed in the system. Additionally, the
328 \fBsgen\fR driver supports the following ioctls:
329 .sp
330 .ne 2
331 .na
332 \fB\fBSGEN_IOC_READY\fR\fR
333 .ad
334 .RS 18n
335 Send a \fBTEST UNIT READY\fR command to the device and return 0 upon success,
336 non-zero upon failure. This ioctl accepts no arguments.
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fBSGEN_IOC_DIAG\fR\fR
343 .ad
344 .RS 18n
345 Change the level of diagnostic reporting provided by the driver. This ioctl
346 accepts a single integer argument between 0 and 3. The levels have the same
347 meaning as in the \fBsgen-diag\fR property discussed in PROPERTIES above.
348 .RE
350 .SH ERRORS
351 .ne 2
352 .na
353 \fB\fBEBUSY\fR\fR
354 .ad
355 .RS 10n
356 The device was opened by another thread or process using the O_EXCL flag, or
357 the device is currently open and O_EXCL is being requested.
358 .RE
360 .sp
361 .ne 2
362 .na
363 \fB\fBENXIO\fR\fR
364 .ad
365 .RS 10n
366 During opening, the device did not respond to a \fBTEST UNIT READY\fR
367 \fBSCSI\fR command.
368 .RE
370 .sp
371 .ne 2
372 .na
373 \fB\fBENOTTY\fR\fR
374 .ad
375 .RS 10n
376 Indicates that the device does not support the requested ioctl function.
377 .RE
379 .SH EXAMPLES
380 .LP
381 Here is an example of how \fBsgen\fR can be configured to bind to scanner
382 devices on the system:
383 .sp
384 .LP
385 \fBdevice-type-config-list = "scanner";\fR
386 .sp
387 .LP
388 The administrator should subsequently uncomment the appropriate
389 \fBname="sgen"...\fR lines for the \fBSCSI\fR target ID to which the scanner
390 corresponds. In this example, the scanner is at target 4.
391 .sp
392 .LP
393 \fBname= "sgen" class= "scsi" target=4 lun=0;\fR
394 .sp
395 .LP
396 If it is expected that the scanner will be moved from target to target over
397 time, or that more scanners might be added in the future, it is recommended
398 that all of the \fBname="sgen"...\fR lines be uncommented, so that \fBsgen\fR
399 checks all of the targets on the bus.
400 .sp
401 .LP
402 For large systems where boot times are a concern, it is recommended that the
403 \fBparent=""\fR property be used to specify which \fBSCSI\fR bus \fBsgen\fR
404 should examine.
405 .SH SEE ALSO
406 .LP
407 \fBdriver.conf\fR(4), \fBscsi\fR(4), \fBsd\fR(7D), \fBst\fR(7D),
408 \fBuscsi\fR(7I)
409 .sp
410 .LP
411 \fIWriting Device Drivers\fR
412 .sp
413 .LP
414 \fIANSI Small Computer System Interface-2 (SCSI-2) \fR
415 .sp
416 .LP
417 \fISCSI-3 SPC Draft Standard, Rev. 11a\fR