*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> ds (7)              


DS(7M)									DS(7M)

NAME    [Toc]    [Back]

     ds	- generic (user	mode) SCSI driver

SYNOPSIS    [Toc]    [Back]


DESCRIPTION    [Toc]    [Back]

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

     All of the	ds devices support the same general interface.	The program
     calls open, gaining exclusive use of a specified 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 responsibility of the program(s)	to
     ensure that both processes	do not both attempt to do commands at the same

     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 <sys/dsreq.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	     */

				     /*	scatter-gather,	etc. .....   */
	 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 */

									Page 1

DS(7M)									DS(7M)

	 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	follows:

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

     Different /dev/scsi 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)

     Several ioctls are	supported by /dev/scsi:

     DS_ENTER	  struct dsreq	   !  enter a request

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

     DS_RESET	  uint		   .  obsolete -- see scsiha(7M)

     DS_SET	  uint		   !  set permanent flags
     DS_CLEAR	  uint		   !  clear permanent flags
     DS_GET	  uint		   !  get permanent flags

									Page 2

DS(7M)									DS(7M)

     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 structure, 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/scsi operations (not in the SCSI sense, but in the I/O sense); these
     are not supported under IRIX.  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
     commands, 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	definitions begin with DSG_ (from dsreq.h) under IRIX
     5.1.  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 configuration 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 obvious 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 and dsc_preset words, require more explanation.	They work
     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 implementation 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.

									Page 3

DS(7M)									DS(7M)

     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
     actually 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; for	the wd93 host adapter, the default for the ds driver is	to
     operate in	the SCSI bus asynchronous mode.	 For other host	adapters, the
     default is	to operate in synchronous mode and wide	mode if	it is
     supported by the target.  If necessary, such parameters can usually be
     controlled	by editing the master file for the particular host adapter
     driver (i.e. /var/sysgen/master.d/wd95 for	wd95,
     /var/sysgen/master.d/scip for scip, etc.).

     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_PRINT	     .	print (no) this	request
     DSRQ_CTRL1	     .	request	with host control bit 1
     DSRQ_CTRL2	     .	enable driver debug printfs during ioctl

									Page 4

DS(7M)									DS(7M)

		       (if program has superuser privileges)

     additional	flags:

     DSRQ_MIXRDWR    ?	request	can both read and write

RETURN CODES    [Toc]    [Back]

     The driver	has a number of	possible return	codes, signifying 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

     A number of ancillary macros, functions, and data structures are defined
     in	<dslib.h>. While not strictly necessary, these should facilitate the
     task of programming SCSI control programs.

									Page 5

DS(7M)									DS(7M)


     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 Specification, ANSI X3T9.2/86-109.	Also of
     interest is the Common Command Set	specification document SCSI CCS
     Specification, ANSI X3T9.2/85-3

NOTES    [Toc]    [Back]

     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	responsibility of the
     control program.  The /dev/scsi 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 asynchronous (polled) I/O.

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

NOTE    [Toc]    [Back]

     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 normal	error returned in this case is EBUSY.  The driver is
     semaphored	such that multiple copies of the file descriptor may be	used,
     either by the same	program, or its	children via fork, etc.

FILES    [Toc]    [Back]


SEE ALSO    [Toc]    [Back]

     dslib(3) for discussion of	routines to simplify the use of	the driver.
     dksc(7M) for a NOTES section describing some configuration	options	of the
     underlying	SCSI driver.
     scsiha(7M)	for operations on the entire SCSI bus
     cdintro(3)	for discussion of a library above dslib	that supports use of
     audio CD's	in the CD-ROM drive.
     scsicontrol(1m) for a program that	uses this driver to probe and control
     scsi devices.

									PPPPaaaaggggeeee 6666
[ Back ]
 Similar pages
Name OS Title
uk OpenBSD SCSI user-level driver
nsp FreeBSD Workbit Ninja SCSI-3 based PC-Card SCSI host adapter driver
dslib IRIX communicate with generic SCSI devices
pci FreeBSD generic PCI driver
cd FreeBSD SCSI CD-ROM driver
iic FreeBSD I2C generic i/o device driver
smb FreeBSD SMB generic I/O device driver
iicbb FreeBSD I2C generic bit-banging driver
iopsp OpenBSD I2O SCSI port driver
scsi_ctl HP-UX SCSI pass-through driver
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service