ddi_dma_lim_x86(9S)					    Data Structures for Drivers 				       ddi_dma_lim_x86(9S)

NAME

       ddi_dma_lim_x86 - x86 DMA limits structure

SYNOPSIS

       #include <sys/ddidmareq.h>

INTERFACE LEVEL

       Solaris x86 DDI specific (Solaris x86 DDI)

DESCRIPTION

       A  ddi_dma_lim structure describes in a generic fashion the possible limitations of a device or its DMA engine. This information is used by
       the system when it attempts to set up DMA resources for a device.  When the system is requested to perform a DMA 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
       ddi_dma_lim structure.

       This structure should be filled in by calling the routine ddi_dmae_getlim(9F). This routine sets the values of the structure members appro-
       priately  based on the characteristics of the DMA engine on the driver's parent bus.  If the driver has additional limitations, it can fur-
       ther restrict some of the values in the structure members.  A driver should not relax any restrictions imposed by ddi_dmae_getlim().

STRUCTURE MEMBERS

       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 this 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 */

       The dlim_addr_lo and dlim_addr_hi fields specify the address range that	the  device's  DMA  engine  can  access.  The  dlim_addr_lo  field
       describes the lower 32-bit boundary of the device's DMA engine. The dlim_addr_hi member describes the inclusive, upper 32-bit boundary. The
       system allocates DMA resources in a way that the address for programming the device's DMA engine will be within this range. For example, if
       your device can access the whole 32-bit address range, you can use  [0,0xFFFFFFFF]. See ddi_dma_cookie(9S) or ddi_dma_segtocookie(9F).

       The  dlim_minxfer  field  describes  the  minimum effective DMA transfer size (in units of bytes), which must be a power of two. This value
       specifies the minimum effective granularity of the DMA engine and describes the minimum amount of memory that can be  touched  by  the  DMA
       transfer.  As a resource request is handled by the system, the dlim_minxfer value can be modified. This modification is contingent upon the
       presence (and use) of I/O caches and DMA write buffers between the DMA engine and the object that DMA is  being	performed  on.	After  DMA
       resources have been allocated, you can retrieve the resultant minimum transfer value using ddi_dma_devalign(9F).

       The  dlim_version field specifies the version number of this structure. Set this field to DMALIM_VER0.

       The  dlim_adreg_max field describes an inclusive upper bound for the device's DMA engine address register. This bound handles a fairly com-
       mon 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  0xFFFF  in  the
       dlim_adreg_max structure member.

       The   dlim_ctreg_max  field  specifies  the  maximum  transfer count that the DMA 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.

       The  dlim_granular field describes the granularity of the device's DMA transfer ability, in units of bytes.  This value is used to specify,
       for example, the sector size of a mass storage device. DMA requests are broken into multiples of this value.  If there is no scatter/gather
       capability, then the size of each DMA transfer will be a multiple of this value.  If there is scatter/gather capability, then a single seg-
       ment 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.

       The   dlim_sgllen field specifies the maximum number of entries in the scatter/gather list. This value is the number of segments or cookies
       that the DMA engine can consume in one I/O request to the device.  If the DMA engine has no scatter/gather list, set this field to one.

       The  dlim_reqsize field describes the maximum number of bytes that the DMA engine can transmit or receive in one I/O command.  This limita-
       tion  is  only  significant if it is less than ( dlim_ctreg_max +1) * dlim_sgllen. If the DMA engine has no particular limitation, set this
       field to 0xFFFFFFFF.

SEE ALSO

       ddi_dmae(9F),   ddi_dma_addr_setup(9F),	 ddi_dma_buf_setup(9F),    ddi_dma_devalign(9F),    ddi_dma_segtocookie(9F),	ddi_dma_setup(9F),
       ddi_dma_cookie(9S) ddi_dma_lim_sparc(9S), ddi_dma_req(9S)

SunOS 5.10							    31 Jan 1994 					       ddi_dma_lim_x86(9S)