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

NAME

       ddi_dma_attr - DMA attributes structure

SYNOPSIS

       #include <sys/ddidmareq.h>

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

DESCRIPTION

       A   ddi_dma_attr_t  structure  describes device- and  DMA engine-specific attributes necessary to allocate  DMA resources for a device. The
       driver might have to extend the attributes with bus-specific information, depending on the bus to which the device is connected.

STRUCTURE MEMBERS

       uint_t	   dma_attr_version;	  /* version number */
       uint64_t    dma_attr_addr_lo;	  /* low DMA address range */
       uint64_t    dma_attr_addr_hi;	  /* high DMA address range */
       uint64_t    dma_attr_count_max;	  /* DMA counter register */
       uint64_t    dma_attr_align;	  /* DMA address alignment */
       uint_t	   dma_attr_burstsizes;   /* DMA burstsizes */
       uint32_t    dma_attr_minxfer;	  /* min effective DMA size */
       uint64_t    dma_attr_maxxfer;	  /* max DMA xfer size */
       uint64_t    dma_attr_seg;	  /* segment boundary */
       int	   dma_attr_sgllen;	  /* s/g list length */
       uint32_t    dma_attr_granular;	  /* granularity of device */
       uint_t	   dma_attr_flags;	  /* DMA transfer flags */

       dma_attr_version stores the version number of this DMA attribute structure. It should be set to DMA_ATTR_V0.

       The dma_attr_addr_lo and dma_attr_addr_hi fields specify the address range the device's DMA engine can access. The  dma_attr_addr_lo  field
       describes the inclusive lower 64-bit boundary.  The dma_attr_addr_hi describes the inclusive upper 64-bit boundary. The system ensures that
       allocated DMA resources are within the range specified. See ddi_dma_cookie(9S).

       The  dma_attr_count_max describes an inclusive upper bound for the device's  DMA counter register. For example, 0xFFFFFF would  describe  a
       DMA  engine  with a 24-bit counter register. DMA resource allocation functions have to break up a  DMA object into multiple  DMA cookies if
       the size of the object exceeds the size of the  DMA counter register.

       The dma_attr_align specifies alignment requirements for allocated DMA resources. This field can be used to force more restrictive alignment
       than imposed by dma_attr_burstsizes or dma_attr_minxfer, such as alignment at a page boundary. Most drivers set this field to 1, indicating
       byte alignment.

       Note that dma_attr_align only specifies alignment requirements for allocated DMA resources. The	buffer	passed	to  ddi_dma_addr_bind_han-
       dle(9F) or ddi_dma_buf_bind_handle(9F) must have an equally restrictive alignment (see ddi_dma_mem_alloc(9F)).

       The   dma_attr_burstsizes  field  describes  the  possible burst sizes the device's  DMA engine can accept. The format of the data sizes is
       binary encoded in terms of powers of two. When DMA resources are allocated, the system can modify the burstsizes value to reflect the  sys-
       tem limits. The driver must use the allowable burstsizes to program the DMA engine. See ddi_dma_burstsizes(9F).

       The  dma_attr_minxfer field describes the minimum effective  DMA access size in units of bytes. DMA resources can be modified, depending on
       the presence and use of I/O caches and write buffers between the DMA engine and the memory object. This field is used to  determine  align-
       ment and padding requirements for ddi_dma_mem_alloc(9F).

       The  dma_attr_maxxfer field describes the maximum effective DMA access size in units of bytes.

       The   dma_attr_seg  field  specifies  segment boundary restrictions for allocated DMA resources. The system allocates DMA resources for the
       device so that the object does not span the segment boundary specified by dma_attr_seg. For example, a value of 0xFFFF means DMA  resources
       must  not  cross  a  64 Kbyte boundary.	DMA resource allocation functions might have to break up a DMA object into multiple DMA cookies to
       enforce segment boundary restrictions. In this case, the transfer must be performed using scatter-gather I/O or multiple DMA windows.

       The dma_attr_sgllen field describes the length of the device's DMA scatter/gather list. Possible values are as follows:

       < 0	Device	DMA engine is not constrained by the size, for example, withDMA chaining.

       = 0	Reserved.

       = 1	Device	DMA engine does not support scatter/gather such as third party DMA.

       > 1	Device	DMA engine uses scatter/gather. dma_attr_sgllen is the maximum number of entries in the list.

       The dma_attr_granular field describes the granularity of the device transfer size, in  units  of  bytes.  When  the  system  allocates  DMA
       resources,  a  single segment's size is a multiple of the device granularity. Or if   dma_attr_sgllen is larger than 1 within a window, the
       sum of the sizes for a subgroup of segments is a multiple of the device granularity.

       Note that all driver requests for DMA resources must be a multiple of the granularity of the device transfer size.

       The dma_attr_flags field can be set to:

       DDI_DMA_FORCE_PHYSICAL

	   Some platforms, such as SPARC systems, support what is called Direct Virtual Memory Access (DVMA). On these platforms,  the	device	is
	   provided  with  a  virtual  address	by  the system in order to perform the transfer. In this case, the underlying platform provides an
	   IOMMU, which translates accesses to these virtual addresses into the proper physical addresses. Some of these  platforms  also  support
	   DMA.  DDI_DMA_FORCE_PHYSICAL  indicates that the system should return physical rather than virtual I/O addresses if the system supports
	   both. If the system does not support physical DMA, the return value from ddi_dma_alloc_handle(9F)  will  be	DDI_DMA_BADATTR.  In  this
	   case, the driver has to clear DDI_DMA_FORCE_PHYSICAL and retry the operation.

EXAMPLES

       Example 1: Initializing the ddi_dma_attr_t Structure

       Assume a device has the following  DMA characteristics:

	 o  Full 32-bit range addressable

	 o  24-bit DMA counter register

	 o  Byte alignment

	 o  4- and 8-byte burst sizes support

	 o  Minimum effective transfer size of 1 bytes

	 o  64 Mbyte maximum transfer size limit

	 o  Maximum segment size of 32 Kbyte

	 o  17 scatter/gather list elements

	 o  512-byte device transfer size granularity

       The corresponding ddi_dma_attr_t structure is initialized as follows:

       static ddi_dma_attr_t dma_attrs = {
		DMA_ATTR_V0		 /* version number */
		(uint64_t)0x0,		 /* low address */
		(uint64_t)0xffffffff,	 /* high address */
		(uint64_t)0xffffff,	 /* DMA counter max */
		(uint64_t)0x1		 /* alignment */
		0x0c,			 /* burst sizes */
		0x1,			 /* minimum transfer size */
		(uint64_t)0x3ffffff,	 /* maximum transfer size */
		(uint64_t)0x7fff,	 /* maximum segment size */
		17,			 /* scatter/gather list lgth */
		512			 /* granularity */
		0			 /* DMA flags */
       };

SEE ALSO

       ddi_dma_addr_bind_handle(9F),   ddi_dma_alloc_handle(9F),   ddi_dma_buf_bind_handle(9F),   ddi_dma_burstsizes(9F),   ddi_dma_mem_alloc(9F),
       ddi_dma_nextcookie(9F), ddi_dma_cookie(9S)

       Writing Device Drivers

SunOS 5.10							    26 Sep 1996 						  ddi_dma_attr(9S)