[Go to CFHT Home Page] Man Pages
Back to Software Index  BORDER=0Manpage Top Level
    ddi_dma_mem_alloc(9F) manual page Table of Contents

Name

ddi_dma_mem_alloc - allocate memory for DMA transfer

Synopsis

#include <sys/ddi.h>
#include <sys/sunddi.h>

int ddi_dma_mem_alloc(ddi_dma_handle_t handle, uint_t length, ddi_device_acc_attr_t *accattrp, ulong_t flags, int (*waitfp)(caddr_t), caddr_t arg, caddr_t *kaddrp, uint_t *real_length, ddi_acc_handle_t *handlep);

Arguments

handle
The DMA handle previously allocated by a call to ddi_dma_alloc_handle(9F) .
length
The length in bytes of the desired allocation.
accattrp
Pointer to a device access attribute structure of this device (see ddi_device_acc_attr(9S) ).
flags
Data transfer mode flags. Possible values are:
DDI_DMA_STREAMING
Sequential, unidirectional, block-sized, and block-aligned transfers.
DDI_DMA_CONSISTENT
Nonsequential transfers of small objects.
waitfp
The address of a function to call back later if resources are not available now. The special function addresses DDI_DMA_SLEEP and DDI_DMA_DONTWAIT are taken to mean, respectively, wait until resources are available or, do not wait and do not schedule a callback.
arg
Argument to be passed to the callback function, if such a function is specified.
kaddrp
On successful return, *kaddrp points to the allocated memory.
*real_length
The amount of memory, in bytes, allocated. Alignment and padding requirements may require ddi_dma_mem_alloc() to allocate more memory than requested in length.
handlep
Pointer to a data access handle.

Interface Level

Solaris DDI specific (Solaris DDI).

Description

ddi_dma_mem_alloc() allocates memory for DMA transfers to or from a device. The allocation will obey the alignment, padding constraints and device granularity as specified by the DMA attributes (see ddi_dma_attr(9S) ) passed to ddi_dma_alloc_handle(9F) and the more restrictive attributes imposed by the system.

flags should be set to DDI_DMA_STREAMING if the device is doing sequential, unidirectional, block-sized, and block-aligned transfers to or from memory. The alignment and padding constraints specified by the minxfer and burstsizes fields in the DMA attribute structure, ddi_dma_attr(9S) (see ddi_dma_alloc_handle(9F) ) will be used to allocate the most effective hardware support for large transfers. For example, if an I/O transfer can be sped up by using an I/O cache, which has a minimum transfer of one cache line, ddi_dma_mem_alloc() will align the memory at a cache line boundary and it will round up *real_length to a multiple of the cache line size.

flags should be set to DDI_DMA_CONSISTENT if the device accesses memory randomly, or if synchronization steps using ddi_dma_sync(9F) need to be as efficient as possible. I/O parameter blocks used for communication between a device and a driver should be allocated using DDI_DMA_CONSISTENT .

The device access attributes are specified in the location pointed by the accattrp argument (see ddi_device_acc_attr(9S) ).

The data access handle is returned in handlep. handlep is opaque - drivers may not attempt to interpret its value. To access the data content, the driver must invoke ddi_getb(9F) or ddi_putb(9F) (depending on the data transfer direction) with the data access handle.

DMA resources must be established before performing a DMA transfer by passing kaddrp and *real_length as returned from ddi_dma_mem_alloc() and the flag DDI_DMA_STREAMING or DDI_DMA_CONSISTENT to ddi_dma_addr_bind_handle(9F) . In addition, to ensure the consistency of a memory object shared between the CPU and the device after a DMA transfer, explicit synchronization steps using ddi_dma_sync(9F) or ddi_dma_unbind_handle(9F) are required.

Return Values

ddi_dma_mem_alloc() returns:

DDI_SUCCESS
Memory successfully allocated.
DDI_FAILURE
Memory allocation failed.

Context

ddi_dma_mem_alloc() can be called from user or interrupt context, except when waitfp is set to DDI_DMA_SLEEP , in which case it can be called from user context only.

See Also

ddi_dma_addr_bind_handle(9F) , ddi_dma_alloc_handle(9F) , ddi_dma_mem_free(9F) , ddi_dma_sync(9F) , ddi_dma_unbind_handle(9F) , ddi_getb(9F) , ddi_putb(9F) , ddi_device_acc_attr(9S) , ddi_dma_attr(9S)


Table of Contents