'\" te
.\"  Copyright (c) 2006, Sun Microsystems, Inc.,  All Rights Reserved
.TH scsi_hba_pkt_alloc 9F "11 Dec 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
scsi_hba_pkt_alloc, scsi_hba_pkt_free \- allocate and free a scsi_pkt structure
.SH SYNOPSIS
.LP
.nf
#include <sys/scsi/scsi.h> 

\fBstruct scsi_pkt *\fR\fBscsi_hba_pkt_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, 
     \fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIcmdlen\fR, \fBint\fR \fIstatuslen\fR, 
     \fBint\fR \fItgtlen\fR, \fBint\fR \fIhbalen\fR, 
     \fBint\fR (*\fIcallback\fR)(\fBcaddr_t\fR \fIarg\fR), \fBcaddr_t\fR \fIarg\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscsi_hba_pkt_free\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBstruct scsi_pkt *\fR\fIpkt\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris architecture specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 13n
.rt  
Pointer to a \fBdev_info_t\fR structure, defining the \fBHBA\fR driver instance.
.RE

.sp
.ne 2
.mk
.na
\fB\fIap\fR\fR
.ad
.RS 13n
.rt  
Pointer to a \fBscsi_address\fR(9S) structure, defining the target instance.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcmdlen\fR\fR
.ad
.RS 13n
.rt  
Length in bytes to be allocated for the \fBSCSI\fR command descriptor block (\fBCDB\fR).
.RE

.sp
.ne 2
.mk
.na
\fB\fIstatuslen\fR\fR
.ad
.RS 13n
.rt  
Length in bytes to be allocated for the \fBSCSI\fR status completion block (\fBSCB\fR).
.RE

.sp
.ne 2
.mk
.na
\fB\fItgtlen\fR\fR
.ad
.RS 13n
.rt  
Length in bytes to be allocated for a private data area for the target driver's exclusive use.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhbalen\fR\fR
.ad
.RS 13n
.rt  
Length in bytes to be allocated for a private data area for the \fBHBA\fR driver's exclusive use.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcallback\fR\fR
.ad
.RS 13n
.rt  
Indicates what \fBscsi_hba_pkt_alloc()\fR 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

.RE

.sp
.ne 2
.mk
.na
\fB\fIarg\fR\fR
.ad
.RS 13n
.rt  
Must be \fINULL.\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fIpkt\fR\fR
.ad
.RS 13n
.rt  
A pointer to a \fBscsi_pkt\fR(9S) structure.
.RE

.SH DESCRIPTION
.sp
.LP
For \fBscsi_hba_pkt_alloc()\fR:
.sp
.LP
The \fBscsi_hba_pkt_alloc()\fR function allocates space for a \fBscsi_pkt\fR structure. \fBHBA\fR drivers must use this interface when allocating a \fBscsi_pkt\fR from their \fBtran_init_pkt\fR(9E) entry point.
.sp
.LP
If \fIcallback\fR is \fBNULL_FUNC\fR, \fBscsi_hba_pkt_alloc()\fR may not sleep when allocating resources, and callers should be prepared to deal with allocation failures.
.sp
.LP
The \fBscsi_hba_pkt_alloc()\fR function copies the \fBscsi_address\fR(9S) structure pointed to by \fIap\fR to the \fBpkt_address\fR field in the \fBscsi_pkt\fR(9S).
.sp
.LP
The \fBscsi_hba_pkt_alloc()\fR function also allocates memory for these \fBscsi_pkt\fR(9S) data areas, and sets these fields to point to the allocated memory:
.sp
.ne 2
.mk
.na
\fB\fBpkt_ha_private\fR\fR
.ad
.RS 18n
.rt  
\fBHBA\fR private data area.
.RE

.sp
.ne 2
.mk
.na
\fB\fBpkt_private\fR\fR
.ad
.RS 18n
.rt  
Target driver private data area.
.RE

.sp
.ne 2
.mk
.na
\fB\fBpkt_scbp\fR\fR
.ad
.RS 18n
.rt  
\fBSCSI\fR status completion block.
.RE

.sp
.ne 2
.mk
.na
\fB\fBpkt_cdbp\fR\fR
.ad
.RS 18n
.rt  
\fBSCSI\fR command descriptor block.
.RE

.sp
.LP
For \fBscsi_hba_pkt_free()\fR:
.sp
.LP
The \fBscsi_hba_pkt_free()\fR function frees the space allocated for the \fBscsi_pkt\fR(9S) structure.
.SH RETURN VALUES
.sp
.LP
The \fBscsi_hba_pkt_alloc()\fR function returns a pointer to the \fBscsi_pkt\fR structure, or \fINULL\fR if no space is available.
.SH CONTEXT
.sp
.LP
The \fBscsi_hba_pkt_alloc()\fR function can be called from user, interrupt, or kernel context. Drivers must not allow \fBscsi_hba_pkt_alloc()\fR to sleep if called from an interrupt routine.
.sp
.LP
The \fBscsi_hba_pkt_free()\fR function can be called from user, interrupt, or kernel context.
.SH SEE ALSO
.sp
.LP
\fBtran_init_pkt\fR(9E), \fBscsi_address\fR(9S), \fBscsi_pkt\fR(9S)
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR