NAME

scsi_pkt - SCSI packet structure

SYNOPSIS

#include <sys/scsi/scsi.h>

INTERFACE LEVEL

Solaris DDI specific (Solaris DDI).

DESCRIPTION

A scsi_pkt structure defines the packet which is allocated by scsi_init_pkt(9F). The target driver fills in some information, and passes it to scsi_transport(9F) for execution on the target. The HBA fills in some other information as the command is processed. When the command completes (or can be taken no further) the completion function specified in the packet is called with a pointer to the packet as its argument. From fields within the packet, the target driver can determine the success or failure of the command.

STRUCTURE MEMBERS

opaque_t

pkt_ha_private;

/* private data for host adapter * /

struct scsi_address pkt_address;                    /* destination packet is for * /
opaque_t            pkt_private;                    /* private data for target driver * /
void                (* pkt_comp)(structscsi_pkt * );/* callback * /
u_int               pkt_flags;                       /* flags * /
int                 pkt_time;                       /* time allotted to complete * /
                                                    /* command * /
u_char              * pkt_scbp;                     /* pointer to status block * /
u_char              * pkt_cdbp;                     /* pointer to command block * /
ssize_t             pkt_resid;                      /* number of bytes not transferred * /
u_int               pkt_state;                      /* state of command * /
u_int               pkt_statistics;                 /* statistics * /
u_char              pkt_reason;                     /* reason completion called * /

pkt_ha_private

is an opaque pointer which the Host Bus Adapter uses to reference a private data structure used to transfer scsi_pkt requests.

pkt_address

is initialized by scsi_init_pkt(9F) and serves to record the intended route and recipient of a request.

pkt_private

is reserved for the use of the target driver and is not changed by the HBA driver.

pkt_comp

specifies the command completion callback routine. When the host adapter driver has gone as far as it can in transporting a command to a SCSI target, and the command has either run to completion, or can go no further for some other reason, the host adapter driver will call the function pointed to by this field and pass a pointer to the packet as argument.

The callback routine itself is called from interrupt context and must not sleep nor call any function which may sleep.

pkt_flags

provides additional information about how the target driver wants the command to be executed. See pkt_flag Definitions.

pkt_time

will be set by the target driver to represent the maximum length of time in seconds that this command is allowed take to complete. pkt_time may be 0 if no timeout is required.

pkt_scbp

points to the SCSI status completion block.

pkt_cdbp

points to a kernel addressable buffer whose length was specified by a call to the proper resource allocation routine, scsi_init_pkt(9F).

pkt_resid

contains a residual count, either the number of data bytes that have not been transferred ( scsi_transport(9F)) or the number of data bytes for which DMA resources could not be allocated

scsi_init_pkt(9F). In the latter case, partial DMA resources may only be allocated if scsi_init_pkt(9F) is called with the

PKT_DMA_PARTIAL flag.

pkt_state

has bit positions representing the five most important states that a SCSI command can go through (see pkt_state Definitions).

pkt_statistics

maintains some transport-related statistics. (see pkt_statistics Definitions).

pkt_reason

contains a completion code that indicates why the pkt_comp function was called.

The host adapter driver will update the pkt_resid, pkt_reason, pkt_state, and pkt_statistics fields.

pkt_flags Definitions:

The definitions that are appropriate for the structure member pkt_flags are:

FLAG_NOINTR

Run command with no command completion callback;

command is complete upon return from

scsi_transport(9F).

FLAG_NODISCON

Run command without disconnects.

FLAG_NOPARITY

Run command without parity checking.

FLAG_HTAG

Run command as the head of queue tagged command.

FLAG_OTAG

Run command as an ordered queue tagged command.

FLAG_STAG

Run command as a simple queue tagged command.

FLAG_SENSING

This command is a request sense command.

FLAG_HEAD

This command should be put at the head of the queue.

pkt_reason Definitions:

The definitions that are appropriate for the structure member pkt_reason are:

CMD_CMPLT

No transport errors-normal completion.

CMD_INCOMPLETE

Transport stopped with abnormal state.

CMD_DMA_DERR

DMA direction error.

CMD_TRAN_ERR

Unspecified transport error.

CMD_RESET

SCSI bus reset destroyed command.

CMD_ABORTED

Command transport aborted on request.

CMD_TIMEOUT

Command timed out.

CMD_DATA_OVR

Data Overrun.

CMD_CMD_OVR

Command Overrun.

CMD_STS_OVR

Status Overrun.

CMD_BADMSG

Message not Command Complete.

CMD_NOMSGOUT

Target refused to go to Message Out phase.

CMD_XID_FAIL

Extended Identify message rejected.

CMD_IDE_FAIL

Initiator Detected Error message rejected.

CMD_ABORT_FAIL

Abort message rejected.

CMD_REJECT_FAIL

Reject message rejected.

CMD_NOP_FAIL

No Operation message rejected.

CMD_PER_FAIL

Message Parity Error message rejected.

CMD_BDR_FAIL

Bus Device Reset message rejected.

CMD_ID_FAIL

Identify message rejected.

CMD_UNX_BUS_FREE

Unexpected Bus Free Phase.

CMD_TAG_REJECT

Target rejected the tag message.

pkt_state Definitions:

The definitions that are appropriate for the structure member pkt_state are:

STATE_GOT_BUS

Bus arbitration succeeded.

STATE_GOT_TARGET

Target successfully selected.

STATE_SENT_CMD

Command successfully sent.

STATE_XFERRED_DATA

Data transfer took place.

STATE_GOT_STATUS

Status received.

STATE_ARQ_DONE

The command resulted in a check condition and the

host adapter driver executed an automatic request

sense cmd.

pkt_statistics Definitions:

The definitions that are appropriate for the structure member pkt_statistics are:

STAT_DISCON

Device disconnect.

STAT_SYNC

Command did a synchronous data transfer.

STAT_PERR

SCSI parity error.

STAT_BUS_RESET

Bus reset.

STAT_DEV_RESET

Device reset.

STAT_ABORTED

Command was aborted.

STAT_TIMEOUT

Command timed out.

SEE ALSO

tran_init_pkt(9E), scsi_init_pkt(9F), scsi_transport(9F)

Writing Device Drivers