1 '\" te
   2 .\" Copyright (c) 2005, 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 DDI_DMA_LIM_X86 9S "Oct 12, 2005"
   7 .SH NAME
   8 ddi_dma_lim_x86 \- x86 DMA limits structure
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddidmareq.h>
  13 .fi
  14 
  15 .SH INTERFACE LEVEL
  16 .sp
  17 .LP
  18 Solaris x86 DDI specific (Solaris x86 DDI). This interface is obsolete.
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 A \fBddi_dma_lim\fR structure describes in a generic fashion the possible
  23 limitations of a device or its \fBDMA\fR engine. This information is used by
  24 the system when it attempts to set up \fBDMA\fR resources for a device.  When
  25 the system is requested to perform a \fBDMA\fR transfer to or from an object,
  26 the request is broken up, if necessary, into multiple sub-requests. Each
  27 sub-request conforms to the limitations expressed in the \fBddi_dma_lim\fR
  28 structure.
  29 .sp
  30 .LP
  31 This structure should be filled in by calling the routine
  32 \fBddi_dmae_getlim\fR(9F). This routine sets the values of the structure
  33 members appropriately based on the characteristics of the \fBDMA\fR engine on
  34 the driver's parent bus.  If the driver has additional limitations, it can
  35 \fIfurther restrict\fR some of the values in the structure members.  A driver
  36 should \fInot relax\fR any restrictions imposed by \fBddi_dmae_getlim()\fR.
  37 .SH STRUCTURE MEMBERS
  38 .sp
  39 .in +2
  40 .nf
  41 uint_t  dlim_addr_lo;  /* low range of 32 bit
  42                                         addressing capability */
  43 uint_t  dlim_addr_hi;  /* inclusive upper bound of
  44                           addressing capability */
  45 uint_t  dlim_minxfer;  /* minimum effective dma transfer size */
  46 uint_t  dlim_version;  /* version number of structure */
  47 uint_t  dlim_adreg_max; /* inclusive upper bound of
  48                             incrementing addr reg */
  49 uint_t  dlim_ctreg_max; /* maximum transfer count minus one */
  50 uint_t  dlim_granular; /* granularity (and min size) of
  51                           transfer count */
  52 short  dlim_sgllen;    /* length of DMA scatter/gather list */
  53 uint_t  dlim_reqsize;  /* maximum transfer size in bytes of
  54                           a single I/O */
  55 .fi
  56 .in -2
  57 
  58 .sp
  59 .LP
  60 The \fBdlim_addr_lo\fR and \fBdlim_addr_hi\fR fields specify the address range
  61 that the device's \fBDMA\fR engine can access. The \fBdlim_addr_lo\fR field
  62 describes the lower 32-bit boundary of the device's \fBDMA\fR engine. The
  63 \fBdlim_addr_hi\fR member describes the inclusive, upper 32-bit boundary. The
  64 system allocates \fBDMA\fR resources in a way that the address for programming
  65 the device's \fBDMA\fR engine will be within this range. For example, if your
  66 device can access the whole 32-bit address range, you can use
  67 [\fB0,0xFFFFFFFF\fR]. See \fBddi_dma_cookie\fR(9S) or
  68 \fBddi_dma_segtocookie\fR(9F).
  69 .sp
  70 .LP
  71 The \fBdlim_minxfer\fR field describes the minimum effective \fBDMA\fR transfer
  72 size (in units of bytes), which must be a power of two. This value specifies
  73 the minimum effective granularity of the \fBDMA\fR engine and describes the
  74 minimum amount of memory that can be touched by the \fBDMA\fR transfer. As a
  75 resource request is handled by the system, the \fBdlim_minxfer\fR value can be
  76 modified. This modification is contingent upon the presence (and use) of
  77 \fBI/O\fRcaches and \fBDMA\fR write buffers between the \fBDMA\fR engine and
  78 the object that \fBDMA\fR is being performed on. After \fBDMA\fR resources have
  79 been allocated, you can retrieve the resultant minimum transfer value using
  80 \fBddi_dma_devalign\fR(9F).
  81 .sp
  82 .LP
  83 The \fBdlim_version\fR field specifies the version number of this structure.
  84 Set this field to \fBDMALIM_VER0\fR.
  85 .sp
  86 .LP
  87 The \fBdlim_adreg_max\fR field describes an inclusive upper bound for the
  88 device's \fBDMA\fR engine address register. This bound handles a fairly common
  89 case where a portion of the address register is simply a latch rather than a
  90 full register. For example, the upper 16 bits of a 32-bit address register
  91 might be a latch. This splits the address register into a portion that acts as
  92 a true address register (lower 16 bits) for a 64-kilobyte segment and a latch
  93 (upper 16 bits) to hold a segment number. To describe these limits, you specify
  94 \fB0xFFFF\fR in the \fBdlim_adreg_max\fR structure member.
  95 .sp
  96 .LP
  97 The \fBdlim_ctreg_max\fR field specifies the maximum transfer count that the
  98 \fBDMA\fR engine can handle in one segment or cookie.  The limit is expressed
  99 as the maximum count minus one. This transfer count limitation is a per-segment
 100 limitation.  Because the limitation is used as a bit mask, it must be one less
 101 than a power of two.
 102 .sp
 103 .LP
 104 The \fBdlim_granular\fR field describes the granularity of the device's
 105 \fBDMA\fR transfer ability, in units of bytes. This value is used to specify,
 106 for example, the sector size of a mass storage device. \fBDMA\fR requests are
 107 broken into multiples of this value. If there is no scatter/gather capability,
 108 then the size of each \fBDMA\fR transfer will be a multiple of this value. If
 109 there is scatter/gather capability, then a single segment cannot be smaller
 110 than the minimum transfer value, but can be less than the granularity. However,
 111 the total transfer length of the scatter/gather list is a multiple of the
 112 granularity value.
 113 .sp
 114 .LP
 115 The  \fBdlim_sgllen\fR field specifies the maximum number of entries in the
 116 scatter/gather list. This value is the number of segments or cookies that the
 117 \fBDMA\fR engine can consume in one I/O request to the device. If the \fBDMA\fR
 118 engine has no scatter/gather list, set this field to one.
 119 .sp
 120 .LP
 121 The \fBdlim_reqsize\fR field describes the maximum number of bytes that the
 122 \fBDMA\fR engine can transmit or receive in one I/O command. This limitation is
 123 only significant if it is less than ( \fBdlim_ctreg_max\fR +1) *
 124 \fBdlim_sgllen\fR. If the \fBDMA\fR engine has no particular limitation, set
 125 this field to \fB0xFFFFFFFF\fR.
 126 .SH ATTRIBUTES
 127 .sp
 128 .LP
 129 See \fBattributes\fR(5) for descriptions of the following attributes:
 130 .sp
 131 
 132 .sp
 133 .TS
 134 box;
 135 c | c
 136 l | l .
 137 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 138 _
 139 Interface Stability     Obsolete
 140 .TE
 141 
 142 .SH SEE ALSO
 143 .sp
 144 .LP
 145 \fBddi_dmae\fR(9F), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F),
 146 \fBddi_dma_devalign\fR(9F), \fBddi_dma_segtocookie\fR(9F),
 147 \fBddi_dma_setup\fR(9F), \fBddi_dma_cookie\fR(9S), \fBddi_dma_lim_sparc\fR(9S),
 148 \fBddi_dma_req\fR(9S)