ds  - User Mode SCSI driver for devices accessed using the
       SGI linux-xscsi subsystem.


SYNOPSIS

       /dev/xscsi/pci*/target*/lun*/ds - the  generic  'ds'  scsi
       driver device


DESCRIPTION

       The  ds  interface  provides  user-mode access to the SCSI
       bus.  It supports the programming interfaces described  in
       dslib(8) and below.

       All  of the ds devices support the same general interface.
       The program calls open, gaining exclusive use of a  speci­
       fied SCSI device (that is, two processes may not both have
       the same device open at the same time  via  this  driver).
       Additionally, when the O_EXCL open flag set, exclusive use
       of the target will be acquired.  No other SCSI driver will
       be  able  to  use  the target until it is closed.  If some
       other process has the target device open from another SCSI
       driver,  the open will fail with errno set to EBUSY.  More
       than one process may in fact have the same target open via
       this  driver,  if  one  is  a descendent of the other (via
       sproc(2) or fork(2).  In this case, it is the responsibil­
       ity of the program(s) to ensure that both processes do not
       both attempt to do commands at the same time.

       After opening, ioctl calls can be made.  They will  either
       be  performed  directly  or turned into SCSI transactions.
       Finally, the close call releases the  device  for  further
       use.

       The  critical interface definitions (request structure and
       codes, return codes, etc.) are defined in <xscsids.h>.  In
       particular, most SCSI transactions are performed using the
       dsreq structure:

         typedef struct dsreq {        /* DEVSCSI ioctl structure      */

                                       /* devscsi prefix ...........   */
           uint          ds_flags;     /* see DSRQ_* flags below       */
           uint          ds_time;      /* timeout in milliseconds
                                          (1 HZ used if zero)          */
           __psint_t     ds_private;   /* private use by caller        */

                                       /* SCSI request .............   */
           caddr_t       ds_cmdbuf;    /* command buffer               */
           uchar_t       ds_cmdlen;    /* command buffer length        */
           caddr_t       ds_databuf;   /* data buffer start            */
           uint          ds_datalen;   /* total data length            */
           caddr_t       ds_sensebuf;  /* sense buffer                 */
           uchar_t       ds_senselen;  /* sense buffer length          */

           dsiovec_t    *ds_iovbuf;    /* scatter-gather dma control   */
           ushort        ds_iovlen;    /* length of scatter-gather     */
           struct dsreq *ds_link;      /* for linked requests          */
           ushort        ds_synch;     /* synchronous transfer control */
           uchar_t       ds_revcode;   /* devscsi version code         */

                                       /* return portion ...........   */
           uchar_t       ds_ret;       /* devscsi return code          */
           uchar_t       ds_status;    /* status byte value            */
           uchar_t       ds_msg;       /* message byte value           */
           uchar_t       ds_cmdsent;   /* actual length command        */
           uint          ds_datasent;  /* actual length user data      */
           uchar_t       ds_sensesent; /* actual length sense data     */
         } dsreq_t;

       The first two parts of the structure (devscsi prefix, SCSI
       request)  must  be  filled in by the calling program.  The
       third part (scatter-gather, etc.) is largely optional, and
       the  last  part (return portion) is used only for returned
       information.

       Normally, the ds_data* fields are  used  to  control  data
       transmission.  In this mode, all sent (received) data uses
       a single I/O buffer.  If  desired,  however,  the  ds_iov*
       fields  may be used (see DSRQ_IOV) to support a set of I/O
       buffers.  The number of scatter gather  entries  supported
       is  given  by  the  V_MAX define, and is currently 1.  The
       scatter-gather structure, dsiovec_t, is  defined  as  fol­
       lows:

         typedef struct dsiovec {  /* DEVSCSI scatter-gather control   */
             caddr_t  iov_base;    /* i/o base */
             int     iov_len;     /* i/o length */
         } dsiovec_t;

       Different  /dev/xscsi/pci*/target*/lun*/ds implementations
       will  support  different  subsets  of  the  specification.
       Items  in  the  following  tables  are therefore marked to
       indicate the likelihood of support:

          !  required  (must be supported)
          .  normal    (usually supported)
          ?  unusual   (seldom  supported)


IOCTLS, ETC.

       Several ioctls are supported by  the  /dev/xscsi/pci*/tar­
       get*/lun*/ds interface
       DS_ENTER     struct dsreq     !  enter a request

       DS_CANCEL    struct dsreq     ?  cancel a request
       DS_POLL      struct dsreq     ?  sample a request


       DS_RESET     uint             .  obsolete

       DS_SET       uint             !  set permanent flags
       DS_CLEAR     uint             !  clear permanent flags
       DS_GET       uint             !  get permanent flags
       DS_CONF      struct dsconf    !  get configuration data
       DS_ABORT     uint             .  send abort message

       The  DS_ENTER ioctl is the basis for most interaction with
       the driver.  The user program prepares  a  request  struc­
       ture,  issues  the ioctl, and examines the returned status
       information.

       Other ioctls help to fill out the interface, however.  The
       polled  I/O ioctls (DS_CANCEL, DS_POLL, DS_CONTIN) are for
       support asynchronous /dev/xscsi  operations  (not  in  the
       SCSI sense, but in the I/O sense); these are not supported
       under the SGI-Linux XSCSI subsystem.  The DS_ABORT  ioctl,
       provides  the  ability to send an abort message; it is not
       implemented for all host adapter types.  The abort message
       will be sent only when the target has no commands pending,
       and is therefore useful only to abort immediate mode  com­
       mands, or target specific functions.

       The permanent flag ioctls (DS_SET, DS_GET, DS_CLEAR) allow
       access to internal driver flag bits.  These are undefined,
       implementation specific, and should be avoided if portable
       code is desired.  The DS_GET ioctl returns bits whose def­
       initions  begin  with DSG_ (from xscsids.h) under the SGI-
       Linux XSCSI subsystem.  Not all  of  the  low  level  host
       adapter drivers support all (or even any) of these bits.

       The  DS_CONF  ioctl, by contrast, allows a user program to
       detect (and perhaps handle)  implementation-specific  con­
       figuration parameters:

         typedef struct dsconf {        /* DEVSCSI configuration structure */
                 uint dsc_flags;        /* DSRQ flags honored by driver */
                 uint dsc_preset;       /* DSRQ flag  preset values */
                 u_char dsc_bus;        /* # of this SCSI bus */
                 u_char dsc_imax;       /* maximum # of ID's per bus on system */
                 u_char dsc_lmax;       /* maximum # of LUN's per ID on system */
                 uint dsc_iomax;        /* maximum length of an I/O on this system */
                 uint dsc_biomax        /* maximum length of buffered I/O's */
         } dsconf_t;

       Most of the dsconf members ( dsc_bus, dsc_*max) have obvi­
       ous meanings.  The dsc_iomax parameter  is  equivalent  to
       the   kernel   tunable  parameter  maxdmasz,  except  that
       dsc_iomax is in bytes, rather than pages.   The  dsc_flags

       together to indicate how the  driver  will  interpret  the
       DSRQ_* flag bits.

       These  bits  are ORed by the driver with the ds_flags word
       in dsreq, request specific driver actions.  The  implemen­
       tation  is  then  free  to  reject, honor, or ignore them.
       Specifically, options will not be turned off, but  may  be
       rejected  via the DSRT_UNIMPL return code.  Options may be
       turned on without any notice whatsoever.

       The dsc_flags member of dsconf indicates which  flags  the
       implementation  promises  to  honor.   The dsc_preset word
       indicates, for each flag not honored, the value defined by
       the implementation.  By appropriate logical operations, an
       application may determine which DSRQ_* options  are  actu­
       ally  available.   The action in parentheses is taken when
       the flag is not set.

       Note that the DSRQ_SYNXFR and  DSRQ_ASYNXFR  flags  should
       not be used in all commands, only when strictly necessary,
       as such negotiations are relatively  expensive.   Not  all
       host adapter drivers will honor these flags.
       devscsi options:

       DSRQ_ASYNC      ?  no (yes) sleep until request done
       DSRQ_SENSE      .  yes (no) auto get sense on status
       DSRQ_TARGET     ?  target (initiator) role

       select options:

       DSRQ_SELATN     .  select with (without) atn
       DSRQ_DISC       .  identify disconnect (not) allowed
       DSRQ_SYNXFR     .  attempt SCSI synchronous transfer negotiation
       DSRQ_ASYNXFR    .  attempt SCSI asynchronous transfer negotiation
       DSRQ_SELMSG     .  send supplied (generate) message

       data transfer options:

       DSRQ_IOV        .  scatter-gather (not) specified
       DSRQ_READ       !  input from SCSI bus
       DSRQ_WRITE      !  output toSCSI bus
       DSRQ_BUF        .  buffered (direct) data transfer

       progress/continuation callbacks:

       DSRQ_CALL       ?  notify progress (completion-only)
       DSRQ_ACKH       ?  (don't) hold ACK asserted
       DSRQ_ATNH       ?  (don't) hold ATN asserted
       DSRQ_ABORT      ?  abort msg until bus clear

       host options (non-portable):

       DSRQ_TRACE      .  trace (no) this request

       DSRQ_CTRL1      .  request with host control bit 1
       DSRQ_CTRL2      .  enable driver debug printfs during ioctl
                            (if program has superuser privileges)

       additional flags:

       DSRQ_MIXRDWR    ?  request can both read and write


RETURN CODES

       The driver has a number of possible return codes, signify­
       ing failures on the part of  the  driver,  the  host  SCSI
       software,  or  the  protocol.   Some  return  codes may be
       mapped  to  more  generic  return   codes   (DSRT_DEVSCSI,
       DSRT_HOST,  DSRT_PROTO).   Note  that  the ds_status field
       contains valid completion status  only  when  the  command
       completed  'normally'.  On timeouts and some other errors,
       this field is set to 0xff on return to  indicate  that  is
       not  valid. The ds_ret may be non-zero even if the command
       completed successfully; i.e.  on partial  i/o  completion,
       and when a request sense has been done.

       devscsi software returns:

       DSRT_DEVSCSI     !  general devscsi failure
       DSRT_MULT        !  request rejected
       DSRT_CANCEL      !  lower request cancelled
       DSRT_REVCODE     !  software obsolete, must recompile
       DSRT_AGAIN       !  try again, recoverable bus error
       DSRT_UNIMPL      !  unimplemented request option

       host SCSI software returns:

       DSRT_HOST        !  general host failure
       DSRT_NOSEL       .  no unit responded to select
       DSRT_SHORT       !  incomplete transfer (not an error)
       DSRT_OK          !  completetransfer (no error status)
       DSRT_SENSE       !  cmd w/ status, sense data gotten
       DSRT_NOSENSE     !  cmd w/ status, error getting sense
       DSRT_TIMEOUT     !  request idle longer than requested
       DSRT_LONG        !  target overran data bounds

       protocol failures:

       DSRT_PROTO       !  misc. protocol failure
       DSRT_EBSY        .  busy dropped unexpectedly
       DSRT_REJECT      .  message reject
       DSRT_PARITY      .  parity error on SCSI bus
       DSRT_MEMORY      .  host memory error
       DSRT_CMDO        .  error during command phase
       DSRT_STAI        .  error during statusphase


SUPPORT CODE

       A   number   of  ancillary  macros,  functions,  and  data

       necessary, these should facilitate the task of programming
       SCSI control programs.


ADDITIONAL INFORMATION

       Consult the SCSI standards documents, and the manuals  for
       the device you are working with for more information.  The
       "SCSI 1" specification document is called SCSI  Specifica­
       tion,  ANSI X3T9.2/86-109.  Also of interest is the Common
       Command Set specification document SCSI CCS Specification,
       ANSI X3T9.2/85-3


NOTES

       The ds programming interface contains a number of optional
       features.  The control program must therefore be  able  to
       react  properly, should a desired function be unavailable.

       The peculiarities of any given SCSI device are the respon­
       sibility of the control program.  The /dev/xscsi/pci*/tar­
       get*/lun*/ds interface merely allows communication to take
       place.

       Since  the  driver provides direct access to the SCSI bus,
       the system administrator must be very careful  in  setting
       up  the  permissions  on  the  device files, lest security
       holes occur.

       No kernel read/write interface is  provided,  due  to  the
       variety of forms these commands take in terms of both size
       and field definitions.

       No support currently  exists  for  target  mode  or  asyn­
       chronous (polled) I/O.

       No checking is currently performed for potentially danger­
       ous actions (Copy, ID and code downloading, etc.).


NOTE

       The device for each controller, id, lun trio is  exclusive
       open,  in  that  once  that combination is opened via this
       interface or the 'normal' system interfaces, it may not be
       opened  again, until released by the other user.  The nor­
       mal error returned in this case is EBUSY.  The  driver  is
       semaphored  such that multiple copies of the file descrip­
       tor may be used, either by the same program, or its  chil­
       dren via fork, etc.


FILES

        /dev/xscsi/pci*/target*/lun*/ds - the generic 'ds' scsi driver device


SEE ALSO

       dslib(8) for discussion of routines to simplify the use of
       the driver.
       xscsicontrol(8) for a program that  uses  this  driver  to



Man(1) output converted with man2html