Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
#include <sys/scsi/scsi.h>
Solaris DDI specific (Solaris DDI).
A scsi_pkt structure defines the packet that 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 host bus adapter (HBA) fills in 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.
opaque_t pkt_ha_private; /* private data for host adapter */ struct scsi_address pkt_address; /* destination packet */ opaque_t pkt_private; /* private data for target driver */ void (*pkt_comp)(struct scsi_pkt *); /* callback */ uint_t pkt_flags; /* flags */ int pkt_time; /* time allotted to complete command */ uchar_t *pkt_scbp; /* pointer to status block */ uchar_t *pkt_cdbp; /* pointer to command block */ ssize_t pkt_resid; /* number of bytes not transferred */ uint_t pkt_state; /* state of command */ uint_t pkt_statistics; /* statistics */ uchar_t pkt_reason; /* reason completion called */ uint_t pkt_cdblen; /* length of pkt_cdbp */ uint_t pkt_scdblen; /* length of pkt_scbp */ uint_t pkt_tgtlen; /* length of pkt_private */ uint_t pkt_numcookies; /* number of DMA cookies */ ddi_dma_cookie_t *pkt_cookies; /* array of DMA cookies */ uint_t pkt_dma_flags; /* DMA flags */pkt_ha_private
Opaque pointer that the HBA uses to reference a private data structure that transfers scsi_pkt requests.
Initialized by scsi_init_pkt(9F), pkt_address records the intended route and the recipient of a request.
Reserved for the use of the target driver, pkt_private is not changed by the HBA driver.
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 routine itself is called from interrupt context and must not sleep or call any function that might sleep.
Provides additional information about how the target driver expects the command to be executed. See pkt_flag Definitions.
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 pkt_time may be 0 if no timeout is required.
Points to either a struct scsi_status(9S) or, if auto-rqsense is enabled and pkt_state includes STATE_ARQ_DONE, a struct scsi_arq_status. If scsi_status is returned, the SCSI status byte resulting from the requested command is available. If scsi_arq_status(9S) is returned, the sense information is also available.
Points to a kernel-addressable buffer with a length specified by a call to the proper resource allocation routine, scsi_init_pkt(9F).
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 can be allocated only if scsi_init_pkt(9F) is called with the PKT_DMA_PARTIAL flag.
Has bit positions that represent the six most important states that a SCSI command can go through. See pkt_state Definitions.
Maintains some transport-related statistics. See pkt_statistics Definitions.
Contains a completion code that indicates why the pkt_comp function was called. See pkt_reason Definitions.
Length of buffer pointed to by pkt_cdbp. See tran_setup_pkt.
Length of buffer pointed to by pkt_scbp. See tran_setup_pkt.
Length of buffer pointed to by pkt_private. See tran_setup_pkt.
Length pkt_cookies array. See tran_setup_pkt.
Array of DMA cookies. See tran_setup_pkt.
DMA flags used, such as DDI_DMA_READ and DDI_DMA_WRITE. See tran_setup_pkt.
The host adapter driver will update the pkt_resid, pkt_reason, pkt_state, and pkt_statistics fields.
The appropriate definitions 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).
Run command without disconnects.
Run command without parity checking.
Run command as the head-of-queue-tagged command.
Run command as an ordered-queue-tagged command.
Run command as a simple-queue-tagged command.
Indicates a request sense command.
Place command at the head of the queue.
Before transporting this command, the host adapter should initiate the renegotiation of wide mode and synchronous transfer speed. Normally, the HBA driver manages negotiations but under certain conditions forcing a renegotiation is appropriate. Renegotiation is recommended before Request Sense and Inquiry commands. 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.
The appropriate definitions for the structure member pkt_reason are: CMD_CMPLT
No transport errors; normal completion.
Transport stopped with abnormal state.
DMAd irection error.
Unspecified transport error.
SCSI bus reset destroyed command.
Command transport aborted on request.
Command timed out.
Data overrun.
Command overrun.
Status overrun.
Message not command complete.
Target refused to go to message out phase.
Extended identify message rejected.
"Initiator Detected Error" message rejected.
Abort message rejected.
Reject message rejected.
"No Operation" message rejected.
"Message Parity Error" message rejected.
"Bus Device Reset" message rejected.
Identify message rejected.
Unexpected bus free phase.
Target rejected the tag message.
The device has been removed.
The appropriate definitions for the structure member pkt_state are: STATE_GOT_BUS
Bus arbitration succeeded.
Target successfully selected.
Command successfully sent.
Data transfer took place.
Status received.
The command resulted in a check condition and the host adapter driver executed an automatic request sense command.
The command requested in extra sense data using a PKT_XARQ flag got a check condition. The host adapter driver was able to successfully request and return this. The scsi_pkt.pkt_scbp->sts_rqpkt_resid returns the sense data residual based on the statuslen parameter of the scsi_init_pkt(9F) call. The sense data begins at scsi_pkt.pkt_scbp->sts_sensedata.
The definitions that are appropriate for the structure member pkt_statistics are: STAT_DISCON
Device disconnect.
Command did a synchronous data transfer.
SCSI parity error.
Bus reset.
Device reset.
Command was aborted.
Command timed out.
tran_init_pkt(9E), tran_setup_pkt(9E), scsi_arq_status(9S), scsi_init_pkt(9F), scsi_transport(9F), scsi_status(9S), scsi_hba_pkt_comp(9F)
Writing Device Drivers
HBA drivers should signal scsi_pkt completion by calling scsi_hba_pkt_comp(9F). This is mandatory for HBA drivers that implement tran_setup_pkt(9E). Failure to comply results in undefined behavior.