sgen - Generic SCSI device driver


     #include <sys/scsi/targets/sgendef.h>



     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


     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  res-
     tricted  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 possi-
     ble for malicious users to install new firmware onto a  dev-
     ice  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 viola-


     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  par-
     ticular  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

     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" tar-
     get=...' 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.


           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.

            is used to match the Vendor ID reported by  the  dev-
           ice. 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.  ven-
           dorid is matched against the Vendor ID reported by the
           device in a case-insensitive manner.

            is used to match the product ID reported by the  dev-
           ice. The SCSI specification limits product IDs to six-
           teen 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  pro-
     ductid.  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.

           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.

           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  con-
           ditions,   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.


           Driver configuration file. See CONFIGURATION  for more

     /dev/scsi/<devtype>/cnt ndn
           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 nam-
           ing   disks.   For   example,   /dev/dsk/c0t0d0s0  and
           /dev/scsi/scanner/c0t5d0 are both  connected  to  con-
           troller 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 sup-
     ports the following ioctls:

           Send a TEST UNIT  READY  command  to  the  device  and
           return  0  upon  success,  non-zero upon failure. This
           ioctl accepts no arguments.

           Change the level of diagnostic reporting  provided  by
           the  driver. This ioctl accepts a single integer argu-
           ment between 0 and 3. The levels have the same meaning
           as  in  the sgen-diag property discussed in PROPERTIES


     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.

           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.


     driver.conf(4), scsi(4), sd(7D), st(7D), uscsi(7I)

     Writing Device Drivers

     ANSI Small Computer System Interface-2 (SCSI-2)

     SCSI-3 SPC Draft Standard, Rev. 11a

Man(1) output converted with man2html