Print this page
4888 Undocument dma_req(9s)
4884 EOF scsi_hba_attach
4886 EOF ddi_dmae_getlim
4887 EOF ddi_iomin
4634 undocument scsi_hba_attach() and ddi_dma_lim(9s)
4630 clean stale references to ddi_iopb_alloc and ddi_iopb_free
   1 '\" te

   2 .\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
   3 .\" Copyright 2012 Garrett D'Amore <garrett@damore.org>.  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 DDI_DMAE_REQ 9S "Feb 06, 2012"
   8 .SH NAME
   9 ddi_dmae_req \- DMA engine request structure
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/dma_engine.h>
  14 .fi
  15 
  16 .SH INTERFACE LEVEL
  17 .sp
  18 .LP
  19 Solaris x86 DDI specific (Solaris x86 DDI).
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 A device driver uses the \fBddi_dmae_req\fR structure to describe the
  24 parameters for a \fBDMA\fR channel. This structure contains all the information
  25 necessary to set up the channel, except for the \fBDMA\fR memory address and
  26 transfer count. The defaults, as specified below, support most standard
  27 devices. Other modes might be desirable for some devices, or to increase


  71 scatter/gather operation. In this mode of operation, the driver calls
  72 \fBddi_dmae_prog()\fR to give the \fBDMA\fR engine the \fBDMA\fR engine request
  73 structure and a pointer to the first cookie. The \fBproc\fR structure member
  74 must be set to the address of a driver \fBnextcookie\fR routine. This routine
  75 takes one argument, specified by the \fBprocparms\fR structure member, and
  76 returns a pointer to a structure of type \fBddi_dma_cookie_t\fR that specifies
  77 the next cookie for the \fBI/O \fR transfer. When the \fBDMA\fR engine is ready
  78 to receive an additional cookie, the bus nexus driver controlling that
  79 \fBDMA\fR engine calls the routine specified by the \fBproc\fR structure member
  80 to obtain the next cookie from the driver. The driver's \fBnextcookie\fR
  81 routine must then return the address of the next cookie (in static storage) to
  82 the bus nexus routine that called it. If there are no more segments in the
  83 current \fBDMA\fR window, then \fB(*proc)()\fR must return the \fBNULL\fR
  84 pointer.
  85 .sp
  86 A driver can specify the \fBDMAE_BUF_CHAIN\fR flag only if the particular bus
  87 architecture supports the use of multiple \fBDMA\fR cookies in a single
  88 \fBI/O\fR transfer. A bus \fBDMA\fR engine can support this feature either with
  89 a fixed-length scatter/gather list, or by an interrupt chaining feature. A
  90 driver must determine whether its parent bus nexus supports this feature by
  91 examining the scatter/gather list size returned in the \fBdlim_sgllen\fR member
  92 of the \fBDMA\fR limit structure returned by the driver's call to
  93 \fBddi_dmae_getlim()\fR. (See \fBddi_dma_lim_x86\fR(9S).) If the size of the
  94 scatter/gather list is 1, then no chaining is available. The driver must not
  95 specify the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR structure it
  96 passes to \fBddi_dmae_prog()\fR, and the driver need not provide a
  97 \fBnextcookie\fR routine.
  98 .sp
  99 If the size of the scatter/gather list is greater than 1, then \fBDMA\fR
 100 chaining is available, and the driver has two options. Under the first option,
 101 the driver chooses not to use the chaining feature. In this case (a) the driver
 102 must \fBset\fR the size of the scatter/gather list to 1 before passing it to
 103 the \fBDMA\fR setup routine, and (b) the driver must not set the
 104 \fBDMAE_BUF_CHAIN\fR flag.
 105 .sp
 106 Under the second option, the driver chooses to use the chaining feature, in
 107 which case, (a) it should leave the size of the scatter/gather list alone, and
 108 (b) it must set the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR
 109 structure. Before calling \fBddi_dmae_prog()\fR, the driver must \fIprefetch\fR
 110 cookies until either (1) the end of the DMA window is
 111 reached, or (2) the size of the
 112 scatter/gather list is reached, whichever occurs first. These cookies must be
 113 saved by the driver until they are requested by the nexus driver calling the


 138 memory position and alignment of the \fBDMA\fR object, all or just part of the
 139 current \fBDMA\fR window might be able to participate in a single \fBI/O\fR
 140 operation. The driver must compute the \fBI/O\fR count by adding up the sizes
 141 of the prefetched \fBDMA\fR cookies. The number of cookies whose sizes are to
 142 be summed is the lesser of (a) the size of the scatter/gather list, or (b) the
 143 number of segments remaining in the window.
 144 .RE
 145 .RS +4
 146 .TP
 147 .ie t \(bu
 148 .el o
 149 Second, on some bus architectures, the driver's \fBnextcookie\fR routine can be
 150 called from a high-level interrupt routine. If the cookies were not prefetched,
 151 the \fBnextcookie\fR routine would have to call \fBDMA\fR functions
 152 from a high-level interrupt routine, which is not
 153 recommended.
 154 .RE
 155 When breaking a \fBDMA\fR window into segments, the system arranges for the end
 156 of every segment whose number is an integral multiple of the scatter/gather
 157 list size to fall on a device-granularity boundary, as specified in the
 158 \fBdlim_granular\fR field in the \fBddi_dma_lim_x86\fR(9S) structure.
 159 .sp
 160 If the scatter/gather list size is 1 (either because no chaining is available
 161 or because the driver does not want to use the chaining feature), then the
 162 total \fBI/O\fR count for a single \fBDMA\fR operation is the size of \fBDMA\fR
 163 segment denoted by the single \fBDMA\fR cookie that is passed in the call to
 164 \fBddi_dmae_prog()\fR. In this case, the system arranges for each \fBDMA\fR
 165 segment to be a multiple of the device-granularity size.
 166 .RE
 167 
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBder_path\fR\fR
 172 .ad
 173 .RS 18n
 174 Specifies the \fBDMA\fR transfer size. The default of zero
 175 (\fBDMAE_PATH_DEF\fR) specifies \fBISA\fR compatibility mode. In that mode,
 176 channels 0, 1, 2, and 3 are programmed in 8-bit mode (\fBDMAE_PATH_8\fR), and
 177 channels 5, 6, and 7 are programmed in 16-bit, count-by-word mode
 178 (\fBDMAE_PATH_16\fR).


 207 .SH ATTRIBUTES
 208 .sp
 209 .LP
 210 See \fBattributes\fR(5) for descriptions of the following attributes:
 211 .sp
 212 
 213 .sp
 214 .TS
 215 box;
 216 c | c
 217 l | l .
 218 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 219 _
 220 Architecture    x86
 221 .TE
 222 
 223 .SH SEE ALSO
 224 .sp
 225 .LP
 226 \fBisa\fR(4), \fBattributes\fR(5),
 227 \fBddi_dmae\fR(9F), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S)
   1 '\" te
   2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   3 .\" Copyright (c) 2004, 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 DDI_DMAE_REQ 9S "May 24, 2014"
   8 .SH NAME
   9 ddi_dmae_req \- DMA engine request structure
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/dma_engine.h>
  14 .fi
  15 
  16 .SH INTERFACE LEVEL
  17 .sp
  18 .LP
  19 Solaris x86 DDI specific (Solaris x86 DDI).
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 A device driver uses the \fBddi_dmae_req\fR structure to describe the
  24 parameters for a \fBDMA\fR channel. This structure contains all the information
  25 necessary to set up the channel, except for the \fBDMA\fR memory address and
  26 transfer count. The defaults, as specified below, support most standard
  27 devices. Other modes might be desirable for some devices, or to increase


  71 scatter/gather operation. In this mode of operation, the driver calls
  72 \fBddi_dmae_prog()\fR to give the \fBDMA\fR engine the \fBDMA\fR engine request
  73 structure and a pointer to the first cookie. The \fBproc\fR structure member
  74 must be set to the address of a driver \fBnextcookie\fR routine. This routine
  75 takes one argument, specified by the \fBprocparms\fR structure member, and
  76 returns a pointer to a structure of type \fBddi_dma_cookie_t\fR that specifies
  77 the next cookie for the \fBI/O \fR transfer. When the \fBDMA\fR engine is ready
  78 to receive an additional cookie, the bus nexus driver controlling that
  79 \fBDMA\fR engine calls the routine specified by the \fBproc\fR structure member
  80 to obtain the next cookie from the driver. The driver's \fBnextcookie\fR
  81 routine must then return the address of the next cookie (in static storage) to
  82 the bus nexus routine that called it. If there are no more segments in the
  83 current \fBDMA\fR window, then \fB(*proc)()\fR must return the \fBNULL\fR
  84 pointer.
  85 .sp
  86 A driver can specify the \fBDMAE_BUF_CHAIN\fR flag only if the particular bus
  87 architecture supports the use of multiple \fBDMA\fR cookies in a single
  88 \fBI/O\fR transfer. A bus \fBDMA\fR engine can support this feature either with
  89 a fixed-length scatter/gather list, or by an interrupt chaining feature. A
  90 driver must determine whether its parent bus nexus supports this feature by
  91 examining the scatter/gather list size returned in the \fBdma_attr_sgllen\fR
  92 member of the \fBDMA\fR attributes structure returned by the driver's call to
  93 \fBddi_dmae_getattr()\fR. (See \fBddi_dma_attr\fR(9S).) If the size of the
  94 scatter/gather list is 1, then no chaining is available. The driver must not
  95 specify the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR structure it
  96 passes to \fBddi_dmae_prog()\fR, and the driver need not provide a
  97 \fBnextcookie\fR routine.
  98 .sp
  99 If the size of the scatter/gather list is greater than 1, then \fBDMA\fR
 100 chaining is available, and the driver has two options. Under the first option,
 101 the driver chooses not to use the chaining feature. In this case (a) the driver
 102 must \fBset\fR the size of the scatter/gather list to 1 before passing it to
 103 the \fBDMA\fR setup routine, and (b) the driver must not set the
 104 \fBDMAE_BUF_CHAIN\fR flag.
 105 .sp
 106 Under the second option, the driver chooses to use the chaining feature, in
 107 which case, (a) it should leave the size of the scatter/gather list alone, and
 108 (b) it must set the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR
 109 structure. Before calling \fBddi_dmae_prog()\fR, the driver must \fIprefetch\fR
 110 cookies until either (1) the end of the DMA window is
 111 reached, or (2) the size of the
 112 scatter/gather list is reached, whichever occurs first. These cookies must be
 113 saved by the driver until they are requested by the nexus driver calling the


 138 memory position and alignment of the \fBDMA\fR object, all or just part of the
 139 current \fBDMA\fR window might be able to participate in a single \fBI/O\fR
 140 operation. The driver must compute the \fBI/O\fR count by adding up the sizes
 141 of the prefetched \fBDMA\fR cookies. The number of cookies whose sizes are to
 142 be summed is the lesser of (a) the size of the scatter/gather list, or (b) the
 143 number of segments remaining in the window.
 144 .RE
 145 .RS +4
 146 .TP
 147 .ie t \(bu
 148 .el o
 149 Second, on some bus architectures, the driver's \fBnextcookie\fR routine can be
 150 called from a high-level interrupt routine. If the cookies were not prefetched,
 151 the \fBnextcookie\fR routine would have to call \fBDMA\fR functions
 152 from a high-level interrupt routine, which is not
 153 recommended.
 154 .RE
 155 When breaking a \fBDMA\fR window into segments, the system arranges for the end
 156 of every segment whose number is an integral multiple of the scatter/gather
 157 list size to fall on a device-granularity boundary, as specified in the
 158 \fBdma_attr_granular\fR field in the \fBddi_dma_attr\fR(9S) structure.
 159 .sp
 160 If the scatter/gather list size is 1 (either because no chaining is available
 161 or because the driver does not want to use the chaining feature), then the
 162 total \fBI/O\fR count for a single \fBDMA\fR operation is the size of \fBDMA\fR
 163 segment denoted by the single \fBDMA\fR cookie that is passed in the call to
 164 \fBddi_dmae_prog()\fR. In this case, the system arranges for each \fBDMA\fR
 165 segment to be a multiple of the device-granularity size.
 166 .RE
 167 
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBder_path\fR\fR
 172 .ad
 173 .RS 18n
 174 Specifies the \fBDMA\fR transfer size. The default of zero
 175 (\fBDMAE_PATH_DEF\fR) specifies \fBISA\fR compatibility mode. In that mode,
 176 channels 0, 1, 2, and 3 are programmed in 8-bit mode (\fBDMAE_PATH_8\fR), and
 177 channels 5, 6, and 7 are programmed in 16-bit, count-by-word mode
 178 (\fBDMAE_PATH_16\fR).


 207 .SH ATTRIBUTES
 208 .sp
 209 .LP
 210 See \fBattributes\fR(5) for descriptions of the following attributes:
 211 .sp
 212 
 213 .sp
 214 .TS
 215 box;
 216 c | c
 217 l | l .
 218 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 219 _
 220 Architecture    x86
 221 .TE
 222 
 223 .SH SEE ALSO
 224 .sp
 225 .LP
 226 \fBisa\fR(4), \fBattributes\fR(5),
 227 \fBddi_dmae\fR(9F), \fBddi_dma_attr\fR(9S)