1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH GET_PKTIOPB 9F "Jan 16, 2006"
   7 .SH NAME
   8 get_pktiopb, free_pktiopb \- allocate/free a SCSI packet in the iopb map
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13 
  14 
  15 
  16 \fBstruct scsi_pkt *\fR\fBget_pktiopb\fR(\fBstruct scsi_address *\fR\fIap\fR,
  17      \fBcaddr_t *\fR\fIdatap\fR, \fBint\fR \fIcdblen\fR, \fBint\fR \fIstatuslen\fR, \fBint\fR \fIdatalen\fR,
  18      \fBint\fR \fIreadflag\fR, \fBint (*\fR\fIcallback\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBfree_pktiopb\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, \fBcaddr_t\fR \fIdatap\fR, \fBint\fR \fIdatalen\fR);
  24 .fi
  25 
  26 .SH INTERFACE LEVEL
  27 .sp
  28 .LP
  29 These interfaces are obsolete. Use \fBscsi_alloc_consistent_buf\fR(9F) instead
  30 of \fBget_pktiopb()\fR. Use \fBscsi_free_consistent_buf\fR(9F) instead of
  31 \fBfree_pktiopb()\fR.
  32 .SH PARAMETERS
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIap\fR\fR
  37 .ad
  38 .RS 13n
  39 Pointer to the target's \fBscsi_address\fR structure.
  40 .RE
  41 
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIdatap\fR\fR
  46 .ad
  47 .RS 13n
  48 Pointer to the address of the packet, set by this function.
  49 .RE
  50 
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIcdblen\fR\fR
  55 .ad
  56 .RS 13n
  57 Number of bytes required for the \fBSCSI \fRcommand descriptor block (CDB).
  58 .RE
  59 
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIstatuslen\fR\fR
  64 .ad
  65 .RS 13n
  66 Number of bytes required for the \fBSCSI \fRstatus area.
  67 .RE
  68 
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIdatalen\fR\fR
  73 .ad
  74 .RS 13n
  75 Number of bytes required for the data area of the \fBSCSI \fRcommand.
  76 .RE
  77 
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIreadflag\fR\fR
  82 .ad
  83 .RS 13n
  84 If non-zero, data will be transferred from the \fBSCSI \fRtarget.
  85 .RE
  86 
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIcallback\fR\fR
  91 .ad
  92 .RS 13n
  93 Pointer to a callback function, or \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR
  94 .RE
  95 
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fIpkt\fR\fR
 100 .ad
 101 .RS 13n
 102 Pointer to a \fBscsi_pkt\fR(9S) structure.
 103 .RE
 104 
 105 .SH DESCRIPTION
 106 .sp
 107 .LP
 108 The \fBget_pktiopb()\fR function allocates a \fBscsi_pkt\fR structure that has
 109 a small data area allocated. It is used by some \fBSCSI \fRcommands such as
 110 \fBREQUEST_SENSE\fR, which involve a small amount of data and require
 111 cache-consistent memory for proper operation. It uses \fBddi_iopb_alloc\fR(9F)
 112 for allocating the data area and \fBscsi_resalloc\fR(9F) to allocate the packet
 113 and \fBDMA\fR resources.
 114 .sp
 115 .LP
 116 \fIcallback\fR indicates what \fBget_pktiopb()\fR should do when resources are
 117 not available:
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBNULL_FUNC\fR\fR
 122 .ad
 123 .RS 16n
 124 Do not wait for resources. Return a \fINULL\fR pointer.
 125 .RE
 126 
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBSLEEP_FUNC\fR\fR
 131 .ad
 132 .RS 16n
 133 Wait indefinitely for resources.
 134 .RE
 135 
 136 .sp
 137 .ne 2
 138 .na
 139 \fBOther Values\fR
 140 .ad
 141 .RS 16n
 142 \fIcallback\fR points to a function which is called when resources may have
 143 become available. \fIcallback\fR \fBmust\fR return either \fB0\fR (indicating
 144 that it attempted to allocate resources but failed to do so again), in which
 145 case it is put back on a list to be called again later, or \fB1\fR indicating
 146 either success in allocating resources or indicating that it no longer cares
 147 for a retry.
 148 .RE
 149 
 150 .sp
 151 .LP
 152 The \fBfree_pktiopb()\fR function is used for freeing the packet and its
 153 associated resources.
 154 .SH RETURN VALUES
 155 .sp
 156 .LP
 157 The \fBget_pktiopb()\fR function returns a pointer to the newly allocated
 158 \fBscsi_pkt\fR or a \fINULL\fR pointer.
 159 .SH CONTEXT
 160 .sp
 161 .LP
 162 If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only
 163 from user or kernel context. Otherwise, it can be called from user, interrupt,
 164 or kernel context. The \fIcallback\fR function should not block or call
 165 routines that block.
 166 .sp
 167 .LP
 168 The \fBfree_pktiopb()\fR function can be called from user, interrupt, or kernel
 169 context.
 170 .SH ATTRIBUTES
 171 .sp
 172 .LP
 173 See \fBattributes\fR(5) for a description of the following attributes:
 174 .sp
 175 
 176 .sp
 177 .TS
 178 box;
 179 c | c
 180 l | l .
 181 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 182 _
 183 Stability Level Obsolete
 184 .TE
 185 
 186 .SH SEE ALSO
 187 .sp
 188 .LP
 189 \fBattributes\fR(5), \fBddi_iopb_alloc\fR(9F),
 190 \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_free_consistent_buf\fR(9F),
 191 \fBscsi_pktalloc\fR(9F), \fBscsi_resalloc\fR(9F), \fBscsi_pkt\fR(9S)
 192 .sp
 193 .LP
 194 \fIWriting Device Drivers\fR
 195 .SH NOTES
 196 .sp
 197 .LP
 198 The \fBget_pktiopb()\fR and \fBfree_pktiopb()\fR functions are obsolete and
 199 will be discontinued in a future release. These functions have been replaced
 200 by, respectively, \fBscsi_alloc_consistent_buf\fR(9F) and
 201 \fBscsi_free_consistent_buf\fR(9F).
 202 .sp
 203 .LP
 204 The \fBget_pktiopb()\fR function uses scarce resources. For this reason and its
 205 obsolescence (see above), its use is discouraged.