'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
.TH tran_setup_pkt 9E "29 Jan 2009" "SunOS 5.11" "Driver Entry Points"
.SH NAME
tran_setup_pkt, tran_teardown_pkt, tran_pkt_constructor, tran_pkt_destructor \- SCSI HBA packet allocation and deallocation
.SH SYNOPSIS
.LP
.nf
#include <sys/scsi/scsi.h>

\fBstruct scsi_pkt *\fR\fBprefix_tran_setup_pkt\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
     \fBint (*\fR\fIcallback\fR) (\fIcaddr_t\fR), \fBcaddr_t\fR \fIarg\fR);
.fi

.LP
.nf
\fBvoid\fR \fBprefix_tran_teardown_pkt\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR);
.fi

.LP
.nf
\fBint\fR \fBprefix_tran_pkt_constructor\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
     \fBscsi_hba_tran_t *\fR\fItranp\fR, \fBint\fR \fIkmflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBprefix_tran_pkt_destructor\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
     \fBstruct scsi_hba_tran_t *\fR\fItranp\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris architecture specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIpkt\fR\fR
.ad
.RS 12n
.rt  
Pointer to the \fBscsi_pkt\fR(9S) structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 12n
.rt  
Flags for associating DMA resources with the packet.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcallback\fR\fR
.ad
.RS 12n
.rt  
Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIarg\fR\fR
.ad
.RS 12n
.rt  
Always \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIkmflags\fR\fR
.ad
.RS 12n
.rt  
Either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBtran_setup_pkt()\fR and \fBtran_destroy_pkt()\fR vectors in the \fBscsi_hba_tran\fR(9S) structure are alternatives to the \fBtran_init_pkt()\fR and \fBtran_destroy_pkt()\fR entry points. They are initialized during the \fBHBA\fR driver's \fBattach\fR(9E) and they are used when a target driver calls \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F).
.SS "tran_setup_pkt(\|)"
.sp
.LP
The \fBtran_setup_pkt()\fR vector is the entry point into the \fBHBA\fR which is used to initialize \fBHBA\fR specific information in a \fBscsi_pkt\fR structure on behalf of a SCSI target driver. All fields documented in \fBscsi_pkt\fR(9S) are initialized.
.sp
.LP
If the \fBHBA\fR driver chose not to preallocate memory for \fBpkt_cdbp\fR and/or \fBpkt_scbp\fR, it must allocate the requested memory at this time and point \fBpkt_cdbp\fR and \fBpkt_scbp\fR to the allocated memory.
.sp
.LP
An \fBHBA\fR driver which provides a \fBtran_setup_pkt\fR entry point inspects the \fBpkt_numcookies\fR and \fBpkt_cookies\fR fields at \fBtran_start\fR time to set up the transfer. If \fBpkt_numcookies\fR is zero, there are no \fBDMA\fR resources associated with this packet. If \fBpkt_numcookies\fR is not zero, it indicates the number of \fBDMA\fR cookies that \fBpkt_cookies\fR points to.
.sp
.LP
The \fBpkt_tgtlen\fR field contains the length of the packet private area pointed to by \fBpkt_private\fR, allocated on behalf of the SCSI target driver.
.sp
.LP
The \fBpkt_scblen\fR field contains the length of the SCSI status completion block pointed to by \fBpkt_scbp\fR. If the status length is greater than or equal to sizeof (\fBstruct\fR \fBscsi_arq_status\fR) and the \fBauto_rqsensecapability\fR has been set, automatic request sense (\fBARS\fR) is enabled for this packet. If the status \fBlengthislessthansizeof\fR (\fBstruct\fR \fBscsi_arq_status\fR), automatic request sense should be disabled for this pkt if the \fBHBA\fR driver is capable of disabling \fBARQ\fR on a per-packet basis.
.sp
.LP
The \fBpkt_cdblen\fR field contains the length of the SCSI command descriptor block.
.sp
.LP
The \fIcallback\fR argument indicates what the allocator routines should do when resources are not available:
.sp
.ne 2
.mk
.na
\fB\fBNULL_FUNC\fR\fR
.ad
.RS 14n
.rt  
Do not wait for resources. Return a \fINULL\fR pointer.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSLEEP_FUNC\fR\fR
.ad
.RS 14n
.rt  
Wait indefinitely for resources.
.RE

.SS "tran_teardown_pkt(\|)"
.sp
.LP
The \fBtran_teardown_pkt()\fR is the entry point into the \fBHBA\fR that must free all of the resources that were allocated to the \fBscsi_pkt\fR(9S) structure during \fBtran_setup_pkt()\fR.
.SS "tran_pkt_constructor(\|) tran_pkt_destructor(\|)"
.sp
.LP
When using \fBtran_pkt_setup()\fR and \fBtran_pkt_teardown()\fR, \fBtran_pkt_constructor()\fR and \fBtran_pkt_destructor()\fR are additional optional entry points that perform the actions of a constructor and destructor. The constructor is called after the following fields in the \fBscsi_pkt\fR structure have been initialized:
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_address\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_ha_private\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_cdbp\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_private\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_scbp\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_cdblen\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_tgtlen\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBpkt_scblen\fR
.RE
.sp
.LP
Allocating and freeing a \fBDMA\fR handle are examples of something that could be done in the constructor and destructor. See \fBkmem_cache_create\fR(9F) for additional restrictions on what actions can be performed in a constructor and destructor.
.sp
.LP
HBA drivers that implement \fBtran_setup_pkt()\fR must signal \fBscsi_pkt\fR(9S) completion by calling \fBscsi_hba_pkt_comp\fR(9F). Direct use of  the \fBscsi_pkt\fR \fIpkt_comp\fR field is not permitted and results in undefined behavior.
.SH RETURN VALUES
.sp
.LP
\fBtran_setup_pkt()\fR must return zero on success, and \fB-1\fR on failure.
.SH SEE ALSO
.sp
.LP
\fBattach\fR(9E), \fBtran_sync_pkt\fR(9E), \fBbioerror\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBkmem_cache_create\fR(9F), \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F), \fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F), \fBscsi_hba_pkt_comp\fR(9F), \fBscsi_hba_pkt_free\fR(9F), \fBscsi_init_pkt\fR(9F), \fBbuf\fR(9S), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S)
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR