DS(7M) DS(7M) NAME ds - generic (user mode) SCSI driver SYNOPSIS /dev/scsi/* DESCRIPTION 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 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 <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 */ 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) IOCTLS, ETC. 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 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. 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 (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, 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 SUPPORT CODE 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. 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 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 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 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 /dev/scsi/sccontroller#dtarget#llun# /dev/scsi/nodename/lunlun#/ccontroller#pport# SEE ALSO 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. Page 6