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.