ddi_dma_mem_alloc(9F) Kernel Functions for Drivers ddi_dma_mem_alloc(9F)
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, size_t length, ddi_device_acc_attr_t *accattrp, uint_t flags, int (*waitfp) (caddr_t),
caddr_t arg, caddr_t *kaddrp, size_t *real_length, ddi_acc_handle_t *handlep);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
PARAMETERS
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:
"small and bold">DDI_DMASequential, 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 callback function indicates how a
caller wants to handle the possibility of resources not being available. If callback is set to DDI_DMA_DONTWAIT, the caller
does not care if the allocation fails, and can handle an allocation failure appropriately. If callback is set to
DDI_DMA_SLEEP, the caller wishes to have the allocation routines wait for resources to become available. If any other value
is set and a DMA resource allocation fails, this value is assumed to be the address of a function to be called when
resources become available. When the specified function is called, arg is passed to it as an argument. The specified call-
back function must return either DDI_DMA_CALLBACK_RUNOUT or DDI_DMA_CALLBACK_DONE. DDI_DMA_CALLBACK_RUNOUT indicates that
the callback function attempted to allocate DMA resources but failed. In this case, the callback function is put back on a
list to be called again later. DDI_DMA_CALLBACK_DONE indicates that either the allocation of DMA resources was successful
or the driver no longer wishes to retry. The callback function is called in interrupt context. Therefore, only system func-
tions accessible from interrupt context are available.
The callback function must take whatever steps are necessary to protect its critical resources, data structures, queues,
and so on.
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.
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 exam-
ple, 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 con-
tent, the driver must invoke ddi_get8(9F) or ddi_put8(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_get8(9F),
ddi_put8(9F), ddi_device_acc_attr(9S), ddi_dma_attr(9S)
Writing Device Drivers
WARNINGS
If DDI_NEVERSWAP_ACC is specified, memory can be used for any purpose; but if either endian mode is specified, you must use ddi_get/put*
and never anything else.
SunOS 5.10 15 Nov 1996 ddi_dma_mem_alloc(9F)