Data Structures for Drivers scsipkt(9S)
NAME
scsipkt - SCSI packet structure
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
DESCRIPTION
A scsipkt structure defines the packet that is allocated by
scsiinitpkt(9F). The target driver fills in some informa-
tion and passes it to scsitransport(9F) for execution on
the target. The host bus adapter (HBA) fills in other infor-
mation as the command is processed. When the command com-
pletes 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
opaquet pkthaprivate; /* private data for
host adapter */
struct scsiaddress pktaddress; /* destination packet */
opaquet pktprivate; /* private data
for target driver */
void (*pktcomp)(struct scsipkt *); /* callback */
uintt pktflags; /* flags */
int pkttime; /* time allotted to
complete command */
uchart *pktscbp; /* pointer to
status block */
uchart *pktcdbp; /* pointer to
command block */
ssizet pktresid; /* number of bytes
not transferred */
uintt pktstate; /* state of command */
uintt pktstatistics; /* statistics */
uchart pktreason; /* reason completion
called */
uintt pktcdblen; /* length of pktcdbp */
uintt pktscdblen; /* length of pktscbp */
uintt pkttgtlen; /* length of pktprivate */
uintt pktnumcookies; /* number of DMA cookies */
ddidmacookiet *pktcookies; /* array of DMA cookies */
uintt pktdmaflags; /* DMA flags */
pkthaprivate Opaque pointer that the HBA uses to refer-
ence a private data structure that
SunOS 5.11 Last change: 11 Jan 2009 1
Data Structures for Drivers scsipkt(9S)
transfers scsipkt requests.
pktaddress Initialized by scsiinitpkt(9F),
pktaddress records the intended route and
the recipient of a request.
pktprivate Reserved for the use of the target driver,
pktprivate is not changed by the HBA
driver.
pktcomp 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 calls the function pointed
to by this field and passes a pointer to
the packet as argument. The callback rou-
tine itself is called from interrupt con-
text and must not sleep or call any func-
tion that might sleep.
pktflags Provides additional information about how
the target driver expects the command to
be executed. See pktflag Definitions.
pkttime Set by the target driver to represent the
maximum time allowed in seconds for this
command to complete. Timeout starts when
the command is transmitted on the SCSI
bus. The pkttime may be 0 if no timeout
is required.
pktscbp Points to either a struct scsistatus(9S)
or, if auto-rqsense is enabled and
pktstate includes STATEARQDONE, a
struct scsiarqstatus. If scsistatus is
returned, the SCSI status byte resulting
from the requested command is available.
If scsiarqstatus(9S) is returned, the
sense information is also available.
pktcdbp Points to a kernel-addressable buffer with
a length specified by a call to the proper
SunOS 5.11 Last change: 11 Jan 2009 2
Data Structures for Drivers scsipkt(9S)
resource allocation routine,
scsiinitpkt(9F).
pktresid Contains a residual count, either the
number of data bytes that have not been
transferred (scsitransport(9F)) or the
number of data bytes for which DMA
resources could not be allocated
scsiinitpkt(9F). In the latter case,
partial DMA resources can be allocated
only if scsiinitpkt(9F) is called with
the PKTDMAPARTIAL flag.
pktstate Has bit positions that represent the six
most important states that a SCSI command
can go through. See pktstate Definitions.
pktstatistics Maintains some transport-related statis-
tics. See pktstatistics Definitions.
pktreason Contains a completion code that indicates
why the pktcomp function was called. See
pktreason Definitions.
pktcdblen Length of buffer pointed to by pktcdbp.
See transetuppkt.
pktscblen Length of buffer pointed to by pktscbp.
See transetuppkt.
pkttgtlen Length of buffer pointed to by
pktprivate. See transetuppkt.
pktnumcookies Length pktcookies array. See
transetuppkt.
pktcookies Array of DMA cookies. See transetuppkt.
pktdmaflags DMA flags used, such as DIDMAREAD and
DIDMAWRITE. See transetuppkt.
SunOS 5.11 Last change: 11 Jan 2009 3
Data Structures for Drivers scsipkt(9S)
The host adapter driver will update the pktresid,
pktreason, pktstate, and pktstatistics fields.
pktflags Definitions
The appropriate definitions for the structure member
pktflags are:
FLAGNOINTR Run command with no command
completion callback. Command
is complete upon return from
scsitransport(9F).
FLAGNODISCON Run command without discon-
nects.
FLAGNOPARITY Run command without parity
checking.
FLAGHTAG Run command as the head-of-
queue-tagged command.
FLAGOTAG Run command as an ordered-
queue-tagged command.
FLAGSTAG Run command as a simple-
queue-tagged command.
FLAGSENSING Indicates a request sense com-
mand.
FLAGHEAD Place command at the head of
the queue.
FLAGRENEGOTIATEWIDESYNC Before transporting this com-
mand, the host adapter should
initiate the renegotiation of
wide mode and synchronous
transfer speed. Normally, the
HBA driver manages negotia-
tions but under certain condi-
tions forcing a renegotiation
is appropriate. Renegotiation
is recommended before Request
Sense and Inquiry commands.
SunOS 5.11 Last change: 11 Jan 2009 4
Data Structures for Drivers scsipkt(9S)
Refer to the SCSI 2 standard,
sections 6.6.21 and 6.6.23.
This flag should not be set
for every packet as this will
severely impact performance.
pktreason Definitions
The appropriate definitions for the structure member
pktreason are:
CMDCMPLT No transport errors; normal completion.
CMDINCOMPLETE Transport stopped with abnormal state.
CMDMADER DMAd irection error.
CMDTRANER Unspecified transport error.
CMDRESET SCSI bus reset destroyed command.
CMDABORTED Command transport aborted on request.
CMDTIMEOUT Command timed out.
CMDATAOVR Data overrun.
CMDCMDOVR Command overrun.
CMDSTSOVR Status overrun.
CMDBADMSG Message not command complete.
CMDNOMSGOUT Target refused to go to message out
phase.
CMDXIDFAIL Extended identify message rejected.
SunOS 5.11 Last change: 11 Jan 2009 5
Data Structures for Drivers scsipkt(9S)
CMDIDEFAIL "Initiator Detected Error" message
rejected.
CMDABORTFAIL Abort message rejected.
CMDREJECTFAIL Reject message rejected.
CMDNOPFAIL "No Operation" message rejected.
CMDPERFAIL "Message Parity Error" message rejected.
CMDBDRFAIL "Bus Device Reset" message rejected.
CMDIDFAIL Identify message rejected.
CMDUNXBUSFRE Unexpected bus free phase.
CMDTAGREJECT Target rejected the tag message.
CMDEVGONE The device has been removed.
pktstate Definitions
The appropriate definitions for the structure member
pktstate are:
STATEGOTBUS Bus arbitration succeeded.
STATEGOTARGET Target successfully selected.
STATESENTCMD Command successfully sent.
STATEXFEREDATA Data transfer took place.
STATEGOTSTATUS Status received.
STATEARQDONE The command resulted in a check condi-
tion and the host adapter driver
SunOS 5.11 Last change: 11 Jan 2009 6
Data Structures for Drivers scsipkt(9S)
executed an automatic request sense
command.
STATEXARQDONE The command requested in extra sense
data using a PKTXARQ flag got a check
condition. The host adapter driver was
able to successfully request and
return this. The scsipkt.pktscbp-
>stsrqpktresid returns the sense
data residual based on the statuslen
parameter of the scsiinitpkt(9F)
call. The sense data begins at
scsipkt.pktscbp->stssensedata.
pktstatistics Definitions
The definitions that are appropriate for the structure
member pktstatistics are:
STATDISCON Device disconnect.
STATSYNC Command did a synchronous data transfer.
STATPER SCSI parity error.
STATBUSRESET Bus reset.
STATDEVRESET Device reset.
STATABORTED Command was aborted.
STATIMEOUT Command timed out.
SEE ALSO
traninitpkt(9E), transetuppkt(9E), scsiarqstatus(9S),
scsiinitpkt(9F), scsitransport(9F), scsistatus(9S),
scsihbapktcomp(9F)
Writing Device Drivers
NOTES
HBA drivers should signal scsipkt completion by calling
scsihbapktcomp(9F). This is mandatory for HBA drivers
SunOS 5.11 Last change: 11 Jan 2009 7
Data Structures for Drivers scsipkt(9S)
that implement transetuppkt(9E). Failure to comply results
in undefined behavior.
SunOS 5.11 Last change: 11 Jan 2009 8
|
