dsreq - User-level Driver Communication Structure

The dsreq type structure can be found in the sys/dsreq.h directory. The macros associated with a dsreq type structure are described below. The dslib routines are described in "dslib Routines Description".

dsreq Structure

typedef struct dsreq {
/* devscsi prefix */

ulong          ds_flags;     /* see flags defined below */
ulong          ds_time;      /* time-out in milliseconds */
ulong          ds_private;   /* for 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 */
ulong          ds_datalen;   /* total data length */
caddr_t        ds_sensebuf;  /* sense buffer */
uchar_t        ds_senselen;  /* sense buffer length */
/* miscellaneous */
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 xfer control*/
uchar_t        ds_revcode;   /* devscsi version code*/

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

ds_flags

The bits of the value for this member are used as flags that determine what the SCSI-bus driver does after you call doscsireq(). Use the FLAGS macro to access the value of this member. The interface is designed to be implemented on a number of architectures, some of which provide more low-level control of the SCSI bus than IRIX. The file, dsreq.h included by dslib.h, currently defines this macro as:

#define FLAGS (dp) ((dp)->ds_flags)

There are symbolic constants that you can use to set the bits of the ds_flags value. (Not all of these flags are currently honored. Your driver can test for which flags are honored by checking the returned value of an ioctl() call on devscsi. See the ds(7M) man page.) These constants are defined in sys/dsreq.h:

DSRQ_ASYNC - No/Yes sleep until request done. A SCSI device option. Not implemented.

DSRQ_SENSE - Yes/No automatically get sense on status when a check condition occurs. A SCSI device option. All requests return only on completion. Not implemented.

DSRQ_TARGET - Target/Initiator role. A SCSI device option. Not implemented.

DSRQ_SELATN - Select with/without ATN. A select option. Not implemented.

DSRQ_DISC - Identify disconnect not-allowed/allowed. A select option. Not implemented.

DSRQ_SYNXFR - Negotiate synchronous SCSI transfer. A select option.

DSRQ_SELMSG - Send supplied/generated message. A select option. Not implemented.

DSRQ_IOV - Scatter-gather not-specified/specified. A data transfer option.

DSRQ_READ - Input data from SCSI bus to the CPU. A data transfer direction.

DSRQ_WRITE - Output data to SCSI bus from the CPU. A data transfer direction.

DSRQ_BUF - Buffered/Direct data transfer. A data transfer option.

DSRQ_CALL - Notify progress upon completion. A progress/continuation callback option. Used with DSRQ_ASYNC. Not implemented.

DSRQ_ACKH - Hold/Don't-hold ACK asserted. A progress/continuation callback option. Not implemented.

DSRQ_ATNH - Hold/don't-hold ATN asserted. A progress/continuation callback option. Not implemented.

DSRQ_ABORT - Send an abort message. Useful only with SCSI commands that have the immediate bit set.

DSRQ_TRACE - Trace/don't-trace this request. A host option (and so not likely to be portable).

DSRQ_PRINT - Print/don't-print this request. A host option (and so not likely to be portable).

DSRQ_CTRL1 - Request with host control bit 1. A host option (and so not likely to be portable).

DSRQ_CTRL2 - Request with host control bit 2. A host option (and so not likely to be portable).

DSRQ_MIXRDWR - Request can both read and write.

ds_time

This member sets the time-out value in milliseconds for the completion of a command sent to the SCSI device. You can use the TIME macro to access the value of this member.

The file dsreq.h defines this macro as:

#define TIME (dp) ((dp)->ds_time)

If you use dslib, you must not change this pointer or the data it references.

ds_private

To access the value of the ds_private member, you can use the PRIVATE macro currently defined in dslib.h as:

#define PRIVATE(dp) ((dp)->ds_private)

This is intended to be used only in the library support routines.

ds_cmdbuf

This member is a pointer to an array, the SCSI command descriptor you want to send to the device. You can use the CMDBUF macro to access this value. The file dsreq.h currently defines this macro as:

#define CMDBUF(dp) ((caddr_t) (dp)->ds_cmdbuf)

ds_cmdlen

This member is the length (in bytes) of the SCSI command pointed to by ds_cmdbuf. You can use the CMDLEN macro to access the value of this member. The file dsreq.h currently defines this macro as:

#define CMDLEN(dp) ((dp)->ds_cmdlen)

Typically, this value is 6, 10, or 12 for SCSI commands of class 0, 1, or 2, respectively.

ds_databuf

This member is a pointer to the start of a data buffer. You can use the DATABUF macro to access the value of this member. The file dsreq.h currently defines this macro as:

#define DATABUF(dp) ((caddr_t) (dp)->ds_databuf)

ds_datalen

This member is the length of the data in the buffer pointed to by the ds_databuf member. You can use the DATALEN macro to access the value of this member. The file dsreq.h currently defines this macro as:

#define DATALEN(dp) ((dp)->ds_datalen)

ds_sensebuf

This member is the pointer to the start of the sense buffer. The contents written to this buffer when you request sense information from a device depend on the device. See the device-specific documentation supplied by the manufacturer. You can use the SENSEBUF macro to access the value of this member. The file dsreq.h currently defines this macro as:

#define SENSEBUF(dp) ((caddr_t) (dp)->ds_sensebuf)

It is used only if DSRQ_SENSE is set in the flags.

ds_senselen

This member is the length of the data in the buffer pointed to by the ds_sensebuf member. You can use the SENSELEN macro to access the value of this member. The file dsreq.h currently defines this macro as:

#define SENSELEN(dp) ((dp)->ds_senselen)

*ds_iovbuf

This member is a pointer to a dsiovec type structure, a SCSI device I/O vector. This structure is used for DMA scatter-gather control. The dsiovec type structure (defined in dsreq.h) has two members: iov_base, a pointer to a buffer containing a table of physical addresses for the entire transfer, and iov_len, the length of the buffer pointed to by iov_base.

To access the value of the *ds_iovbuf member, you can use the macro, IOVBUF. The file dsreq.h currently defines this macro as:

#define IOVBUF(dp) ((caddr_t) (dp)->ds_iovbuf)

ds_iovlen

This member is the length, in bytes, of the data for scatter-gather transfer. You can use the IOVLEN macro to access the value of this member. The file dsreq.h currently defines this macro as:

#define IOVLEN(dp) ((dp)->ds_iovlen)

*ds_link

Not supported.

ds_synch

Not supported.

ds_revcode

This member is the version code for the devscsi driver.

ds_ret

This member is the return code for the command executed on the SCSI device. You can use the RET macro to access this member. The file dsreq.h currently defines RET:

#define RET(dp) ((dp)->ds_ret)

The file dsreq.h defines the following symbolic constants for the value pointed to by this member:

DSRT_DEVSCSI - General failure from SCSI bus.

DSRT_HOST - General host failure, typically a SCSI-bus request.

DSRT_STAI - Protocol error during status phase.

DSRT_EBSY - Busy dropped unexpectedly; protocol error.

DSRT_UNIMPL - Protocol error. Not implemented.

DSRT_CMDO - Protocol error during command phase.

DSRT_REJECT - Message rejected; protocol error.

DSRT_PARITY - Parity error on SCSI bus; protocol error.

DSRT_PROTO - Miscellaneous protocol failure.

DSRT_MEMORY - Host memory error.

DSRT_MULT - Request rejected by SCSI bus.

DSRT_CANCEL - Lower request canceled by SCSI bus.

DSRT_REVCODE - Software obsolete, must recompile.

DSRT_AGAIN - Try again, recoverable SCSI-bus error.

DSRT_NOSEL - No unit responded to select.

DSRT_SHORT - Incomplete transfer (not an error).

DSRT_OK - Completed transfer without error status.

DSRT_SENSE - Command with status, sense data successfully retrieved from SCSI host.

DSRT_NOSENSE - Command with status, error occurred while trying to get sense data from SCSI host.

DSRT_TIMEOUT - Request idled longer than requested. Command could not complete within the limit of the time-out value.

DSRT_LONG - Target over ran data bounds.

ds_status

This member is the SCSI target's status byte value for the SCSI command just executed. You can use the STATUS macro to access this member.

The file dsreq.h currently defines STATUS:

#define STATUS(dsp) ((dp)->ds_status)

The file dsreq.h defines the following symbolic constants for this byte:

STA_GOOD - the target has successfully completed the SCSI command.

STA_CHECK - indicates an error, exception, or abnormal condition. If DSRQ_SENSE is set, request sense is automatically done. See ds_sensebuf.

STA_BUSY - the target is busy, so the command was not issued.

STA_IGOOD - SCSI command with link completed.

STA_RESERV - Command aborted because it tried to access a logical unit or an extent within a logical unit that reserves that type of access to another SCSI device.

ds_msg

Not implemented.

ds_cmdsent

The value of this member is the length of the SCSI command actual sent. You can use the CMDSENT macro to access this member. The file dsreq.h currently defines CMDSENT:

#define CMDSENT(dsp) ((dp)->ds_cmdsent)

ds_datasent

The value of this member is the length of the user data actually transferred. You can use the DATASENT macro to access this member. The file dsreq.h currently defines DATASENT:

#define DATASENT(dsp) ((dp)->ds_datasent)

ds_sensesent

The value of this member is the length of the sense data actually received. You can use the SENSESENT macro to access this member. The file dsreq.h currently defines SENSESENT:

#define SENSESENT(dsp) ((dp)->ds_sensesent)