usr/src/man/man9f/scsi_dmaget.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.
   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 SCSI_DMAGET 9F "Jan 16, 2006"
   7 .SH NAME
   8 scsi_dmaget, scsi_dmafree \- SCSI dma utility routines
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13
  14
  15
  16 \fBstruct scsi_pkt *\fR\fBscsi_dmaget\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR,
  17      \fBopaque_t\fR \fIdmatoken\fR, \fBint\fR\fB(*\fRcallback\fB)(void)\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBscsi_dmafree\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR);
  23 .fi
  24
  25 .SH INTERFACE LEVEL
  26 .sp
  27 .LP
  28 These interfaces are obsolete. Use \fBscsi_init_pkt\fR(9F) instead of
  29 \fBscsi_dmaget()\fR. Use \fBscsi_destroy_pkt\fR(9F) instead of
  30 \fBscsi_dmafree()\fR.
  31 .SH PARAMETERS
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIpkt\fR\fR
  36 .ad
  37 .RS 12n
  38 A pointer to a \fBscsi_pkt\fR(9S) structure.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIdmatoken\fR\fR
  45 .ad
  46 .RS 12n
  47 Pointer to an implementation dependent object.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIcallback\fR\fR
  54 .ad
  55 .RS 12n
  56 Pointer to a callback function, or \fBNULL_FUNC\fR or \fBSLEEP_FUNC.\fR
  57 .RE
  58
  59 .SH DESCRIPTION
  60 .sp
  61 .LP
  62 The \fBscsi_dmaget()\fR function allocates \fBDMA\fR resources for an already
  63 allocated \fBSCSI\fR packet. \fIpkt\fR is a pointer to the previously allocated
  64 \fBSCSI\fR packet (see \fBscsi_pktalloc\fR(9F)).
  65 .sp
  66 .LP
  67 The \fIdmatoken\fR parameter is a pointer to an implementation dependent object
  68 which defines the length, direction, and address of the data transfer
  69 associated with this \fBSCSI \fRpacket (command). The \fIdmatoken\fR must be a
  70 pointer to a \fBbuf\fR(9S) structure. If \fIdmatoken\fR is \fINULL\fR, no
  71 resources are allocated.
  72 .sp
  73 .LP
  74 The \fIcallback\fR parameter indicates what \fBscsi_dmaget()\fR should do when
  75 resources are not available:
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBNULL_FUNC\fR\fR
  80 .ad
  81 .RS 16n
  82 Do not wait for resources. Return a \fINULL\fR pointer.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBSLEEP_FUNC\fR\fR
  89 .ad
  90 .RS 16n
  91 Wait indefinitely for resources.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fBOther Values\fR
  98 .ad
  99 .RS 16n
 100 \fIcallback\fR points to a function which is called when resources may have
 101 become available. \fIcallback\fR must return either \fB0\fR (indicating that it
 102 attempted to allocate resources but failed to do so again), in which case it is
 103 put back on a list to be called again later, or \fB1\fR indicating either
 104 success in allocating resources or indicating that it no longer cares for a
 105 retry.
 106 .RE
 107
 108 .sp
 109 .LP
 110 The \fBscsi_dmafree()\fR function frees the \fBDMA\fR resources associated with
 111 the \fBSCSI\fR packet. The packet itself remains allocated.
 112 .SH RETURN VALUES
 113 .sp
 114 .LP
 115 The \fBscsi_dmaget()\fR function returns a pointer to a \fBscsi_pkt\fR on
 116 success. It returns \fBNULL\fR if resources are not available.
 117 .SH CONTEXT
 118 .sp
 119 .LP
 120 If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine may only be called
 121 from user or kernel context. Otherwise, it may be called from user, kernel, or
 122 interrupt context. The \fIcallback\fR function may not block or call routines
 123 that block.
 124 .sp
 125 .LP
 126 The \fBscsi_dmafree()\fR function can be called from user, interrupt, or kernel
 127 context.
 128 .SH ATTRIBUTES
 129 .sp
 130 .LP
 131 See \fBattributes\fR(5) for a description of the following attributes:
 132 .sp
 133
 134 .sp
 135 .TS
 136 box;
 137 c | c
 138 l | l .
 139 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 140 _
 141 Stability Level Obsolete
 142 .TE
 143
 144 .SH SEE ALSO
 145 .sp
 146 .LP
 147 \fBattributes\fR(5), \fBscsi_pktalloc\fR(9F), \fBscsi_pktfree\fR(9F),
 148 \fBscsi_resalloc\fR(9F), \fBscsi_resfree\fR(9F), \fBbuf\fR(9S),
 149 \fBscsi_pkt\fR(9S)
 150 .sp
 151 .LP
 152 \fIWriting Device Drivers\fR
 153 .SH NOTES
 154 .sp
 155 .LP
 156 The \fBscsi_dmaget()\fR and \fBscsi_dmafree()\fR functions are obsolete and
 157 will be discontinued in a future release. These functions have been replaced
 158 by, respectively, \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F).