Driver Entry Points transtart(9E)
NAME
transtart - request to transport a SCSI command
SYNOPSIS
#include
int prefixtranstart(struct scsiaddress *ap,
struct scsipkt *pkt);
INTERFACE LEVEL
Solaris architecture specific (Solaris DI).
PARAMETERS
pkt Pointer to the scsipkt(9S) structure that is about
to be transferred.
ap Pointer to a scsiaddress(9S) structure.
DESCRIPTION
The transtart() vector in the scsihbatran(9S) structure
must be initialized during the HBA driver's attach(9E) to
point to an HBA entry point to be called when a target
driver calls scsitransport(9F).
transtart() must perform the necessary operations on the
HBA hardware to transport the SCSI command in the pkt
structure to the target/logical unit device specified in the
ap structure.
If the flag FLAGNOINTR is set in pktflags in pkt,
transtart() should not return until the command has been
completed. The command completion callback pktcomp in pkt
must not be called for commands with FLAGNOINTR set, since
the return is made directly to the function invoking
scsitransport(9F).
When the flag FLAGNOINTR is not set, transtart() must
queue the command for execution on the hardware and return
immediately. The member pktcomp in pkt indicates a call-
back routine to be called upon command completion.
Refer to scsipkt(9S) for other bits in pktflags for
which the HBA driver may need to adjust how the command is
SunOS 5.11 Last change: 17 Aug 2005 1
Driver Entry Points transtart(9E)
managed.
If the autorqsense capability has been set, and the status
length allocated in traninitpkt(9E) is greater than or
equal to sizeof(struct scsiarqstatus), automatic request
sense is enabled for this pkt. If the command terminates
with a Check Condition, the HBA driver must arrange for a
Request Sense command to be transported to that
target/logical unit, and the members of the scsiarqstatus
structure pointed to by pktscbp updated with the results
of this Request Sense command before the HBA driver com-
pletes the command pointed by pkt.
The member pkttime in pkt is the maximum number of
seconds in which the command should complete. Timeout starts
when the command is transmitted on the SCSI bus. A pkttime
of 0 means no timeout should be performed.
For a command which has timed out, the HBA driver must per-
form some recovery operation to clear the command in the
target, typically an Abort message, or a Device or Bus
Reset. The pktreason member of the timed out pkt should be
set to CMDTIMEOUT, and pktstatistics OR'ed with
STATIMEOUT. If the HBA driver can successfully recover
from the timeout, pktstatistics must also be OR'ed with
one of STATABORTED, STATBUSRESET, or STATDEVRESET, as
appropriate. This informs the target driver that timeout
recovery has already been successfully accomplished for the
timed out command. The pktcomp completion callback, if not
NUL, must also be called at the conclusion of the timeout
recovery.
If the timeout recovery was accomplished with an Abort Tag
message, only the timed out packet is affected, and the
packet must be returned with pktstatistics OR'ed with
STATABORTED and STATIMEOUT.
If the timeout recovery was accomplished with an Abort mes-
sage, all commands active in that target are affected. All
corresponding packets must be returned with pktreason,
CMDTIMEOUT, and pktstatistics OR'ed with STATIMEOUT
and STATABORTED.
If the timeout recovery was accomplished with a Device
Reset, all packets corresponding to commands active in the
target must be returned in the transport layer for this
SunOS 5.11 Last change: 17 Aug 2005 2
Driver Entry Points transtart(9E)
target. Packets corresponding to commands active in the tar-
get must be returned returned with pktreason set to
CMDTIMEOUT, and pktstatistics OR'ed with STATDEVRESET
and STATIMEOUT. Currently inactive packets queued for the
device should be returned with pktreason set to CMDRESET
and pktstatistics OR'ed with STATABORTED.
If the timeout recovery was accomplished with a Bus Reset,
all packets corresponding to commands active in the target
must be returned in the transport layer. Packets correspond-
ing to commands active in the target must be returned with
pktreason set to CMDTIMEOUT and pktstatistics OR'ed with
STATIMEOUT and STATBUSRESET. All queued packets for
other targets on this bus must be returned with pktreason
set to CMDRESET and pktstatistics OR'ed with STATABORTED.
Note that after either a Device Reset or a Bus Reset, the
HBA driver must enforce a reset delay time of 'scsi-reset-
delay' milliseconds, during which time no commands should be
sent to that device, or any device on the bus, respectively.
transtart() should initialize the following members in pkt
to 0. Upon command completion, the HBA driver should ensure
that the values in these members are updated to accurately
reflect the states through which the command transitioned
while in the transport layer.
pktresid For commands with data transfer, this
member must be updated to indicate the
residual of the data transferred.
pktreason The reason for the command completion.
This field should be set to CMDCMPLT at
the beginning of transtart(), then
updated if the command ever transitions
to an abnormal termination state. To
avoid losing information, do not set
pktreason to any other error state
unless it still has its original
CMDCMPLT value.
pktstatistics Bit field of transport-related statis-
tics.
pktstate Bit field with the major states through
which a SCSI command can transition.
SunOS 5.11 Last change: 17 Aug 2005 3
Driver Entry Points transtart(9E)
Note: The members listed above, and
pkthbaprivate member, are the only
fields in the scsipkt(9S) structure
which may be modified by the transport
layer.
RETURN VALUES
transtart() must return:
TRANACEPT The packet was accepted by the tran-
sport layer.
TRANBUSY The packet could not be accepted
because there was already a packet in
progress for this target/logical unit,
the HBA queue was full, or the target
device queue was full.
TRANBADPKT The DMA count in the packet exceeded
the DMA engine's maximum DMA size, or
the packet could not be accepted for
other reasons.
TRANFATALEROR A fatal error has occurred in the HBA.
CONTEXT
The transtart() function can be called from user or
interupt context. This requirement comes from
scsitransport().
SEE ALSO
attach(9E), traninitpkt(9E), scsihbaattach(9F),
scsitransport(9F), scsiaddress(9S), scsiarqstatus(9S),
scsihbatran(9S), scsipkt(9S)
Writing Device Drivers
SunOS 5.11 Last change: 17 Aug 2005 4
|
