1sgen(7D) Devices sgen(7D)
2
6 sgen - Generic SCSI device driver
7
9 #include <sys/scsi/targets/sgendef.h>
10 sgen@target,lun:<devtype>
13
16 The sgen driver exports the uscsi(7I) interfaces to user processes. The
17 sgen driver can be configured to bind to SCSI devices for which no sys‐
18 tem driver is available. Examples of such devices include SCSI scanners
19 and SCSI processor devices.
20
22 Typically, drivers which export the uscsi(7I) interface unconditionally
23 require that the user present superuser credentials. The sgen driver
24 does not, and relies on the filesystem permissions on its device spe‐
25 cial file to govern who may access that device. By default, access is
26 restricted and device nodes created by the sgen driver are readable and
27 writable by the superuser exclusively.
28 It is important to understand that SCSI devices coexisting on the same
31 SCSI bus may potentially interact with each other. This may result from
32 firmware bugs in SCSI devices, or may be made to happen programmati‐
33 cally by sending appropriate SCSI commands to a device. Potentially,
34 any application controlling a device via the sgen driver can introduce
35 data integrity or security problems in that device or any other device
36 sharing the same SCSI bus.
37 Granting unprivileged users access to an sgen-controlled SCSI device
40 may create other problems. It may be possible for a user to instruct
41 a target device to gather data from another target device on the same
42 bus. It may also be possible for malicious users to install new
43 firmware onto a device to which they are granted access. In environ‐
44 ments where security is a concern but user access to devices controlled
45 by the sgen driver is nontheless desired, it is recommended that the
46 devices be separated onto a dedicated SCSI bus to mitigate the risk of
47 data corruption and security violations.
48
50 The sgen driver is configurable via the sgen.conf file. In addition to
51 standard SCSI device configuration directives (see scsi(4)), adminis‐
52 trators can set several additional properties for the sgen driver.
53 By default, the sgen driver will not claim or bind to any devices on
56 the system. To do so, it must be configured by the administrator using
57 the inquiry-config-list and/or the device-type-config-list properties.
58 As with other SCSI drivers, the sgen.conf configuration file enumerates
61 the targets sgen should use. See scsi(4) for more details. For each
62 target enumerated in the sgen.conf file, the sgen driver sends a SCSI
63 INQUIRY command to gather information about the device present at that
64 target. The inquiry-config-list property specifies that the sgen driver
65 should bind to a particular device returning a particular set of
66 inquiry data. The device-type-config-list specifies that the sgen
67 driver should bind to every device that is of a particular SCSI device
68 type. When examining the device, the sgen driver tests to see if it
69 matches an entry in the device-type-config-list or the inquiry-config-
70 list. For more detail on these two properties, see the PROPERTIES sec‐
71 tion.
72 When a match against the INQUIRY data presented by a device is made,
75 the sgen driver attaches to that device and creates a device node and
76 link in the /devices and /dev hierarchies. See the FILES section for
77 more information about how these files are named.
78 It is important for the administrator to ensure that devices claimed by
81 the sgen driver do not conflict with existing target drivers on the
82 system. For example, if the sgen driver is configured to bind to a
83 direct access device, the standard sd.conf file will usually cause sd
84 to claim the device as well. This can cause unpredictable results. In
85 general, the uscsi(7I) interface exported by sd(7D) or st(7D) should be
86 used to gain access to direct access and sequential devices.
87 The sgen driver is disabled by default. The sgen.conf file is shipped
90 with all of the 'name="sgen" class="scsi" target=...' entries commented
91 out to shorten boot time and to prevent the driver from consuming ker‐
92 nel resources. To use the sgen driver effectively on desktop systems,
93 simply uncomment all of the name="sgen" lines in sgen.conf file. On
94 larger systems with many SCSI controllers, carefully edit the sgen.conf
95 file so that sgen binds only where needed. Refer to driver.conf(4) for
96 further details.
97
99 inquiry-config-list The inquiry-config-list property is a list of
100 pairs of strings that enumerates a list of spe‐
101 cific devices to which the sgen driver will
102 bind. Each pair of strings is referred to as
103 <vendorid, productid> in the discussion below.
104 vendorid is used to match the Vendor ID reported by the device. The
107 SCSI specification limits Vendor IDs to eight characters.
108 Correspondingly, the length of this string should not
109 exceed eight characters. As a special case, "*" may be used
110 as a wildcard which matches any Vendor ID. This is useful
111 in situations where more than one vendor produces a partic‐
112 ular model of a product. vendorid is matched against the
113 Vendor ID reported by the device in a case-insensitive man‐
114 ner.
115 productid is used to match the product ID reported by the device.
118 The SCSI specification limits product IDs to sixteen char‐
119 acters (unused characters are filled with the whitespace
120 characters). Correspondingly, the length of productid
121 should not exceed sixteen characters. When examining the
122 product ID of the device, sgen examines the length l of
123 productid and performs a match against only the first l
124 characters in the device's product ID. productid is
125 matched against the product ID reported by the device in a
126 case-insensitive manner.
127 For example, to match some fictitious devices from ACME corp, the
131 inquiry-config-list can be configured as follows:
132 inquiry-config-list = "ACME", "UltraToast 3000",
137 "ACME", "UltraToast 4000",
138 "ACME", "UltraToast 5000";
139 To match "UltraToast 4000" devices, regardless of vendor, inquiry-con‐
143 fig-list is modified as follows:
144 inquiry-config-list = "*", "UltraToast 4000";
149 To match every device from ACME in the "UltraToast" series (i.e Ultra‐
153 Toast 3000, 4000, 5000, ...), inquiry-config-list is modified as fol‐
154 lows:
155 inquiry-config-list = "ACME" "UltraToast";
160 Whitespace characters are significant when specifying productid. For
164 example, a productid of "UltraToast 1000" is fifteen characters in
165 length. If a device reported its ID as "UltraToast 10000", the sgen
166 driver would bind to it because only the first fifteen characters are
167 considered significant when matching. To remedy this situation, specify
168 productid as "UltraToast 1000 ", (note trailing space). This forces
169 the sgen driver to consider all sixteen characters in the product ID to
170 be significant.
171 device-type-config-list The device-type-config-list property is a
173 list of strings that enumerate a list of
174 device types to which the sgen driver will
175 bind. The valid device types correspond to
176 those defined by the SCSI-3 SPC Draft Stan‐
177 dard, Rev. 11a. These types are:
178 │
183 Type Name │ Inquiry Type ID
184 ───────────────────┼───────────────────────────────────────
185 direct │ 0x00
186 sequential │ 0x01
187 printer │ 0x02
188 processor │ 0x03
189 worm │ 0x04
190 rodirect │ 0x05
191 scanner │ 0x06
192 optical │ 0x07
193 changer │ 0x08
194 comm │ 0x09
195 prepress1 │ 0x0a
196 prepress2 │ 0x0b
197 array_ctrl │ 0x0c
198 ses │ 0x0d
200 rbc │ 0x0e
201 ocrw │ 0x0f
202 bridge │ 0x10
203 type_unknown │ 0x1f
204 Alternately, you can specify device types by INQUIRY type ID. To do
208 this, specify type_0x<typenum> in the sgen-config-list. Case is not
209 significant when specifying device type names.
210 sgen-diag The sgen-diag property sets the diagnostic output level.
212 This property can be set globally and/or per target/lun
213 pair. sgen-diag is an integer property, and can be set to
214 0, 1, 2 or 3. Illegal values will silently default to 0.
215 The meaning of each diagnostic level is as follows:
216 0 No error reporting [default]
219 1 Report driver configuration information, unusual conditions, and
222 indicate when sense data has been returned from the device.
223 2 Trace the entry into and exit from routines inside the driver, and
226 provide extended diagnostic data. No error reporting [default].
227 3 Provide detailed output about command characteristics, driver
230 state, and the contents of each CDB passed to the driver.
231 In ascending order, each level includes the diagnostics that the previ‐
235 ous level reports. See the IOCTLS section for more infomation on the
236 SGEN_IOC_DIAG ioctl.
237
239 sgen.conf Driver configuration file. See CONFIGURA‐
240 TION for more details.
241 /dev/scsi/<devtype>/cntndn The sgen driver categorizes each device
244 in a separate directory by its SCSI
245 device type. The files inside the direc‐
246 tory are named according to their con‐
247 troller number, target ID and LUN as fol‐
248 lows:
249 cn is the controller number, tn is the
251 SCSI target id and dn is the SCSI LUN
252 This is analogous to the {controller;tar‐
254 get;device} naming scheme, and the con‐
255 troller numbers correspond to the same
256 controller numbers which are used for
257 naming disks. For example,
258 /dev/dsk/c0t0d0s0 and /dev/scsi/scan‐
259 ner/c0t5d0 are both connected to con‐
260 troller c0.
261
264 The sgen driver exports the uscsi(7I) interface for each device it man‐
265 ages. This allows a user process to talk directly to a SCSI device for
266 which there is no other driver installed in the system. Additionally,
267 the sgen driver supports the following ioctls:
268 SGEN_IOC_READY Send a TEST UNIT READY command to the device and
270 return 0 upon success, non-zero upon failure. This
271 ioctl accepts no arguments.
272 SGEN_IOC_DIAG Change the level of diagnostic reporting provided by
275 the driver. This ioctl accepts a single integer argu‐
276 ment between 0 and 3. The levels have the same mean‐
277 ing as in the sgen-diag property discussed in PROPER‐
278 TIES above.
279
282 EBUSY The device was opened by another thread or process using the
283 O_EXCL flag, or the device is currently open and O_EXCL
284 is being requested.
285 ENXIO During opening, the device did not respond to a TEST UNIT
288 READY SCSI command.
289 ENOTTY Indicates that the device does not support the requested
292 ioctl function.
293
296 Here is an example of how sgen can be configured to bind to scanner
297 devices on the system:
298 device-type-config-list = "scanner";
301 The administrator should subsequently uncomment the appropriate
304 name="sgen"... lines for the SCSI target ID to which the scanner corre‐
305 sponds. In this example, the scanner is at target 4.
306 name= "sgen" class= "scsi" target=4 lun=0;
309 If it is expected that the scanner will be moved from target to target
312 over time, or that more scanners might be added in the future, it is
313 recommended that all of the name="sgen"... lines be uncommented, so
314 that sgen checks all of the targets on the bus.
315 For large systems where boot times are a concern, it is recommended
318 that the parent="" property be used to specify which SCSI bus sgen
319 should examine.
320
322 driver.conf(4), scsi(4), sd(7D), st(7D), uscsi(7I)
323 Writing Device Drivers
326 ANSI Small Computer System Interface-2 (SCSI-2)
329 SCSI-3 SPC Draft Standard, Rev. 11a
332SunOS 5.11 29 Mar 2008 sgen(7D)