svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
tran_start(9e)
tran_start(9E) Driver Entry Points tran_start(9E)
NAME
tran_start - request to transport a SCSI command
SYNOPSIS
#include <sys/scsi/scsi.h>
int prefix_tran_start(struct scsi_address *ap,
struct scsi_pkt *pkt);
INTERFACE LEVEL
Solaris architecture specific (Solaris DDI).
PARAMETERS
pkt Pointer to the scsi_pkt(9S) structure that is about to be trans‐
ferred.
ap Pointer to a scsi_address(9S) structure.
DESCRIPTION
The tran_start() vector in the scsi_hba_tran(9S) structure must be ini‐
tialized during the HBA driver's attach(9E) to point to an HBA entry
point to be called when a target driver calls scsi_transport(9F).
tran_start() must perform the necessary operations on the HBA hardware
to transport the SCSI command in the pkt structure to the target/logi‐
cal unit device specified in the ap structure.
If the flag FLAG_NOINTR is set in pkt_flags in pkt, tran_start() should
not return until the command has been completed. The command completion
callback pkt_comp in pkt must not be called for commands with
FLAG_NOINTR set, since the return is made directly to the function in‐
voking scsi_transport(9F).
When the flag FLAG_NOINTR is not set, tran_start() must queue the com‐
mand for execution on the hardware and return immediately. The member
pkt_comp in pkt indicates a callback routine to be called upon command
completion.
Refer to scsi_pkt(9S) for other bits in pkt_flags for which the HBA
driver may need to adjust how the command is managed.
If the auto_rqsense capability has been set, and the status length al‐
located in tran_init_pkt(9E) is greater than or equal to sizeof(struct
scsi_arq_status), 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 tar‐
get/logical unit, and the members of the scsi_arq_status structure
pointed to by pkt_scbp updated with the results of this Request Sense
command before the HBA driver completes the command pointed by pkt.
The member pkt_time in pkt is the maximum number of seconds in which
the command should complete. Timeout starts when the command is trans‐
mitted on the SCSI bus. A pkt_time of 0 means no timeout should be per‐
formed.
For a command which has timed out, the HBA driver must perform some re‐
covery operation to clear the command in the target, typically an Abort
message, or a Device or Bus Reset. The pkt_reason member of the timed
out pkt should be set to CMD_TIMEOUT, and pkt_statistics OR'ed with
STAT_TIMEOUT. If the HBA driver can successfully recover from the time‐
out, pkt_statistics must also be OR'ed with one of STAT_ABORTED,
STAT_BUS_RESET, or STAT_DEV_RESET, as appropriate. This informs the
target driver that timeout recovery has already been successfully ac‐
complished for the timed out command. The pkt_comp completion callback,
if not NULL, must also be called at the conclusion of the timeout re‐
covery.
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 pkt_statistics OR'ed with STAT_ABORTED and STAT_TIMEOUT.
If the timeout recovery was accomplished with an Abort message, all
commands active in that target are affected. All corresponding packets
must be returned with pkt_reason, CMD_TIMEOUT, and pkt_statistics
OR'ed with STAT_TIMEOUT and STAT_ABORTED.
If the timeout recovery was accomplished with a Device Reset, all pack‐
ets corresponding to commands active in the target must be returned in
the transport layer for this target. Packets corresponding to commands
active in the target must be returned returned with pkt_reason set to
CMD_TIMEOUT, and pkt_statistics OR'ed with STAT_DEV_RESET and
STAT_TIMEOUT. Currently inactive packets queued for the device should
be returned with pkt_reason set to CMD_RESET and pkt_statistics OR'ed
with STAT_ABORTED.
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 corresponding to commands active in the target
must be returned with pkt_reason set to CMD_TIMEOUT and pkt_statistics
OR'ed with STAT_TIMEOUT and STAT_BUS_RESET. All queued packets for
other targets on this bus must be returned with pkt_reason set to
CMD_RESET and pkt_statistics OR'ed with STAT_ABORTED.
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 de‐
vice on the bus, respectively.
tran_start() 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.
pkt_resid For commands with data transfer, this member must be
updated to indicate the residual of the data trans‐
ferred.
pkt_reason The reason for the command completion. This field
should be set to CMD_CMPLT at the beginning of
tran_start(), then updated if the command ever tran‐
sitions to an abnormal termination state. To avoid
losing information, do not set pkt_reason to any
other error state unless it still has its original
CMD_CMPLT value.
pkt_statistics Bit field of transport-related statistics.
pkt_state Bit field with the major states through which a SCSI
command can transition. Note: The members listed
above, and pkt_hba_private member, are the only
fields in the scsi_pkt(9S) structure which may be
modified by the transport layer.
RETURN VALUES
tran_start() must return:
TRAN_ACCEPT The packet was accepted by the transport layer.
TRAN_BUSY The packet could not be accepted because there was
already a packet in progress for this target/logi‐
cal unit, the HBA queue was full, or the target de‐
vice queue was full.
TRAN_BADPKT The DMA count in the packet exceeded the DMA en‐
gine's maximum DMA size, or the packet could not be
accepted for other reasons.
TRAN_FATAL_ERROR A fatal error has occurred in the HBA.
CONTEXT
The tran_start() function can be called from user or interrupt context.
This requirement comes from scsi_transport().
SEE ALSO
attach(9E), tran_init_pkt(9E), scsi_hba_attach(9F), scsi_transport(9F),
scsi_address(9S), scsi_arq_status(9S), scsi_hba_tran(9S), scsi_pkt(9S)
Writing Device Drivers in Oracle Solaris 11.4
Oracle Solaris 11.4 9 September 2024 tran_start(9E)