1sgen(7D)                            Devices                           sgen(7D)
2
3
4

NAME

6       sgen - Generic SCSI device driver
7

SYNOPSIS

9       #include <sys/scsi/targets/sgendef.h>
10
11
12       sgen@target,lun:<devtype>
13
14

DESCRIPTION

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

SECURITY

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
29
30       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
38
39       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

CONFIGURATION

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
54
55       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
59
60       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
73
74       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
79
80       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
88
89       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

PROPERTIES

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
105
106       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
116
117       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
128
129
130       For  example,  to  match  some  fictitious  devices from ACME corp, the
131       inquiry-config-list can be configured as follows:
132
133
134
135
136       inquiry-config-list =    "ACME",       "UltraToast 3000",
137                                "ACME",       "UltraToast 4000",
138                                 "ACME",      "UltraToast 5000";
139
140
141
142       To match "UltraToast 4000" devices, regardless of vendor,  inquiry-con‐
143       fig-list is modified as follows:
144
145
146
147
148       inquiry-config-list =    "*",           "UltraToast 4000";
149
150
151
152       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
156
157
158
159       inquiry-config-list =     "ACME"      "UltraToast";
160
161
162
163       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
172       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
179
180
181
182
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
199       ses                │ 0x0d
200       rbc                │ 0x0e
201       ocrw               │ 0x0f
202       bridge             │ 0x10
203       type_unknown       │ 0x1f
204
205
206
207       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
211       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
217
218       0    No error reporting [default]
219
220
221       1    Report  driver  configuration information, unusual conditions, and
222            indicate when sense data has been returned from the device.
223
224
225       2    Trace the entry into and exit from routines inside the driver, and
226            provide extended diagnostic data. No error reporting [default].
227
228
229       3    Provide  detailed  output  about  command  characteristics, driver
230            state, and the contents of each CDB passed to the driver.
231
232
233
234       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

FILES

239       sgen.conf                     Driver configuration file. See CONFIGURA‐
240                                     TION  for more details.
241
242
243       /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
250                                     cn is the controller number,  tn  is  the
251                                     SCSI target id and dn is the SCSI LUN
252
253                                     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
262

IOCTLS

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
269       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
273
274       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
280

ERRORS

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
286
287       ENXIO     During  opening,  the  device  did not respond to a TEST UNIT
288                 READY SCSI command.
289
290
291       ENOTTY    Indicates that the device does  not  support  the   requested
292                 ioctl function.
293
294

EXAMPLES

296       Here  is  an  example  of how sgen can be configured to bind to scanner
297       devices on the system:
298
299
300       device-type-config-list = "scanner";
301
302
303       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
307
308       name= "sgen" class= "scsi" target=4 lun=0;
309
310
311       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
316
317       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

SEE ALSO

322       driver.conf(4), scsi(4), sd(7D), st(7D), uscsi(7I)
323
324
325       Writing Device Drivers
326
327
328       ANSI Small Computer System Interface-2 (SCSI-2)
329
330
331       SCSI-3 SPC Draft Standard, Rev. 11a
332
333
334
335SunOS 5.11                        29 Mar 2008                         sgen(7D)
Impressum