1 '\" te
   2 .\" Copyright (c) 2005, 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 DDI_DMA_LIM_SPARC 9S "Oct 12, 2005"
   7 .SH NAME
   8 ddi_dma_lim_sparc, ddi_dma_lim \- SPARC DMA limits structure
  10 .LP
  11 .nf
  12 #include <sys/ddidmareq.h>
  13 .fi
  16 .sp
  17 .LP
  18 Solaris SPARC DDI specific (Solaris SPARC DDI). These interfaces are obsolete.
  20 .sp
  21 .LP
  22 This page describes the SPARC version of the \fBddi_dma_lim\fR structure. See
  23 \fBddi_dma_lim_x86\fR(9S) for a description of the x86 version of this
  24 structure.
  25 .sp
  26 .LP
  27 A \fBddi_dma_lim\fR structure describes in a generic fashion the possible
  28 limitations of a device's \fBDMA\fR engine. This information is used by the
  29 system when it attempts to set up \fBDMA\fR resources for a device.
  31 .sp
  32 .in +2
  33 .nf
  34 uint_t  dlim_addr_lo; /* low range of 32 bit
  35                                        addressing capability */
  36 uint_t  dlim_addr_hi;    /* inclusive upper bound of address.
  37                              capability */
  38 uint_t  dlim_cntr_max;   /* inclusive upper bound of
  39                             dma engine address limit * /
  40 uint_t  dlim_burstsizes; /* binary encoded dma burst sizes */
  41 uint_t  dlim_minxfer;    /* minimum effective dma xfer size */
  42 uint_t  dlim_dmaspeed;   /* average dma data rate (kb/s) */
  43 .fi
  44 .in -2
  46 .sp
  47 .LP
  48 The \fBdlim_addr_lo\fR and \fBdlim_addr_hi\fR fields specify the address range
  49 the device's \fBDMA\fR engine can access. The \fBdlim_addr_lo\fR field
  50 describes the lower 32-bit boundary of the device's \fBDMA\fR engine, the
  51 \fBdlim_addr_hi\fR describes the inclusive upper 32-bit boundary. The system
  52 allocates \fBDMA\fR resources in a way that the address for programming the
  53 device's \fBDMA\fR engine (see \fBddi_dma_cookie\fR(9S) or
  54 \fBddi_dma_htoc\fR(9F)) is within this range. For example, if your device can
  55 access the whole 32-bit address range, you may use  [\fB0\fR,\fB0xFFFFFFFF\fR].
  56 If your device has just a 16-bit address  register but will access the top of
  57 the 32-bit address range, then  [\fB0xFFFF0000\fR,\fB0xFFFFFFFF\fR] is the
  58 right limit.
  59 .sp
  60 .LP
  61 The \fBdlim_cntr_max\fR field describes an inclusive upper bound for the
  62 device's \fBDMA\fR engine address register. This handles a fairly common case
  63 where a portion of the address register is only a latch rather than a full
  64 register. For example, the upper 8 bits of a 32-bit address register can be a
  65 latch. This splits the address register into a portion that acts as a true
  66 address register (24 bits) for a 16 Mbyte segment and a latch (8 bits) to hold
  67 a segment number. To describe these limits, specify  \fB0xFFFFFF\fR in the
  68 \fBdlim_cntr_max\fR structure.
  69 .sp
  70 .LP
  71 The \fBdlim_burstsizes\fR field describes the possible burst sizes the device's
  72 \fBDMA\fR engine can accept. At the time of a \fBDMA\fR resource request, this
  73 element defines the possible \fBDMA\fR burst cycle sizes that the requester's
  74 \fBDMA\fR engine can handle. The format of the data is binary encoding of burst
  75 sizes assumed to be powers of two. That is, if a \fBDMA\fR engine is capable of
  76 doing 1-, 2-, 4-, and 16-byte transfers, the encoding ix 0x17. If the device is
  77 an SBus device and can take advantage of a 64-bit SBus, the lower 16 bits are
  78 used to specify the burst size for 32-bit transfers and the upper 16 bits are
  79 used to specify the burst size for 64-bit transfers. As the resource request is
  80 handled by the system, the \fBburstsizes\fR value can be modified. Prior to
  81 enabling \fBDMA\fR for the specific device, the driver that owns the \fBDMA\fR
  82 engine should check (using \fBddi_dma_burstsizes\fR(9F)) what the allowed
  83 \fBburstsizes\fR have become and program the \fBDMA\fR engine appropriately.
  84 .sp
  85 .LP
  86 The \fBdlim_minxfer\fR field describes the minimum effective \fBDMA\fR transfer
  87 size (in units of bytes). It must be a power of two. This value specifies the
  88 minimum effective granularity of the \fBDMA\fR engine. It is distinct from
  89 \fBdlim_burstsizes\fR in that it describes the minimum amount of access a
  90 \fBDMA\fR transfer will effect. \fBdlim_burstsizes\fR describes in what
  91 electrical fashion the \fBDMA\fR engine might perform its accesses, while
  92 \fBdlim_minxfer\fR describes the minimum amount of memory that can be touched
  93 by the \fBDMA\fR transfer. As a resource request is handled by the system, the
  94 \fBdlim_minxfer\fR value can be modified contingent upon the presence (and use)
  95 of \fBI/O \fRcaches and \fBDMA\fR write buffers in between the \fBDMA\fR engine
  96 and the object that \fBDMA\fR is being performed on. After \fBDMA\fR resources
  97 have been allocated, the resultant minimum transfer value can be gotten using
  98 \fBddi_dma_devalign\fR(9F).
  99 .sp
 100 .LP
 101 The field \fBdlim_dmaspeed\fR is the expected average data rate for the
 102 \fBDMA\fR engine (in units of kilobytes per second). Note that this should not
 103 be the maximum, or peak, burst data rate, but a reasonable guess as to the
 104 average throughput. This field is entirely optional and can be left as zero.
 105 Its intended use is to provide some hints about how much of the \fBDMA\fR
 106 resource this device might need.
 108 .sp
 109 .LP
 110 See \fBattributes\fR(5) for descriptions of the following attributes:
 111 .sp
 113 .sp
 114 .TS
 115 box;
 116 c | c
 117 l | l .
 119 _
 120 Interface Stability     Obsolete
 121 .TE
 124 .sp
 125 .LP
 126 \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F),
 127 \fBddi_dma_burstsizes\fR(9F), \fBddi_dma_devalign\fR(9F),
 128 \fBddi_dma_htoc\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_cookie\fR(9S),
 129 \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S)