share/man/man9f/get_pktiopb.9f

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