'\" te .\" Copyright (c) 2005, Sun Microsystems, Inc. .\" 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. .\" 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. .\" 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] .TH DDI_DMA_LIM_X86 9S "Oct 12, 2005" .SH NAME ddi_dma_lim_x86 \- x86 DMA limits structure .SH SYNOPSIS .LP .nf #include .fi .SH INTERFACE LEVEL .sp .LP Solaris x86 DDI specific (Solaris x86 DDI). This interface is obsolete. .SH DESCRIPTION .sp .LP A \fBddi_dma_lim\fR structure describes in a generic fashion the possible limitations of a device or its \fBDMA\fR engine. This information is used by the system when it attempts to set up \fBDMA\fR resources for a device. When the system is requested to perform a \fBDMA\fR transfer to or from an object, the request is broken up, if necessary, into multiple sub-requests. Each sub-request conforms to the limitations expressed in the \fBddi_dma_lim\fR structure. .sp .LP This structure should be filled in by calling the routine \fBddi_dmae_getlim\fR(9F). This routine sets the values of the structure members appropriately based on the characteristics of the \fBDMA\fR engine on the driver's parent bus. If the driver has additional limitations, it can \fIfurther restrict\fR some of the values in the structure members. A driver should \fInot relax\fR any restrictions imposed by \fBddi_dmae_getlim()\fR. .SH STRUCTURE MEMBERS .sp .in +2 .nf uint_t dlim_addr_lo; /* low range of 32 bit addressing capability */ uint_t dlim_addr_hi; /* inclusive upper bound of addressing capability */ uint_t dlim_minxfer; /* minimum effective dma transfer size */ uint_t dlim_version; /* version number of structure */ uint_t dlim_adreg_max; /* inclusive upper bound of incrementing addr reg */ uint_t dlim_ctreg_max; /* maximum transfer count minus one */ uint_t dlim_granular; /* granularity (and min size) of transfer count */ short dlim_sgllen; /* length of DMA scatter/gather list */ uint_t dlim_reqsize; /* maximum transfer size in bytes of a single I/O */ .fi .in -2 .sp .LP The \fBdlim_addr_lo\fR and \fBdlim_addr_hi\fR fields specify the address range that the device's \fBDMA\fR engine can access. The \fBdlim_addr_lo\fR field describes the lower 32-bit boundary of the device's \fBDMA\fR engine. The \fBdlim_addr_hi\fR member describes the inclusive, upper 32-bit boundary. The system allocates \fBDMA\fR resources in a way that the address for programming the device's \fBDMA\fR engine will be within this range. For example, if your device can access the whole 32-bit address range, you can use [\fB0,0xFFFFFFFF\fR]. See \fBddi_dma_cookie\fR(9S) or \fBddi_dma_segtocookie\fR(9F). .sp .LP The \fBdlim_minxfer\fR field describes the minimum effective \fBDMA\fR transfer size (in units of bytes), which must be a power of two. This value specifies the minimum effective granularity of the \fBDMA\fR engine and describes the minimum amount of memory that can be touched by the \fBDMA\fR transfer. As a resource request is handled by the system, the \fBdlim_minxfer\fR value can be modified. This modification is contingent upon the presence (and use) of \fBI/O\fRcaches and \fBDMA\fR write buffers between the \fBDMA\fR engine and the object that \fBDMA\fR is being performed on. After \fBDMA\fR resources have been allocated, you can retrieve the resultant minimum transfer value using \fBddi_dma_devalign\fR(9F). .sp .LP The \fBdlim_version\fR field specifies the version number of this structure. Set this field to \fBDMALIM_VER0\fR. .sp .LP The \fBdlim_adreg_max\fR field describes an inclusive upper bound for the device's \fBDMA\fR engine address register. This bound handles a fairly common case where a portion of the address register is simply a latch rather than a full register. For example, the upper 16 bits of a 32-bit address register might be a latch. This splits the address register into a portion that acts as a true address register (lower 16 bits) for a 64-kilobyte segment and a latch (upper 16 bits) to hold a segment number. To describe these limits, you specify \fB0xFFFF\fR in the \fBdlim_adreg_max\fR structure member. .sp .LP The \fBdlim_ctreg_max\fR field specifies the maximum transfer count that the \fBDMA\fR engine can handle in one segment or cookie. The limit is expressed as the maximum count minus one. This transfer count limitation is a per-segment limitation. Because the limitation is used as a bit mask, it must be one less than a power of two. .sp .LP The \fBdlim_granular\fR field describes the granularity of the device's \fBDMA\fR transfer ability, in units of bytes. This value is used to specify, for example, the sector size of a mass storage device. \fBDMA\fR requests are broken into multiples of this value. If there is no scatter/gather capability, then the size of each \fBDMA\fR transfer will be a multiple of this value. If there is scatter/gather capability, then a single segment cannot be smaller than the minimum transfer value, but can be less than the granularity. However, the total transfer length of the scatter/gather list is a multiple of the granularity value. .sp .LP The \fBdlim_sgllen\fR field specifies the maximum number of entries in the scatter/gather list. This value is the number of segments or cookies that the \fBDMA\fR engine can consume in one I/O request to the device. If the \fBDMA\fR engine has no scatter/gather list, set this field to one. .sp .LP The \fBdlim_reqsize\fR field describes the maximum number of bytes that the \fBDMA\fR engine can transmit or receive in one I/O command. This limitation is only significant if it is less than ( \fBdlim_ctreg_max\fR +1) * \fBdlim_sgllen\fR. If the \fBDMA\fR engine has no particular limitation, set this field to \fB0xFFFFFFFF\fR. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Obsolete .TE .SH SEE ALSO .sp .LP \fBddi_dmae\fR(9F), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), \fBddi_dma_devalign\fR(9F), \fBddi_dma_segtocookie\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_cookie\fR(9S), \fBddi_dma_lim_sparc\fR(9S), \fBddi_dma_req\fR(9S)